Repository navigation
Clean context rot from agent-facing docs - #131
Merged
Merged
Conversation
Currency fixes, verified against main at 11be8d4: - CLAUDE.md: ADR-0017 entropy exemption noted in the scanner rule, ADR-0016/0017 added to canonical references, sprint pointer moved to the archive, the '< 5 min' claim updated to its CI-verified status, examples/ no longer a 'placeholder until week 9'. - AGENTS.md: regenerated as an exact mirror of CLAUDE.md (it had forked: missing the worktree-discipline section, pre-ADR-0003 'not yet reconciled' strategy framing, 'compose lands in week 11'). - overview.md security model: scanner is enforced (was 'lands in PR-3'), ADR-0012 peer auth and issue #118 limits described, ADR-0017 noted. - README + mvp-spec: phantom 'branch'/'checkout' CLI commands removed or marked not-shipped; venv bootstrap described correctly; demo README updated for the self-contained run-demo.sh and runtime autodetection. - roadmap.md: shipped weeks 1-11 collapsed from unchecked checkboxes to per-week shipped summaries; Status line now says historical record. Archive moves (verbatim, diff-verified): docs/product/sprint-2026-05-20.md and docs/verification/agent-sdk-schema.md to docs/archive/. Status banners added in place on the 2026-05-21 agenticd analysis (closed via #34) and the a8 reverse-migration plan (accepted ADRs link into them, so they stay put). Claude-Session: https://claude.ai/code/session_01V9TtRvFnDS4eGkcxZhnyf9
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates agent-facing documentation to eliminate stale or incorrect claims that could mislead automated assistants and humans, aligning key docs (README, CLAUDE/AGENTS, architecture/product docs, and demo docs) with the current shipped v1.0 behavior and CI-verified demo discipline.
Changes:
- Refreshes CLI, demo, and roadmap claims to match what actually shipped (including removing nonexistent CLI subcommands from the MVP spec/README and documenting the demo’s self-bootstrapping venv + CI “demo” job).
- Rewrites roadmap checklists into shipped-week summaries and introduces
docs/archive/for executed plans/memos to reduce “open work” ambiguity. - Updates security model docs to reflect shipped socket peer auth + secret-scanner enforcement + sanctioned entropy exemption.
Reviewed changes
Copilot reviewed 10 out of 12 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Updates project status and corrects shipped CLI command list; clarifies demo setup (venv bootstrapped by run-demo.sh). |
| examples/langgraph-rollback/README.md | Simplifies demo quickstart; documents autodetected container runtime + idempotent venv bootstrap. |
| docs/product/roadmap.md | Converts roadmap into a historical record with shipped summaries; points executed sprint plan to docs/archive/. |
| docs/product/mvp-spec.md | Corrects MVP CLI subcommands to match shipped surface; notes branch/checkout didn’t land in v1.0. |
| docs/product/demo-scenario.md | Adds CI-verification statement for the “<5 min from clone” demo claim. |
| docs/plans/a8-reverse-migration/feature-implementation-plan.md | Adds “EXECUTED” banner to prevent treating the plan as active work. |
| docs/ops/2026-05-21-agenticd-architectural-analysis.md | Adds “CLOSED” banner and points readers to main as source of truth while preserving ADR-linked anchors. |
| docs/archive/sprint-2026-05-20.md | Archives the executed hardening sprint plan verbatim for audit/history. |
| docs/archive/agent-sdk-schema.md | Archives a schema verification checkpoint doc supporting the ADR trail. |
| docs/architecture/overview.md | Updates security model section to reflect shipped peer auth, socket limits, and enforced secret scanning + exemptions. |
| CLAUDE.md | Refreshes agent standing context (CI-verified demo claim, entropy exemption rule, ADR index pointer). |
| AGENTS.md | Brings AGENTS in sync with current standing context (worktree discipline, demo/CI claims, updated references). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - [`docs/adr/0001-architecture-foundations.md`](docs/adr/0001-architecture-foundations.md) — foundational decisions | ||
| - [`docs/adr/0001-architecture-foundations.md`](docs/adr/0001-architecture-foundations.md) — foundational decisions (Decision 7 amended by ADR-0003) | ||
| - [`docs/adr/0002-substrate-and-supercommit.md`](docs/adr/0002-substrate-and-supercommit.md) — substrate, extended Commit, 2PC staging order | ||
| - [`docs/adr/0003-claude-agent-sdk-integration.md`](docs/adr/0003-claude-agent-sdk-integration.md) — first non-LangGraph integration target (the first platform-partner integration / Claude Agent SDK), layered session-manifest path |
Member
Author
There was a problem hiding this comment.
Fixed in bc216ea — AGENTS.md is regenerated as an exact mirror of the corrected CLAUDE.md.
| @@ -146,6 +146,7 @@ When in doubt, these are authoritative: | |||
| - [`docs/adr/0003-claude-agent-sdk-integration.md`](docs/adr/0003-claude-agent-sdk-integration.md) — first non-LangGraph integration target (the first platform-partner integration / Claude Agent SDK), layered session-manifest path | |||
Member
Author
There was a problem hiding this comment.
Fixed in bc216ea — the bullet now says real-time atomic sidecar per ADR-0004, manifest-export only as the documented escape hatch.
The external portfolio assessment recommends a clearer maturity vocabulary until release artifacts and external use exist: - git.agentic: 'v1.0 shipped' becomes 'open-source MVP complete, production validation in progress' (site badge, status, index card, README); the phantom 'branch' CLI entry drops off the site's list too. - Sentinel: 'full security layer built' is paired with pre-1.0 / packages-not-yet-published everywhere it appears. - src-control: 'per-file permissions' becomes 'recipient-encrypted paths' (path-level permissions stay as the stated long-term thesis); the in-RAM claim gains the tool-materialization caveat; status names the unaudited crypto and missing TLS as design-partner-alpha bounds. Astro build verified (4 pages). Claude-Session: https://claude.ai/code/session_01V9TtRvFnDS4eGkcxZhnyf9
Copilot review on PR #131: the canonical-reference bullet still described ADR-0003 as the 'layered session-manifest path' — Decision 2 committed to the real-time atomic sidecar (ADR-0004), with manifest-export only as the escape hatch. Fixed in CLAUDE.md, AGENTS.md regenerated as its mirror. Also fixes the demo-smoke failure this PR surfaced: step 12 piped 'agentic log --oneline' through 'head -10', and whenever the history exceeds 10 entries (LangGraph step count varies per run) head closes the pipe early and the Rust CLI panics on SIGPIPE with exit 101. Use the CLI's own --limit 10 instead of a pipe. Claude-Session: https://claude.ai/code/session_01V9TtRvFnDS4eGkcxZhnyf9
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 15 out of 17 changed files in this pull request and generated 2 comments.
Comments suppressed due to low confidence (1)
AGENTS.md:150
- This section header is empty in the rendered Markdown, so it reads like something failed to import. If there are no imported instructions in this repo, add an explicit note (or remove the header) so readers don’t assume content is missing.
## Imported Claude Cowork project instructions
Comment on lines
+70
to
+72
| ## Worktree discipline | ||
|
|
||
| Any time you are about to modify, create, or delete files in this repo you MUST do the work in a git worktree under `.worktrees/<slug>/`, never directly in the main checkout. Toni edits this repo in parallel on the same machine, so `HEAD` in the main checkout can move under an agent at any moment — see [[feedback_check_git_state_before_amend]]. Worktrees isolate agent edits from that movement, keep each conceptual change on its own branch, and make abandoned attempts cheap to discard. |
| ### In scope | ||
|
|
||
| 1. **CLI tool `agentic`** — `init`, `commit`, `log`, `checkout`, `rollback`, `diff`, `branch`. | ||
| 1. **CLI tool `agentic`** — `init`, `commit`, `log`, `status`, `diff`, `rollback` (plus `ping`, `resolve`, `cat-object`). *As shipped:* the originally-specced `checkout` and `branch` subcommands did not land in v1.0 — branch refs exist in the daemon and the SDK's checkpointer uses per-thread branches, but branch manipulation from the CLI is v1.1 work. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
A doc audit (2026-07-10) found stale facts and executed-plan rot in the docs agents read every session — the kind of thing that makes an agent argue with correct code. Worst finds: AGENTS.md had silently forked from CLAUDE.md (missing the worktree-discipline rules entirely, still claiming the demo compose stack "lands in week 11"); overview.md's security section said the secret scanner "is not yet machine-rejected" (it shipped 2026-05-21 and is enforced) and that the socket has no authentication (ADR-0012 peer auth shipped); README and mvp-spec advertised
branch/checkoutCLI commands that don't exist; and CLAUDE.md's scanner rule predated ADR-0017, so an agent following it would treat yesterday's entropy exemption as a violation.What
mainat the time of writing, including the now CI-verified "< 5 min from clone" demo claim (thedemojob runs it in under 2 minutes on a fresh runner).- [ ]boxes (which read as not-done) to per-week shipped summaries; only the open post-launch design-partner track keeps checkboxes.docs/archive/introduced: the fully-executed 2026-05-20 sprint plan and the week-6 verification memo moved there verbatim (diff-verified). The 2026-05-21 agenticd analysis and the a8 plan stay in place (accepted ADRs deep-link into them) with CLOSED/EXECUTED banners so they can't be read as open work.Docs-only; no code changes. Relative links in all touched files verified.
https://claude.ai/code/session_01V9TtRvFnDS4eGkcxZhnyf9