AGENT-CONTRACT.md

Agent access contract (Claude, Codex, any coding agent)

SourceCompass (repository: mithunyc/SourceCompass; CLI: eb) is a derived map, not authority:

• Architecture docs say what should happen.
• Code shows what is implemented.
• Only runtime evidence shows what actually ran. The map records none.

Where these disagree, the map shows the disagreement instead of resolving it.

Protocol (cheapest first)

1. Identity and freshness, always first node <toolkit folder>/eb.mjs context --in <instance> (run from inside the repo, or pass --repo <path>). Every later answer is checked against that same checkout (yours, or the one named with --repo) and names it; a default instance is never applied inside another repository. Freshness covers the code, the design files and this toolkit's code. For a known file, read it directly: the map is not cheaper there.
   • DIFFERENT_REPOSITORY: stop using the map.
   • STALE… or UNKNOWN: use records only as pointers and read the cited source.
   • FRESH_WITH_UNKNOWNS: recorded files are unchanged, but untracked code was not inspected, or some source files were only partly read at build (syntax errors; the answer names them and their count). Grep source for new callers before trusting impact answers, and read a named file directly.
   • FRESH: continue.
2. Planning or orientation, only if the task needs the big picture
   • eb brief <topic words> (typically ~1–1.5k tokens, not a cap): matching lifecycle items with status, the plan-file status of their ids (read from the repo at HEAD), evidence that changed since the board was written (re-verify it), chains that break, and the files to read. It rebuilds first when the repo has new commits; if it cannot (a leftover lock), it says NOT refreshed.
   • eb map (typically ~700 tokens): modules, gaps, guard mismatches, workflows, and unlinked screens.
3. Specifics, on demand
   • eb q "<product words>": cited records (screen, files, data, tests). Say whether the output was truncated.
   • eb show <ID>: a full screen record. eb show <ID>#ctl:<name>: button → handler → data → table.
   • eb impact <repo/path>: screens, controls, tables and tests that depend on a file.
   • eb place <feature words> / eb arch [<module>] (when the instance has intent/architecture.json): the target module map. place ranks modules by their job, workflows and records, names the best home (it may be a module that does not exist yet), its app and menu placement, what each layer needs (field app, office app, shared logic, backend, sync), the links it must connect through and the placement rules. It flags a CLOSE CALL when two modules match about equally; decide by audience and records. arch alone lists every module, the rules and the end-to-end paths with their first break. When modules carry contracts, eb arch <module> also prints the goal, the done-when checklist, how each item is proven, the gaps with their owners, the SME gate, the shared rules that bind the module and who has concurred. Plan a slice against done-when: you may split or reorder the work, but never weaken it. The architecture is a reviewed design, not proof: if the file has problems, answers end with a WARNING line.
   • eb platform [<port|flow|stage>|decisions|ssot] (when the instance has intent/platform.json): the internal contract a change must go through, the adapter behind it today, how to leave that vendor, the growth stage it belongs to, and the done-when checklist. Never import a vendor SDK outside the adapter the port names.
   • eb module <id> / eb workflow <id>: intent vs implementation, gaps, and the steps with evidence levels. With a workflow catalog, eb workflow <id> gives who does and approves each step, every allowed state change and whether the server must enforce it, and what AI may draft and must never decide. A step-level workflow with the same id takes precedence; eb workflow alone lists the catalog. If the catalog file has problems, catalog answers end with a WARNING line, brief shows one near the top and the viewer shows a warning banner; a step-level workflow answer does not carry it.
4. Before editing, re-check the source. A saved HTML page, an Obsidian note or an earlier answer is an as-of observation. It is not current truth.

Requirements and authority

• Every done-when item and shared rule has an id (<module>.DW<n>, R<nn>, <port>.DW<n>), a revision and a decision status: proposed, approved, rejected or superseded. Implementation status is separate: not assessed, absent, partial, implemented, tested: or observed:.
• An approval binds the id, the revision and the exact text. It comes from the founder or the named human authority, never from a reviewer, a council or a code match. An edited requirement reads as proposed until it is approved again.
• SourceCompass never assigns the next task. Work and authority come from the repository's own plan and process.

