software-factory AGENTS.md

Agent instructions

This repository is a software factory harness. It holds itself to the method it ships.

Before changing anything

1. Read docs/method.md. The layering is not arbitrary and the ordering (L1/L4/L5 first, L0 after the third occurrence of a pattern) is the load-bearing advice.
2. Run sf verify before sf check. A check that no longer fires makes every green run meaningless, and it is the cheaper failure to find.

Hard rules

• A rule needs why and fix. The catalog refuses to load without them, and L4.EVERY_RULE_HAS_A_WHY fails when enforcement and prose come apart. A new rule means a new section in docs/rules.md in the same commit.
• A rule needs a mutation fixture, in every language it claims. Add it to src/fixtures.rs in the same change, then sf fixtures. L5.EVERY_CHECK_HAS_A_MUTATION_TEST fails without one, and sf verify fails both if the fixture does not trip the rule and if it trips it in only some of the languages the rule declares a query for.
• A rule must be pointed at something, or switched off in writing. L5.NO_INERT_RULE fails an enabled lock with no scope, a hazard rule with no tools, a structural rule with no query for any language this repository declares, or an instance whose when names a dependency version the manifest no longer declares. Disabled with a reason in docs/rules.md is honest; enabled and inert is a rule lying about its own coverage.
• Prose may only name commands this sf accepts. L4.RULE_PROSE_NAMES_A_REAL_COMMAND reads every sf ... a rule's statement, why or fix quotes and compares it with the clap definition in src/main.rs, so a fix written against a subcommand that does not exist yet fails the check. Ship the command in the same change, or name the one that exists. A unit test does the same sweep over the whole shipped catalog, including the rules this repository has switched off.
• Never widen a rule to make a finding disappear. If a rule is wrong, argue it in the prose and change it deliberately. Silently loosening a glob is indistinguishable from a fix at the diff level, which is exactly the failure mode this repository exists to catch.
• Never hand-edit a digest or a lock. Run sf lock or sf seal <gate>. That now includes .software-factory/catalog.lock.json, which records the reach of every enabled rule so that L2.CATALOG_ONLY_TIGHTENS can tell an upgrade that strengthened a rule from one that weakened it. Re-locking to clear that finding without reading it is the move the rule exists to make expensive.
• Never weaken the policy to go green. L2.FACTORY_CONFIG_IS_LOCKED will notice the edit and L2.POLICY_ONLY_TIGHTENS will notice its direction. If a rule genuinely needs loosening, that is a pull request about the rule, with the reasoning in the body — not a line inside a change about something else.
• Order of operations after touching the guardrail: sf fixtures, sf docs, sf ratchet, then sf lock last. The lock covers the ratchet, so locking before re-seeding leaves the build red.
• Rule ids are a public contract. Every repository that adopted this tool pinned them. Renaming one is a breaking change.