Make the repository a map a new worker can verify

TL;DR: Give a fresh worker a short route from the customer contract to the relevant code, checks and operating constraints. Keep repository facts reviewable, and make important architecture rules executable so stale documentation becomes detectable.

Where you are. Northstar's threshold task is defined. You are preparing the engineering environment a coding worker will enter without your conversation history.

A reproducible first ten minutes

A new engineer can interrupt a teammate to ask which service owns purchasing policy. A fresh agent session has only the material you expose to it. If the answer lives in an old chat, the worker may inspect the wrong service, invent a command or patch a symptom in the interface.

The repository should contain enough information to reconstruct the intended job. That does not mean putting customer secrets, every design discussion or all historical logs in version control. Keep stable engineering knowledge in the repository and link to controlled operational systems for current credentials and customer records.

For the Northstar fixture, the useful entry map is small:

AGENTS.md                 entry instructions and document map
docs/contract.md           threshold behavior and excluded changes
docs/architecture.md       allowed dependency direction
src/policy.py              candidate implementation
tasks/T-17.json            task identity and acceptance reference

The independent verifier lives outside the candidate checkout, so the worker cannot edit it by accident through its normal task surface. Protecting it from a hostile worker takes more than that: it needs separate execution permissions, which a directory layout cannot provide.

A larger engagement needs additional documents: an architecture map, setup and validation commands, security boundaries, product behavior, active plans, completed decisions and known debt. Give each document an owner or an explicit review trigger; without one, “the repository is the source of truth” turns into a slogan attached to stale files.

Documents that point to observable facts

Suppose docs/architecture.md says the pricing rule is pure: it takes integer cents and returns a boolean. The application may call it, but the rule may not fetch a supplier URL, read a credential or invoke the application. That keeps the policy calculation predictable and stops a repair from picking up unrelated effects.

A diagram makes that dependency direction visible:

Follow the architecture document into the AST check. A model reading the rule does not satisfy it. The check inspects the candidate's syntax tree and rejects imports in this deliberately tiny pure-function fixture. In a real repository, encode the actual allowed dependency graph rather than banning every import.

Static checks have limits: dynamic loading, reflection and generated code can all get past a simple import rule. Use the check for the class of failure it actually covers, and pair it with runtime tests and execution restrictions that fit the threat model. An AST linter is not a security sandbox.

A map, not a dump

A useful map answers “where should I look next?” without repeating every file it links to. The root instructions can say which document defines purchasing behavior and how to obtain a baseline result. The behavior document carries the detailed examples. The architecture document owns dependency direction. The task ledger owns current progress and evidence references.

Duplicating the same rule in six places creates six chances for disagreement. If a rule must appear in multiple surfaces, generate the secondary view or add a consistency check. A hand-maintained count of passing tasks is especially fragile when the actual evidence ledger changes independently.

For an FDE, the map should also separate customer policy from your own implementation choices. “Review at the configured limit” comes from the customer contract; “use a pure function” is an engineering decision. The customer can later change the first without invalidating the second, and recording which is which makes a handoff easier to review.

Do this before moving on

Here is a synthetic readiness packet:

Deliverable: write the smallest repair plan that makes a fresh worker able to establish the baseline. Order it by dependencies.

Worked review. First verify the actual setup and test command, then correct the entry map. Restore the pure policy boundary or explicitly review a proposed architecture change. Remove the hard-coded limit and test a changed limit. Finally replace the completion claim with evidence tied to the candidate revision. Rewriting the progress note first would make the workspace look healthier without proving any behavior.

Change the input. The repository genuinely needs an external policy service. The pure-function architecture is now incomplete. Do not hide the new call inside the predicate. Add a separate adapter with timeouts, authentication and an explicit “policy unavailable” outcome, and pass an already validated policy value into the calculation. Update the architecture decision and its checks together.

A good repository map saves repeated explanation, but its larger benefit is that contradictions become cheap to find before they reach a customer.

Go deeper

• Is this repo agent-ready?: Use the interview scenario to challenge a repository readiness claim.
• Audit trails: Distinguish recorded evidence from an editable narrative about what happened.
• Repository instruction research: Read the evidence before assuming more repository instructions always improve results.

Key takeaways

• Give a fresh worker a short route to behavior, architecture and checks.
• Keep current operational secrets outside the repository knowledge map.
• Translate important architecture constraints into checks with stated limits.