After an authorized change

Three kinds of update exist. Keep them separate. A refresh (eb build) re-reads the code and design files. Evidence (eb evidence add) records a check. A proposal (eb propose, then eb proposals resolve) suggests new requirement text. None of them approves anything, and none of them edits the design.

Rebuild once after a change, and keep the last valid map labelled stale if the rebuild fails. Do not re-run a council for every source change.

Evidence rules

• Record what was checked with eb evidence add --req <id> --expect-rev <n> --status PASS|FAIL|NOT_RUN|N/A --layer <layer> --env <env> --source-sha <sha> --receipt <path or URL>, only after separately authorized work.
• A record names one layer of one requirement revision. It shows only that layer. It does not transfer to another revision, so a requirement edited after the check needs new evidence.
• A planned evaluation (eb req <id>) is a plan, not evidence. Never report a plan as a pass.
• Name the layer honestly: a unit test is not a device test. eb evidence list [--req <id>] shows what is recorded.

Findings rules

• eb findings [<id>] traces a review finding to its source document, requirement revision, evaluations, evidence and owner.
• Each finding maps to a requirement revision with a disposition, or is marked superseded, duplicate, non-actionable or unresolved.
• Owners are checked against the repository's plan file. A PROPOSED owner is not registered in the ledger. An owner the plan file does not carry reads NOT FOUND. Do not treat either as an assignment.

Proposal-resolution rules

• Propose a change with eb propose --id <id> --expect-rev <n> --file <new text> --why "<reason>". It is refused when the requirement has moved past the revision you read, and while the design files changed since the last build (run eb build first; a proposal has no --allow-stale).
• A proposal never edits the design. Its owner applies an accepted one, which bumps the revision.
• eb proposals checks each pending proposal against the requirement as the design holds it now and flags it STALE when that revision or text moved on. Two proposals against the same revision are both kept and flagged COMPETING for a person to resolve.
• A person records how a proposal ended with eb proposals resolve --file <proposal file> --as accepted|rejected|superseded --by <who> --why "<reason>". Accepted is refused until the design already holds the exact proposed text at the proposed revision. The record is kept, never deleted (eb proposals --all lists resolved ones). An agent does not resolve its own proposal.

What every answer carries

• Source identity: the instance, the index commit and the repo root commit, the checkout the answer was checked against, and the design-input state, in a one-line header on every answer. HEAD comes from eb context.
• Freshness: FRESH, FRESH_WITH_UNKNOWNS (unknown new callers, or source files the build could only partly read), STALE with reasons, or UNKNOWN, computed when the answer is produced. In CLI answers (q, show, impact, context, brief), a record built from a partly read file says INCOMPLETE. The viewer's record detail carries the same flag on the affected record; standalone cards do not yet. A saved page opened with eb open --no-rebuild on a stale map is a marked copy (brain.stale-view.html) with a STALE banner.
• Citations: file:line for every claim.
• Uncertainty: unknown: lines, evidence fields, and hop confidence (statically traced, branch-insensitive vs further). A near link can sit on a branch the button never takes.
• Truncation: capped lists say so (+N more, truncated: …, list capped). Requirement lines are paged (--page <n>); a long single field, such as a goal or a requirement's full text, is not truncated, so an answer's size is not bounded.

What it never means

• A route guard is not server authorization.
• A table at the end of a chain means a write path exists in code. It does not mean saving works.
• "Declared" does not mean reachable. "Readiness" does not mean inspection PASS. Workflows are DRAFT definitions, not approvals or executable agents.
• ui_presence, connected_readback and production_observation stay not examined until someone observes a real build.

Costs (not free)

• Rebuilding is deterministic, with no model calls. Time grows with repository size; measure it on yours.
• Using the map costs the tokens of its answers: typically about 0.7k for map, about 1–2k per q and about 1–1.5k per brief. These are typical sizes, not limits: a design with long fields gives longer answers.
• Discovery also costs: this contract text, or a skill description.
• Build and upkeep of the toolkit are real engineering costs.
• Do not assume it saves tokens. A session's fixed start-up cost can dominate whatever the map saves. Measure on your own codebase, with the design frozen before the runs, before relying on it for cost.