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.

Make the first ten minutes reproducible

A person can interrupt a teammate to ask which service owns purchasing policy. A fresh agent session has only the material you expose. If the answer lives in an old chat, the worker may inspect the wrong service, invent a command or repair 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. That placement prevents accidental editing through the normal task surface. Strong protection from a hostile worker also requires separate execution permissions; a directory layout alone cannot provide it.

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. Otherwise “the repository is the source of truth” becomes a slogan attached to stale files.

Make documents 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. This keeps a policy calculation predictable and prevents the repair from acquiring unrelated effects.

A diagram makes that dependency direction visible:

Follow the architecture document into the AST check. The rule is not satisfied merely because the model read 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 evade a simplistic import rule. Use the check to catch the failure class it actually covers, then combine it with runtime tests and execution restrictions appropriate to the threat model. Do not call an AST linter a security sandbox.

Distinguish a map from a dump

A useful map answers “where should I look next?” It does not repeat every linked file. 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 also needs to distinguish customer policy from your implementation choice. “Review at the configured limit” comes from the supplied customer contract. “Use a pure function” is an engineering decision. A future customer can change the first without automatically invalidating the second. Recording that distinction 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 establishing 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. Introduce a separate adapter with timeouts, authentication and an unavailable-policy outcome; pass an already validated policy value into the calculation. Update the architecture decision and its checks together.

A good repository map reduces repeated explanation. Its stronger contribution is making contradictions cheap to discover before they become a customer-facing effect.

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.