Make Threat Modeling and Reuse a Design Step, and Give Review a Design Lens #2516

Problem

#2507 landed "Trust Boundaries and Hardening Effort", which tells a session and a reviewer how much hardening an input earns. Two gaps remain, and both burn the same budget the rule exists to save.

1. The rule is applied at review and triage, not at design. Nothing asks a session to model the threat before it writes code. So a change is built first, hardened by habit, and the hardening is declined afterwards, one review round at a time. The rule saves the issue but not the work that preceded it.
2. Nothing asks a session to reuse before it builds, or to consolidate once a pattern repeats. The only reuse rule is the "Contracts state what, not how, and favor reuse" principle, and it is scoped to the workflow contract. In HomeAutomation-Config, file manipulation and secret reading each carry careful handling, and sessions re-implemented that handling per script rather than calling one shared helper. The maintainer had to ask for consolidation repeatedly. The hub shows the same shape. Codify: Let the Real Operation Be the Check, and Close a Defect Class Through One Primitive #2431 records a FIFO-blocks-the-read defect fixed three times at three sites before read_regular_file() closed the class. Canonicalize -Dir in bootstrap.ps1 Before Refusing a Drive or Share Root #2495 asks for a canonicalizing directory check in bootstrap.ps1 that host-setup/menu.ps1 already does.

Neither review lens looks for this. fleet-code-review "Review the Change" lists correctness, regressions, security, compatibility, error handling, concurrency, resource lifetime, tests, and contract drift. It has no design dimension, and its "omit pure preferences" item reads a duplication finding as one. local-strict-review's brief adds coercions, races, and platform differences, all hardening lenses. So a correct diff that duplicates an existing helper, or adds a fourth per-site check for a class already seen, passes both reviews clean.

Threat modeling and reuse are ordinary engineering practice, not a hub convention, so they belong with the foundational rules every session reads, not in one repository's memory.

Proposed change

1. A GOVERNANCE.md section on design, beside "Trust Boundaries and Hardening Effort", routed from the AGENTS.md table. Working title "Design Before Code". It states:
   • Model the threat before the first edit. Name the change's inputs, the class of each under "Trust Boundaries and Hardening Effort", and the deployment the code runs in. That model sets the hardening budget, so hardening the model does not call for is not written, rather than written and then declined.
   • Reuse before building. Search this repository and the hub for an existing primitive before adding one, and extend it rather than add a sibling that does almost the same thing.
   • A defect class seen a second time gets one primitive, and every site moves onto it. A per-site check repeats its own platform and edge-case defects at every site, as Codify: Let the Real Operation Be the Check, and Close a Defect Class Through One Primitive #2431 measured. This absorbs Codify: Let the Real Operation Be the Check, and Close a Defect Class Through One Primitive #2431's second lesson.
   • Complexity is a cost that needs a reason. Code that answers no requirement and no realistic threat is removed, not maintained.
2. Codify: Let the Real Operation Be the Check, and Close a Defect Class Through One Primitive #2431's other two lessons go to CODESTYLE.md General, since they are code-level: let the real operation be the check rather than a prediction of it, and a failure message states the error, the path, and the remedy without describing the state the failure left.
3. Widen the Foundational Principles reuse bullet from the workflow contract to all code, pointing at the new section.
4. Give review a design lens.
   • fleet-code-review "Review the Change" carries the new section as a generated include, the way it carries "Trust Boundaries and Hardening Effort", and adds design to its criteria: logic an existing helper already provides, a per-site fix for a class already seen elsewhere, and hardening or abstraction the threat model does not justify. A finding backed by the new section is not a preference.
   • local-strict-review's brief asks the reviewer, for each new function or helper the diff adds, to search the repository for an existing one doing the same job, bounded to that search, and to report a consolidation finding or an over-hardening finding alongside its correctness findings.
   • A consolidation finding outside the diff is filed as one issue naming every site, not fixed in the change under review.
5. Surface the design step at the moment it applies. agent-conduct gains a trigger at "about to design or start implementing a change", pointing at the new section, so the threat model happens before the code rather than in review.
6. A repository names its shared primitives. OPERATIONS.md, beside the trust boundaries it already lists under Configuration Layout, names the helpers that own file I/O, secret reads, and any other class the repository has consolidated. A session then finds the primitive without searching for it.
7. The re-triage of the open hardening backlog moved to Re-Triage the Open Hardening Backlog Against the Trust-Boundary and Design Rules #2517, since closing issues on judgment, and working the guard's attended-only tree, is the maintainer's.

Done when

• The new section is in GOVERNANCE.md, routed from AGENTS.md, and Codify: Let the Real Operation Be the Check, and Close a Defect Class Through One Primitive #2431's lessons are in their homes, closing Codify: Let the Real Operation Be the Check, and Close a Defect Class Through One Primitive #2431.
• fleet-code-review and local-strict-review carry the design lens, and agent-conduct surfaces the design step.
• OPERATIONS.md's template asks for the shared-primitive list.
• Downstream consolidation, such as HomeAutomation-Config's file and secret helpers, is filed in each repository by its own session after the carried change reaches it on resync.

🤖 Generated with Claude Code