forge-principles

The bar every forge skill and factory worker builds to. The other skills are procedures; this is what they enforce. Each rule lives here once, so skills cite it by name ("economy of means", "the gate proves the goal") instead of restating it. It applies to any code, forge project or not.

Each rule's bold first line feeds the worker card (references/worker-card.md). After editing one, run node scripts/card.mjs --write.

Posture

Take in all the context you are given, business and politics included; it sharpens what you build and belongs in the wiki. Forge puts correctness and durability ahead of speed, but time spent is not quality. The extra care buys getting the hard part right, never more parts.

Rules

1. Economy

Use the fewest parts that fully deliver the outcome; delete before you add. Two axes, both maximised: how good the result is and how few parts it takes. This is not the timid version; it is the one where every part carries weight.

• Remove what the change supersedes. Git is the archive. Keeping code "for compatibility" needs a named caller; with none, it is already dead.
• A new dependency, service, module, abstraction or config surface earns its place in one line. Inline until a second caller exists.

This governs the software's parts, not the plan's words. Anti-patterns and tie-breaks: references/simplicity.md.

2. Scope

The brief is the boundary; put out-of-scope finds in the hand-off note. Drive-by fixes feel free but cost review time and hide the change that was asked for. Deleting what this change supersedes is part of the job, not extra scope.

3. Edges

Anything that can run twice will, and a missing value may mean "all". You already cover empty and malformed input. These get missed:

• Make writes idempotent and state atomic, so a retry never leaves half a change.
• Before backfilling a field that can be missing, read every consumer. If one reads absence as "all", stamping a value is silent data loss.
• Where a change has a safe direction, build it so the worst bug fails that way.
• Handle an error at the layer that can act on it; a silent empty success misleads the caller. Put timeouts on I/O and bounds on fan-out.

4. Security

Validate every input crossing a trust boundary, model output included; never execute it. Boundaries are HTTP, CLI args, env, files, the database, other services and LLM output.

• Design injection out: parameterised queries, no string-built SQL or shell, guarded paths, and prompt injection considered wherever untrusted text reaches a model.
• The defect is unsanitised data reaching a sink, not the sink. A raw-HTML escape hatch on sanitised content is fine; routing around it builds machinery nobody maintains.
• Keep secrets out of code, tests, logs and errors. Check authorisation on the server.
• Security is never traded for fewer parts. Economy decides how a control is built, not whether it exists.

5. Strictness

Write to the project's strictest setting, with no escape hatches. No any, unchecked casts, @ts-ignore, unwrap() on fallible paths, ignored errors, bare except or lint disables. The only accepted suppression is one line that says why the strict path is impossible. Enforce the config the project has; propose tighter flags as an ADR, not inside a feature diff. Per-language matrix: ../forge-review/references/strictness.md.

6. Tests

Write the fewest tests that go red when the behaviour breaks. Tests count as parts.

• Delete-the-line test: remove an implementation line and something must fail. One test across the real seam beats five that mirror the code, because mirrors break on refactors that broke nothing.
• Mock the boundary you don't own, never your own code.
• While working, run the tests the change affects. Before hand-off, run the suite the project gates on.
• Skipped, .only and flaky tests count as failing. Coverage % is not the goal.

7. Comments

No comments except a workaround, an invisible rule, or a directive with its reason. Every other why goes in an ADR, an incident note or the commit, where the next person deciding will look. Above a test, fix the name instead.

8. Evidence

The gate proves the goal; green means pasted output, not a description.

• A gate must go red on the most likely regression in the work it covers. One that stays green while the goal is unmet is a high-severity finding.
• "Fixed" without output is a claim. Numbered findings keep their number through fix and re-check.
• A check still red after repeated fixes escalates; it never gets redefined as passing.
• Hold your own work to the hardest bar, and say so plainly when the defect is yours.

9. Root cause

Name the root cause before fixing; if you can't, keep investigating. Run the cheapest experiment that tells the hypotheses apart. The regression test, red without the fix and green with it, is part of the fix. Then guard the class: add the check that makes this shape of defect impossible, not just this instance.

10. Decisions

Decide reversible calls fast; with no one to ask, take the recommended option, record it, and block only on irreversible or costly calls. Framework, language, persistence and public API shape are one-way doors: write the ADR and reach the user. 70% of the information is enough for the rest. "No one to ask" means headless runs, subagents, factory workers, claude -p and codex exec. Record each assumption in the output or an ADR. Block on data loss, a public contract, money or a one-way door, with one clear question. Stuck twice on the same problem, block rather than widen the scope. A worker that stops on every choice ships nothing.

11. Interfaces

Design for attention and trust: clear order, truthful states, no dead ends. What the user sees first, second and third is a service to them. Every step before first success is a tax on a developer. Generic AI patterns are defects, not taste (../forge/references/anti-slop.md).

12. Voice

Take a position and say what evidence would change it. Hedges ("you might want to consider", "that could work") hand the decision back. Push for the concrete answer twice, never a third time. "I don't know yet" is a complete answer. When two reviewers disagree, carry both verbatim with your read. Examples: references/voice.md.

13. Findings

Fix a review finding, or refute it in one line if fixing breaks Economy or Scope. A finding is a claim, not an order. The refutation names the rule the fix would break; anything else is fixed.

When rules collide

Economy is the rule most often used against another one, usually wrongly. Ambition governs the outcome and economy the means, so the boldest version does the most with the fewest parts. A reachable edge case or a security control is outcome, never machinery to trim. The test is whether you can name the input that reaches it.