📖 [Docs]: A working checkout of a docs repository is no longer treated as context

[Marius Storhaug (MariusStorhaug)]

The agentic development guidance now says which copy of the documentation an agent is allowed to read as guidance. Canonical context comes from the clones the workspace bootstrap fetched and validated; a working checkout of a docs or memory repository — one cloned in order to change it — is not a context source, even when it is sitting on disk and opens perfectly well.

Changed: which checkout counts as canonical context

Agentic Development gains a section next to the freshness gate stating the distinction, and the agentic development spec states it as a requirement so the existing fresh-context MUST now names the artifact it governs. The rule is written in terms of role rather than path: what makes a clone canonical is that the gate proved it current, not where it lives, so it holds for any initiative's documentation repository and for whatever location a contributor cloned it into.

The reason is recorded with it, because the reason is what makes the rule stick. A working checkout has no freshness gate — nothing fetches it, nothing fails when it falls behind, and a superseded page in it is still present and still readable. The failure is therefore silent and self-confirming: a prompt written from a checkout 26 commits behind cited a documentation page that had not existed upstream for 26 commits, and the agent that followed it could not tell, because the page it was sent to opened.

New: a check that settles whether a checkout can be trusted

Rather than trusting a checkout, verify it — a fetch and a count, neither of which changes anything in the working tree:

git -C <path> fetch origin --quiet
git -C <path> rev-list --left-right --count HEAD...origin/<default-branch>

The two numbers are the commits the checkout is ahead of, and behind, the remote head, and both must be zero — the same bar the freshness gate applies, where being ahead or diverged fails just as being behind does. Anything else means the checkout is not fit to be read as guidance: read the validated clone instead, or bring the checkout up to the remote head first. Nothing about editing documentation through a working checkout changes — the checkout is where a change is written, not where the rules are read.

---

Technical details

• src/docs/Ways-of-Working/Agentic-Development.md — new ### A working checkout is not a context source subsection at the end of The workspace bootstrap, carrying the role-not-path distinction, the reason, and the verification command. The worktrees paragraph moved above the new heading so it stays part of the parent section rather than being absorbed into the subsection. One clause added to the Architecture refresh-gate paragraph linking to the new anchor, so a reader arriving at the gate learns what it governs.
• src/docs/Capabilities/agentic-development/spec.md — new requirement Working checkouts are not context sources directly after Fresh context before use, keeping RFC-2119 form (MUST be read from gate-validated clones, MUST NOT use a working checkout, MAY verify with the ahead/behind command), plus a matching success criterion. The existing MUST is untouched; this states its scope.
• Scope held to the clarification. The context resolution contract is not reordered, and no tooling guard was added — a guard would have to discover every clone on a machine before it could police one, and the durable fix is that the reader knows which checkout is authoritative.
• Verification command checked against a real stale checkout before documenting it: git rev-list --left-right --count HEAD...origin/main returned 1 29 for a checkout 1 ahead and 29 behind, and 0 0 for a synchronized one. It reports the two counts and leaves the working tree untouched, as Say that a working checkout of a docs repository is not a context source #132 claims. Both surfaces write the ref as origin/<default-branch> rather than hard-coding main, and require both counts to be zero, so the documented check matches the gate rather than a subset of it.
• Copilot review round one raised three points on the snippet — two commands described as one, a hard-coded origin/main against surrounding text that said the default branch may differ, and treating only the behind count as disqualifying. All three are fixed in 26020fd; round two was clean.
• Branch deviates from <type>/<issue>-<slug>: the app's branch-rename tool strips / and refuses a second call, so docs/132-context-source was unreachable and the flat docs-132-context-source was used.
• Implementation plan progress: all four plan items in Say that a working checkout of a docs repository is not a context source #132 completed.

Changed surface	Standards checked	Framework docs checked	Result
src/docs/Ways-of-Working/**	Markdown, Natural Language, Documentation Model	Agentic Development	Aligned
src/docs/Capabilities/agentic-development/**	Markdown, Documentation Model	Spec-Driven Development (RFC-2119 requirement form)	Aligned

• Issue convergence sweep: open issues touching the same pages were reviewed. Reconcile which agent pointer files a repository must carry #121, Reduce AGENTS.md to a route list and every client file to a route #125, and Reconcile the agent files required by Repository Standard with the set Agentic Development defines #140 are closed. Keep pinned PowerShell Gallery module versions current without Dependabot #136 covers .github/scripts/Invoke-PesterSuite.ps1 and dependency updates, with no overlap. No additional issue is fully satisfied by this diff.
• Validation: Test-DocumentationLink.ps1 (114 files, all links resolve), Update-DocumentationIndex.ps1 -Check, markdownlint-cli2 with .github/linters/.markdown-lint.yml, codespell, textlint with .github/linters/.textlintrc (rules confirmed loaded against a probe file), and Invoke-PesterSuite.ps1 (54 tests) all green, matched by green CI.

Related issues

• Fixes Say that a working checkout of a docs repository is not a context source #132

[Copilot]

Pull request overview

This PR clarifies the agentic-development guidance that canonical context must be read from gate-validated clones, and that a working checkout of a docs/memory repo (cloned to edit) must not be treated as an authoritative context source, even if it exists locally and is readable.

Changes:

• Updates the Ways of Working → Agentic Development narrative to explicitly distinguish gate-validated clones vs. working checkouts, including rationale and a verification command.
• Extends the agentic-development capability spec with an RFC-2119 requirement stating that working checkouts MUST NOT be used as context sources, and adds a matching success criterion.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
src/docs/Ways-of-Working/Agentic-Development.md	Adds a new subsection explaining why working checkouts are not authoritative context and how to verify divergence.
src/docs/Capabilities/agentic-development/spec.md	Adds a normative requirement + success criterion to scope the existing freshness gate to gate-validated clones (excluding working checkouts).

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/docs/Capabilities/agentic-development/spec.md:68

• The spec says a reader can verify a checkout with git rev-list ... “after fetching”, but it doesn’t show an explicit fetch command. If someone runs rev-list without fetching first, the remote-tracking ref may be stale and the check can give a false sense of freshness. Consider spelling out the fetch step inline to make the verification procedure self-contained.

- **Working checkouts are not context sources.** Canonical context MUST be read from the context repository clones that passed the freshness gate. A working checkout of a `docs` or `memory` repository — one cloned in order to change it rather than to be governed by it — MUST NOT be used as a context source, whatever path it occupies, because it sits outside the gate: nothing fetches it, and a superseded page in it is readable rather than missing, so the failure is silent. A reader MAY establish whether any checkout is current with `git rev-list --left-right --count HEAD...origin/<default-branch>` after fetching, which reports commits ahead and behind without changing the working tree.