Product direction: the architecture contract for agent-written code #106

Summary

systemap keeps the people who own a system in charge of its architecture while agents write the code. Agents do the work. People hold the intent and make the decisions.

Read this issue first if you are new to the project. The linked issues are the parts.

The people

The three parts of the product

• The contract: the boundaries (rules, invariants, permitted flows), each with a reason. The agent writes it. A change to it appears separately in PR review.
• The map: a description of the code. The agent builds it and keeps it current.

People do no map work. They take part only in normal PR review.

• The evidence: digests, citations, and reviews. Each claim shows its level: established from facts, examined by an agent, or unknown. Unknown is never a pass.

Rules for the product

1. Attention is the scarcest resource. For anything that a person sees, precision is more important than recall.
2. The agent writes each rule with a plain-language reason. systemap checks the part that the facts can show, and says which part it cannot check.
3. A decision by a person stays a decision until the facts behind its reason change.
4. Keep the mental model of the team current, not only the CI result.
5. Trust must match the evidence. Do not say "verified" for a claim that an agent examined.
6. A CI block gives the rule, its reason, and the usual correct change.
7. The agent builds and proposes. The person decides only in PR review.

How we know that it works

• Interruptions for each owner each week, and the share that were worth it.
• The time for a reviewer to state the architectural effect of a PR, and whether the reviewer finds a planted break.
• Developer comprehension of the current architecture after weeks of agent-written changes.
• The share of contract approvals done in less than 10 seconds (a warning sign).
• Breaks caught compared with an agent alone and with an import linter.
• Teams that did not build systemap still use it after 60 days.

Parts

• Separate the contract from the map #98 Separate the contract from the map
• A PR summary of the architectural effect, for reviewers #99 A PR summary of the architectural effect, for reviewers
• Start a new team with a contract proposed from its current code #100 Start a new team with a contract proposed from its current code
• Check the contract before the agent writes code #101 Check the contract before the agent writes code
• Show the assurance level of each claim #102 Show the assurance level of each claim
• Planted-task comparison: agent alone, agent with rules, agent with systemap #104 Planted-task comparison: agent alone, agent with rules, agent with systemap
• Test that a new language needs no change to shared code #105 Test that a new language needs no change to shared code

Not in this direction

• Proof of what the program does when it operates.
• A required model provider. Jev and OpenAI stay optional.
• Routine questions to people.
• Diagram features that do not help the people above.

Uncertainty

This direction is a hypothesis. The planted-task comparison is the first test. If an import linter with an agent catches the same breaks, the value must come from review and comprehension, and this plan must change.

Which issue to pick

Each issue has a priority label. Pick the lowest number first.

• P0, do first: none open. A flow review stays current after the cited code changes #49 (a flow review stays current after a code change) is repaired.
• P1, next: judgement --order-by-drift sends data to Jev when the selected provider is OpenAI #118 (PR Use the selected provider for drift ordering #121 by pdd27673 is open). (Decision workflow: let the agent finish its work without a person #89, Recorded answers: stop needless reopening, and keep one migration path #90, Claude Code plugin hooks: three defects #95, Documentation corrections #97, Separate the contract from the map #98, A PR summary of the architectural effect, for reviewers #99, Show the assurance level of each claim #102, Keep test files out of architecture questions and answer evidence #114, and Map files that link out of the repository are read #120 are repaired.)
• P2, after P1: Planted-task comparison: agent alone, agent with rules, agent with systemap #104 (the planted-task comparison, which waits for a decision to start), Start a new team with a contract proposed from its current code #100, Check the contract before the agent writes code #101, Run the 2.0.0 maintenance replay #53, Test that a new language needs no change to shared code #105, TypeScript adapter: two possible accuracy problems #91, Measure delta and live on a large repository #92, On Windows, a folder that changes to a link is not found #67.
• P3, when convenient: Release process: publish script and facts format rule #93, Pre-commit hooks can pass with no measurement #94. Contributor tooling.

Moonshots (label moonshot, after the P0 results)

• Declare a target architecture, and let agents bring the code to it #107 Declare a target architecture, and let agents bring the code to it
• Architecture history linked to agent sessions #108 Architecture history linked to agent sessions