diff --git a/src/docs/Capabilities/agentic-development/spec.md b/src/docs/Capabilities/agentic-development/spec.md index d22b4b0..cf83322 100644 --- a/src/docs/Capabilities/agentic-development/spec.md +++ b/src/docs/Capabilities/agentic-development/spec.md @@ -69,6 +69,7 @@ Applies to any organization that wants a shared project knowledge base and memor - **Deterministic context resolution.** Agents MUST resolve context in layers: system and client policy, user preferences, the repository router, the context-repository freshness gate, repository context, path-scoped repository rules, organization docs, any inherited ecosystem docs, organization memory, then current task context. - **Local-first availability.** The docs and memory repositories SHOULD be available locally in a predictable workspace so agents can read them without relying on search or web access. - **Fresh context before use.** Every canonical context repository MUST be fetched and exactly synchronized with its remote default branch before its contents are read. Dirty, locally ahead, diverged, wrong-branch, or unreachable repositories MUST stop context resolution rather than fall back to stale content. +- **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/` after fetching, which reports commits ahead and behind without changing the working tree. - **Refresh once per session, not once per machine.** The freshness gate MUST run at the start of every agent session, in every runtime. A workspace that was synchronized at some earlier point MUST NOT be treated as current, because elapsed time is not a state the agent can observe. The refresh MUST be idempotent, so that running it when nothing has changed is cheap and silent; a refresh that is expensive or noisy at steady state gets bypassed, and a bypassed gate is worse than none because the workspace still appears synchronized. - **Memory is scoped by horizon.** Memory MUST separate entries that apply organization-wide, entries that apply to one repository, and notes that apply only to the task in hand. Session-scoped notes MUST NOT be shared: they MUST be excluded from the repository's history so that a scratchpad cannot be inherited as knowledge. Making a session note durable MUST be a deliberate act of promotion, which is where the entry is checked for whether it is actually true. - **Durable memory is committed as it is written.** A memory entry MUST be committed and pushed when it is written, one commit per discrete lesson, so that no remembered thing depends on a session ending cleanly. @@ -91,6 +92,7 @@ Applies to any organization that wants a shared project knowledge base and memor - A human or agent can follow `docs/index.md` → Ways of Working → Workflow → the current stage procedure without knowing a file path in advance. - A prompt such as `Review this PR ` reaches the Review procedure directly, while `Make this issue ` reaches Define, without a parallel process definition. - A missing, dirty, locally ahead, diverged, wrong-branch, or unreachable canonical context repository stops discovery before any context index is read. +- A working checkout of a `docs` repository present on disk is not read as canonical context, and a reader can tell a current checkout from a stale one before trusting either. - Updating a standard in `docs` changes the canonical guidance without editing every repository. - Capturing a recurring lesson in `memory` makes it available to later agents working in the same organization. diff --git a/src/docs/Ways-of-Working/Agentic-Development.md b/src/docs/Ways-of-Working/Agentic-Development.md index 216a030..8911e0e 100644 --- a/src/docs/Ways-of-Working/Agentic-Development.md +++ b/src/docs/Ways-of-Working/Agentic-Development.md @@ -40,7 +40,7 @@ flowchart TD memory --> work["Act and follow stage handoffs"] ``` -Refresh is a gate before traversal, not a best-effort background step. After it passes, the indexes are the default discovery mechanism. [Workflow](Workflow.md) owns the process and routes the work to a [stage procedure](Workflow-Stages/index.md); the stage page then points to the standards and artifacts it consumes. A clear prompt such as `Review this PR ` may shortcut directly through the Workflow routing table, but it does not create a second process definition. **Local files never replace central standards — they layer specifics on top.** +Refresh is a gate before traversal, not a best-effort background step. It governs the clones the bootstrap validates, and those are what context is read from — [a working checkout is not a context source](#a-working-checkout-is-not-a-context-source). After it passes, the indexes are the default discovery mechanism. [Workflow](Workflow.md) owns the process and routes the work to a [stage procedure](Workflow-Stages/index.md); the stage page then points to the standards and artifacts it consumes. A clear prompt such as `Review this PR ` may shortcut directly through the Workflow routing table, but it does not create a second process definition. **Local files never replace central standards — they layer specifics on top.** ## Where documentation lives @@ -153,6 +153,21 @@ Each clone carries repository-local git config only, so the workspace never modi The workspace makes the *central* context present locally; the same local-first stance shapes how each working repository is laid out. Repositories are cloned as [git worktrees](Git-Worktrees.md) — one working directory per branch — so a person and an agent, or several agents, can work on multiple issues in the same repository at once without stashing or switching branches. +### A working checkout is not a context source + +Canonical context is read from the clones the gate validated. A **working checkout** of a documentation repository — one cloned in order to change it, rather than to be governed by it — is not a context source, even when it sits on disk and reads perfectly well. The distinction is one of role, not of path: what makes a clone canonical is that the gate proved it current, not where it lives, so this holds for any initiative's `docs` and `memory` repositories and for whatever location a contributor happens to clone them into. + +The reason is that 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 — so the failure is silent and self-confirming. A working checkout of this repository was found 26 commits behind its remote head, clean and zero commits ahead, simply neglected; it predated the Ways of Working restructure and so still carried a page that had been replaced upstream. A task prompt authored from that checkout named the replaced page as the authority for its format, citing a path that had not existed for 26 commits. The agent that received the prompt could not tell, because the page it was sent to opened. + +Whether a given checkout is current is decided by a fetch and a count, neither of which changes anything in the working tree: + +```powershell +git -C fetch origin --quiet +git -C rev-list --left-right --count HEAD...origin/ +``` + +The two numbers are the commits the checkout is ahead of, and behind, the remote head. Both must be zero — the same bar the 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 to the remote head before trusting a word of it. Editing documentation through a working checkout is unchanged by this — the checkout is where a change is written, not where the rules are read. + ## Where this connects - [Git Worktrees](Git-Worktrees.md) — how this framework is implemented on a local machine, so several pieces of work run in parallel.