bchanot/claude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(doc-syncer): scope to public docs, .claude read-only, conventions + clean mode

Browse Source 
Rewrite the doc-syncer agent so it only ever targets public docs and
treats .claude/ (and CLAUDE.md) as read-only context.

- Add normative CONVENTIONS section: Standard-Readme, Diátaxis doc-type
  separation, Keep a Changelog + SemVer, Conventional Commits.
- Add CONTEXT SOURCES section: .claude/ and CLAUDE.md may be read for
  project context but are never modified, never sync targets, and their
  content is never copied into a public doc.
- Drop .claude/{tasks,audits,memory} and CLAUDE.md from discovery,
  per-doc analysis, tagging, patches, and the report. Remove the STEP 4
  blocks that audited TODO.md / audits/*.md / decisions-learnings-blockers.
- Fix sync scope to the modifiable targets: README, INSTALL, CONFIGURE,
  USAGE, DEPLOY, CONTRIBUTING, CHANGELOG, SECURITY, ARCHITECTURE, LICENSE,
  docs/**. Add SECURITY.md and ARCHITECTURE.md analysis stanzas.
- Make the README template lean (Standard-Readme order): drop Status and
  Project layout; forbid roadmap/todo/internal-state; README only links
  to the Diátaxis docs, never duplicates them.
- Add CLEAN mode (triggered by a 'clean' arg): propose removal of
  out-of-convention sections and copied .claude/ content from existing
  public docs, HUMAN-tagged and gate-validated.
- Conserve: stack detection, 14-section DEPLOY gate, validation gate,
  AUTO/HUMAN tagging, never-invent rule, AUTO MODE (input contract
  'auto-mode scope:' unchanged, so callers are unaffected).
- Preserve frontmatter name/tools/model; update description to reflect
  the public-doc scope and 'reads .claude/ for context only'.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Bastien Chanot 2026-06-18 17:46:48 +02:00
parent f39cc1b954
commit edff761fc4
1 changed files with 280 additions and 230 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

510
agents/doc-syncer.md
View File

@ -1,6 +1,6 @@
--- ---
name: doc-syncer name: doc-syncer
description: Detect stale documentation by cross-referencing git history against the project's actual doc layout. Auto-discovers root docs, docs/**, and .claude/{tasks,audits,memory}/. Stack-aware deploy-doc gating (DEPLOY.md only when non-trivial). Enforces README presence. Audit, report, patch. Supports full audit and automatic (silent) mode. description: Detect stale PUBLIC documentation by cross-referencing git history against the project's doc layout (README, INSTALL, CONFIGURE, USAGE, DEPLOY, CONTRIBUTING, CHANGELOG, SECURITY, ARCHITECTURE, LICENSE, docs/**). Conventions enforced: Standard-Readme, Diátaxis, Keep a Changelog + SemVer, Conventional Commits. Reads .claude/ for context only, never modifies or exposes it. Stack-aware deploy-doc gating (DEPLOY.md only when non-trivial). Enforces README presence. Audit, report, patch. Full audit, clean mode, and automatic (silent) mode.
tools: Read, Write, Edit, Bash, Grep, Glob tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet model: sonnet
--- ---
@ -8,52 +8,92 @@ model: sonnet
# DOC SYNCER # DOC SYNCER
## GOAL ## GOAL
Keep documentation in sync with code. Detect drift, report it, Keep PUBLIC documentation in sync with code. Detect drift, report it,
patch what can be patched automatically. Auto-discover what doc patch what can be patched automatically. Auto-discover what public doc
the project has and what it actually needs based on stack and the project has and what it actually needs based on stack and deploy
deploy complexity. Never invent content -- only reflect what complexity. Never invent content -- only reflect what changed in code.
changed in code. `.claude/` is context, never a target (see CONVENTIONS).
## REQUEST ## REQUEST
$ARGUMENTS $ARGUMENTS
--- ---
## CONVENTIONS
Normative. Every doc produced or patched MUST follow these. Apply at
audit, report, and patch.
- **README — Standard Readme** (RichardLitt/standard-readme). Fixed
section set + order (STEP 5). Lean: no internal-state content.
- **Doc types separated — Diátaxis.** One concern per file; README only
links, never duplicates a delegated body:
- `INSTALL.md` = how-to (get it installed / running locally).
- `CONFIGURE.md` = reference (every config option, generated from the
real schema — `.env.example`, config struct/parsing — never invented).
- `DEPLOY.md` = operational how-to (production deploy).
- `USAGE.md` = tutorial + reference (use the running app / API / CLI).
- **CHANGELOG — Keep a Changelog** format + **SemVer** versioning.
- **Commits — Conventional Commits** (`type(scope): subject`). Used when
referencing commits and when deriving CHANGELOG entries.
## CONTEXT SOURCES — `.claude/` AND `CLAUDE.md` ARE READ-ONLY
- doc-syncer **MAY read** `.claude/tasks/`, `.claude/audits/`,
`.claude/memory/`, and `CLAUDE.md` purely to **understand** the project
— architecture decisions, planned-vs-delivered features, constraints,
project context — so it writes better PUBLIC docs.
- doc-syncer **NEVER modifies** any file under `.claude/` or `CLAUDE.md`.
They are NOT sync targets: absent from `DOC_FILES`, from AUTO/HUMAN
tagging, from patches, from CREATE/REMOVE proposals, and from the
report's target list.
- doc-syncer **NEVER copies** `.claude/` content into a public doc. No
TODO, roadmap, decisions, learnings, journal, or audit text reproduced
in README / INSTALL / CONFIGURE / USAGE / DEPLOY / docs/. The content
**informs** the writing; it is never transcribed.
---
## MODE DETECTION ## MODE DETECTION
Parse `$ARGUMENTS`: Parse `$ARGUMENTS`:
- **AUTO MODE** — `$ARGUMENTS` starts with `auto-mode scope:` - **AUTO MODE** — `$ARGUMENTS` starts with `auto-mode scope:`
Jump to AUTO MODE section. Jump to AUTO MODE section.
- **FULL AUDIT** — anything else (empty, file list, description) - **FULL AUDIT** — anything else (empty, file list, description).
Run the full audit workflow. Run the full audit workflow.
- **CLEAN MODE** — set when `$ARGUMENTS` contains the token `clean`.
Modifier on FULL AUDIT: run the full audit AND propose removal of
out-of-convention content already present in public docs (see
STEP 6.5). Not a separate flow.
--- ---
## FULL AUDIT ## FULL AUDIT
### STEP 1 — DISCOVER PROJECT DOC LAYOUT ### STEP 1 — DISCOVER PUBLIC DOC LAYOUT
Auto-detect what doc files actually exist. No fixed list. Auto-detect which public doc files exist. Fixed candidate set =
the modifiable targets only. `.claude/**` and `CLAUDE.md` are context
sources (read-only), never discovered as targets.
```bash ```bash
# Standard root doc files (only those that exist) # Public root doc targets (only those that exist)
for f in README.md CLAUDE.md INSTALL.md CONFIGURE.md USAGE.md \ for f in README.md INSTALL.md CONFIGURE.md USAGE.md DEPLOY.md \
DEPLOY.md CONTRIBUTING.md CHANGELOG.md SECURITY.md \ CONTRIBUTING.md CHANGELOG.md SECURITY.md ARCHITECTURE.md \
CODE_OF_CONDUCT.md ARCHITECTURE.md ROADMAP.md LICENSE; do LICENSE; do
[ -f "$f" ] && echo "$f" [ -f "$f" ] && echo "$f"
done done
# docs/ tree # docs/ tree (public docs)
find docs -name '*.md' 2>/dev/null find docs -name '*.md' 2>/dev/null
# .claude/ project-state docs
find .claude/tasks .claude/audits .claude/memory \
-name '*.md' 2>/dev/null
``` ```
Store as `DOC_FILES` (existing) and `DOC_MISSING` (canonical names Store as `DOC_FILES` (existing targets) and `DOC_MISSING` (canonical
absent — at minimum: README.md). names absent — at minimum: `README.md`).
> `.claude/` and `CLAUDE.md` MUST NOT appear in `DOC_FILES`. Read them
> later only for context, never list them as drift targets.
### STEP 2 — STACK & DEPLOY ANALYSIS ### STEP 2 — STACK & DEPLOY ANALYSIS
@ -121,98 +161,92 @@ For each file in `DOC_FILES`:
4. Cross-reference each change against doc content. 4. Cross-reference each change against doc content.
5. **Feature delta detection:** 5. **Feature delta detection:**
- New entry points / routes / commands / skills / modules in - New entry points / routes / commands / modules in code, no doc
code, no doc section → `[ADDED]`. section → `[ADDED]`.
- Doc references functions / files / endpoints / features - Doc references functions / files / endpoints / features absent
absent from code → `[REMOVED]`. from code → `[REMOVED]`.
- Use `git diff --stat` between last doc edit and HEAD to - Use `git diff --stat` between last doc edit and HEAD to identify
identify added (`A`) / deleted (`D`) files. added (`A`) / deleted (`D`) files.
May read `.claude/` for context here (e.g. a decision explaining WHY a
feature was added) — to write accurate doc text, never to copy it.
### STEP 4 — ANALYSIS PER DOC TYPE ### STEP 4 — ANALYSIS PER DOC TYPE
Apply doc-specific checks. Skip docs not in `DOC_FILES` (handled Apply doc-specific checks. Skip docs not in `DOC_FILES` (handled
by STEP 5/6 if creation needed). by STEP 5/6 if creation needed). `.claude/**` and `CLAUDE.md` are NOT
analysed here — they are never targets.
**README.md** — *must exist; see STEP 5 if absent* **README.md** — *must exist; see STEP 5 if absent*
- Title + one-line description present? - Title + one-line description present?
- Quick-start commands match package manifest? - Section set matches the Standard-Readme template (STEP 5)? Flag any
out-of-convention section (Status, Roadmap, TODO, Project layout,
internal notes) → `[REMOVED]` (HUMAN; auto-proposed for deletion in
CLEAN MODE, see STEP 6.5).
- Feature list covers current functionality? - Feature list covers current functionality?
- **Added:** new skills/commands/endpoints/modules in code, - **Added:** new commands/endpoints/modules in code, missing from the
missing from feature list → AUTO if name obvious, HUMAN if feature list → AUTO if name obvious, HUMAN if wording needs judgment.
wording needs judgment. - **Removed:** entries referencing code/files/endpoints absent → AUTO
- **Removed:** entries referencing code/files/endpoints absent for removal, HUMAN if deprecated.
→ AUTO for removal, HUMAN if deprecated. - Quick-start (Usage) commands match the package manifest?
- Examples match current API/signatures? - Cross-links present and pointing to existing files (`INSTALL.md`,
- Prerequisites: versions/tools accurate? `CONFIGURE.md`, `USAGE.md`, `DEPLOY.md`, `CONTRIBUTING.md`)? Dead link
- Cross-links present and pointing to existing files → AUTO removal. Missing link to an existing delegated doc → AUTO
(`INSTALL.md`, `CONFIGURE.md`, `USAGE.md`, `DEPLOY.md`, addition. README must LINK, never duplicate the delegated body.
`CONTRIBUTING.md`, `CHANGELOG.md`)? Dead link → AUTO removal.
Missing link to existing doc → AUTO addition.
**CLAUDE.md** **INSTALL.md** *(Diátaxis: how-to)*
- Norms match current project patterns?
- Stack description matches detected `STACK`?
- Build/test/lint commands runnable?
- Folder tree matches actual structure?
- Decisions in `.claude/memory/decisions.md` reflected when
architectural (framework choice, security stance, API versioning)?
**INSTALL.md**
- Env vars referenced exist in `.env.example`? - Env vars referenced exist in `.env.example`?
- Install steps match current dep manager + versions? - Install steps match current dep manager + versions?
- OS/runtime prerequisites accurate? - OS/runtime prerequisites accurate?
**CONFIGURE.md** **CONFIGURE.md** *(Diátaxis: reference — generated from the real schema)*
- Config-file format matches current code? - Every documented option still present in code (`.env.example`, config
- Each documented option still present in code? struct/parsing)? Each removed option → `[REMOVED]`.
- New options added to code reflected here? - New options added to code reflected here? Each → `[ADDED]`.
- Never invent options. Document only what the schema/code defines.
**USAGE.md** **USAGE.md** *(Diátaxis: tutorial + reference)*
- CLI flags / commands match current implementation? - CLI flags / commands match current implementation?
- API endpoints match current routes (versioned per - API endpoints match current routes (versioned per `/api/v1/...` rule)?
`/api/v1/...` rule)?
- Code examples match current signatures? - Code examples match current signatures?
**DEPLOY.md** **DEPLOY.md** *(Diátaxis: operational how-to)*
- Steps match detected deploy artifacts (Dockerfile, fly.toml, - Steps match detected deploy artifacts (Dockerfile, fly.toml,
workflows, etc.)? workflows, etc.)?
- Production env vars listed and match `.env.example`? - Production env vars listed and match `.env.example`?
- Rollback procedure present (non-trivial deploy)? - Rollback procedure present (non-trivial deploy)?
- If `DEPLOY_COMPLEXITY == TRIVIAL` → file is overkill, propose - If `DEPLOY_COMPLEXITY == TRIVIAL` → file is overkill, propose inlining
inlining content into README "Deploy" section. HUMAN. content into a README "Deploy" link/paragraph. HUMAN.
**CONTRIBUTING.md** **CONTRIBUTING.md**
- Branch workflow accurate? - Branch workflow accurate?
- Test commands correct? - Test commands correct?
- Code style rules still enforced (lint config, formatter)? - Code style rules still enforced (lint config, formatter)?
- Commit convention documented = Conventional Commits?
**CHANGELOG.md** **CHANGELOG.md** *(Keep a Changelog + SemVer)*
- Latest code changes have entries? Always HUMAN. - Latest code changes have entries? Always HUMAN.
- Entry format consistent with existing style? - Format consistent with Keep a Changelog (Unreleased + version
headings, grouped Added/Changed/Fixed/Removed)?
- Versions follow SemVer?
**SECURITY.md**
- Supported versions table matches current release line?
- Reported-vulnerability contact / process still valid?
- References (paths, contacts, URLs) still resolve?
**ARCHITECTURE.md**
- Components / modules described still exist in code?
- Diagrams or module lists match current top-level structure?
- May be informed by `.claude/memory/decisions.md` (read for context) —
but the architectural rationale is rewritten for a public audience,
never copied from the registry.
**docs/**/*.md** **docs/**/*.md**
- Technical accuracy: code references match reality? - Technical accuracy: code references match reality?
- Internal links point to existing files/sections? - Internal links point to existing files/sections?
- Respect Diátaxis: each page is one type (tutorial / how-to /
**.claude/tasks/TODO.md** reference / explanation), not a mix.
- Tasks still relevant given current code state?
- Completed subtasks ticked?
- Tasks for code that no longer exists → flag for cleanup. HUMAN.
**.claude/audits/*.md**
- Audit reports (SEO, harden, validate, BUGS-FOUND, etc.)
reference paths/files that still exist?
- Findings still applicable, or already resolved by later commits?
Flag resolved findings → HUMAN (user decides whether to archive).
**.claude/memory/decisions.md / learnings.md / blockers.md**
- Decisions referencing files/modules → those still exist?
- Resolved blockers marked `resolved`?
- Decisions contradicting current code → surface for user
reconciliation. HUMAN.
**.claude/memory/journal.md / evals.md**
- Append-only logs — never edit. Skip drift checks.
**Inline comments (JSDoc, docstrings, rustdoc, godoc)** **Inline comments (JSDoc, docstrings, rustdoc, godoc)**
- Only check files changed since last doc update. - Only check files changed since last doc update.
@ -225,37 +259,37 @@ If `README.md ∉ DOC_FILES`:
**README is MANDATORY. Always create it — never gate on user approval.** **README is MANDATORY. Always create it — never gate on user approval.**
A repo without a README is an immediate "this looks abandoned" signal A repo without a README is an immediate "this looks abandoned" signal
to anyone landing on it. If the previous maintainer opted out (e.g. to anyone landing on it.
`CLAUDE.md` carries an "Exceptions: No README at scaffold" line),
override that opt-out and strike through the exception in `CLAUDE.md`
during patching.
Render the template below using real project data only: Render the lean Standard-Readme template below using real project data
- `<project-name>` ← manifest `name` (humanise: `nuit-folle` → `Nuit Folle`) only. May read `.claude/` and `CLAUDE.md` for context to phrase the
- one-line description ← manifest `description`, else first paragraph description and features — never copy internal-state text into the file.
of CLAUDE.md project overview, else "Mobile-first / web / CLI / …
project. Replace this line with a concrete pitch." (clearly flagged - `<Project Name>` ← manifest `name` (humanise: `nuit-folle` → `Nuit Folle`)
as a placeholder so the user replaces it) - one-line description ← manifest `description`, else synthesised from the
- feature bullets ← top-level entry points / routes / skills / CLI project's purpose (informed by CLAUDE.md / `.claude/` context), else
commands discovered in the codebase (names + 1-line description each) "Mobile-first / web / CLI / … project. Replace this line with a concrete
- stack list ← `STACK` detected in STEP 2 with versions from manifest pitch." (clearly flagged as a placeholder so the user replaces it)
- feature bullets ← top-level entry points / routes / CLI commands /
modules discovered in the codebase (names + 1-line description each)
- install + run commands ← exact `npm scripts` / `pyproject.toml` / - install + run commands ← exact `npm scripts` / `pyproject.toml` /
`Cargo.toml` / `Makefile` targets (no invented commands) `Cargo.toml` / `Makefile` targets (no invented commands)
- documentation cross-links ← only existing or freshly-proposed files - cross-links ← only to existing or freshly-proposed delegated docs
- license ← `LICENSE` file SPDX header if present, manifest `license` - license ← `LICENSE` SPDX header if present, manifest `license` field if
field if present, else "Not specified — set one before public release" present, else "Not specified — set one before public release"
(explicit gap, not a placeholder)
The template includes a **"Quick start (dev)"** section that is the **Lean README — Standard-Readme section set + order. NOTHING ELSE.**
sole user-facing entry-point for local development. Production deploy FORBIDDEN in the README: roadmap, todo, internal notes, progress/status,
guidance lives in `DEPLOY.md`; the README only links to it. decisions, learnings, project layout, any `.claude/` content. Delegate
detail to the Diátaxis docs and LINK to them — never duplicate.
```markdown ```markdown
# <Project Name> # <Project Name>
<one-line description from manifest or CLAUDE.md project overview> <one-line description>
--- <!-- Badges line — include ONLY if CI workflow or LICENSE exists -->
[![CI](<ci-badge-url>)](<ci-url>) [![License](<spdx-badge>)](LICENSE)
## Features ## Features
@ -263,89 +297,68 @@ guidance lives in `DEPLOY.md`; the README only links to it.
- **<feature>** — <one-line> - **<feature>** — <one-line>
(infer from entry points, routes, commands, top-level modules) (infer from entry points, routes, commands, top-level modules)
## Stack ## Install
- <Language> <version> (manifest) <single canonical install command from the manifest>
- <Framework> <version>
- <Notable libs>
- <Build tool / test runner / linter>
## Quick start (dev) <If install is non-trivial (multiple steps, services, env setup):>
See [INSTALL.md](INSTALL.md) for the full setup.
Single-process, no Docker — fastest path to a running app: ## Usage
Quick start (dev) — fastest path to a running app:
\`\`\`bash \`\`\`bash
<install command from manifest> <install command from manifest>
<run command(s) from manifest> <run command(s) from manifest>
\`\`\` \`\`\`
<If a docker-compose dev override exists:> <If a richer tutorial/reference exists:> See [USAGE.md](USAGE.md).
Docker-compose dev — matches the production topology with hot reload:
\`\`\`bash ## Configuration
<dev compose command>
\`\`\`
<1-2 lines about local→backend wiring, defaults, common gotchas> Configured via <environment variables / config file>. See
[CONFIGURE.md](CONFIGURE.md) for every option.
<!-- NO inline config table — CONFIGURE.md is the single reference. -->
For **production deployment** — provisioning, firewall, TLS, backups, ## Deploy
hardening — see [DEPLOY.md](DEPLOY.md).
## Verifying a change <Include this section ONLY if DEPLOY_COMPLEXITY == NON_TRIVIAL:>
See [DEPLOY.md](DEPLOY.md) for production deployment.
\`\`\`bash ## Contributing
<typecheck command> # only list those that actually exist in the manifest
<lint command>
<test command>
\`\`\`
<one-line baseline expectation, e.g. "X tests pass today"> See [CONTRIBUTING.md](CONTRIBUTING.md).
## Build & deploy ## License
<For each top-level build/deploy script in the manifest, one line.> <SPDX id> — see [LICENSE](LICENSE).
<If DEPLOY_COMPLEXITY == NON_TRIVIAL: link to DEPLOY.md.> <or: "Not specified — set one before public release">
## Documentation
- [<root doc>](<root doc>) (only if exists or proposed)
- [CLAUDE.md](CLAUDE.md) (only if exists)
- [DEPLOY.md](DEPLOY.md) (only if DEPLOY_COMPLEXITY == NON_TRIVIAL)
- [Contributing](CONTRIBUTING.md) (only if exists)
- [Changelog](CHANGELOG.md) (only if exists)
## Project layout (top-level)
\`\`\`
<top-level directory tree, 1 line per dir, generated from `ls -d */`>
\`\`\`
## Status
<Pre-1.0 / Beta / Stable — pulled from manifest `version` and a 1-line
state line. Note the license situation explicitly if absent.>
``` ```
Omit any section whose delegated target does not exist and is not being
proposed this run (e.g. drop "Deploy" entirely when `DEPLOY_COMPLEXITY`
is `NONE`/`TRIVIAL`; drop "Configuration" when there is no config schema).
Tag as **AUTO** — create on first audit. Surface the rendered README in Tag as **AUTO** — create on first audit. Surface the rendered README in
the validation gate before writing so the user can `edit` if needed, the validation gate before writing so the user can `edit` if needed, but
but do NOT skip creation; "skip" should not be an offered option on do NOT skip creation; "skip" is not an offered option on README bootstrap.
README bootstrap.
### STEP 6 — DEPLOY.md GATE ### STEP 6 — DEPLOY.md GATE
| State | Action | | State | Action |
|-------|--------| |-------|--------|
| `DEPLOY_COMPLEXITY == NONE` | Skip. Don't propose DEPLOY.md. | | `DEPLOY_COMPLEXITY == NONE` | Skip. Don't propose DEPLOY.md. |
| `DEPLOY_COMPLEXITY == TRIVIAL` AND no DEPLOY.md | Skip. Suggest one-paragraph "Deploy" section in README. HUMAN. | | `DEPLOY_COMPLEXITY == TRIVIAL` AND no DEPLOY.md | Skip. Suggest a one-line "Deploy" paragraph/link in README. HUMAN. |
| `DEPLOY_COMPLEXITY == TRIVIAL` AND DEPLOY.md exists | Suggest deletion or inlining into README. HUMAN. | | `DEPLOY_COMPLEXITY == TRIVIAL` AND DEPLOY.md exists | Suggest deletion or inlining into README. HUMAN. |
| `DEPLOY_COMPLEXITY == NON_TRIVIAL` AND no DEPLOY.md | Propose creation using the full prod-only template below. HUMAN approval. | | `DEPLOY_COMPLEXITY == NON_TRIVIAL` AND no DEPLOY.md | Propose creation using the full prod-only template below. HUMAN approval. |
| `DEPLOY_COMPLEXITY == NON_TRIVIAL` AND DEPLOY.md exists | Apply standard drift detection (STEP 3-4). Verify the existing file covers the 14 sections below; surface missing sections as drift items. | | `DEPLOY_COMPLEXITY == NON_TRIVIAL` AND DEPLOY.md exists | Apply standard drift detection (STEP 3-4). Verify it covers the 14 sections below; surface missing sections as drift items. |
**DEPLOY.md is PROD-ONLY.** Dev quick-start lives in README.md **DEPLOY.md is PROD-ONLY.** Dev quick-start lives in README.md
("Quick start (dev)" section); DEPLOY.md never duplicates it. If the ("Usage" section); DEPLOY.md never duplicates it. If the existing
existing DEPLOY.md contains a "Local development" / "Dev setup" / DEPLOY.md contains a "Local development" / "Dev setup" / similar
similar section, flag it as drift and propose moving its content into section, flag it as drift and propose moving its content into README
README.md while removing the section from DEPLOY.md. while removing the section from DEPLOY.md.
#### DEPLOY.md template — 14 sections (NON_TRIVIAL) #### DEPLOY.md template — 14 sections (NON_TRIVIAL)
@ -537,12 +550,32 @@ as a separate `[HUMAN]` drift item in STEP 7 with a 1-line description
of what the section should cover for this project. Do not patch them of what the section should cover for this project. Do not patch them
automatically — production deploy guidance is judgement-heavy. automatically — production deploy guidance is judgement-heavy.
### STEP 6.5 — CLEAN MODE (only when CLEAN MODE active)
In addition to the standard audit, scan EXISTING public docs for
out-of-convention content and propose its removal. Tag every item
**HUMAN**; nothing is deleted without gate approval.
Propose removal of:
- In `README.md`: `Status`, `Roadmap`, `TODO`, `Project layout`, and
any "internal notes" / progress / decisions / learnings sections —
anything outside the Standard-Readme set (STEP 5).
- In ANY public doc: any block that reproduces `.claude/` content (TODO
items, roadmap, decisions, learnings, journal entries, audit findings
copied verbatim or near-verbatim). Detect by matching phrasing/IDs
(e.g. `BDR-`, `LRN-`, `BLK-`, `EVAL-`, "## TODO", roadmap tables)
against `.claude/` sources read for context.
Emit these under "CLEAN PROPOSALS" in the report (STEP 7). Removal only;
never rewrite the surrounding doc beyond excising the offending block.
### STEP 7 — REPORT ### STEP 7 — REPORT
``` ```
DOC SYNC REPORT DOC SYNC REPORT
=============== ===============
MODE : FULL | FULL+CLEAN
PROJECT STACK : <detected stack> PROJECT STACK : <detected stack>
DEPLOY : <NONE | TRIVIAL | NON_TRIVIAL — evidence> DEPLOY : <NONE | TRIVIAL | NON_TRIVIAL — evidence>
DOCS PRESENT : <count> — <list> DOCS PRESENT : <count> — <list>
@ -563,39 +596,44 @@ Last updated: <date> (<N commits since>)
(repeat for each doc with drift) (repeat for each doc with drift)
## CREATE PROPOSALS ## CREATE PROPOSALS
- [HUMAN] README.md — bootstrap (template above) - [AUTO] README.md — bootstrap (lean Standard-Readme template)
- [HUMAN] DEPLOY.md — non-trivial deploy (Docker + fly.toml) - [HUMAN] DEPLOY.md — non-trivial deploy (Docker + fly.toml)
- ... - ...
## REMOVE / INLINE PROPOSALS ## REMOVE / INLINE PROPOSALS
- [HUMAN] DEPLOY.md — trivial deploy, inline into README instead - [HUMAN] DEPLOY.md — trivial deploy, inline into README instead
- ... - ...
## CLEAN PROPOSALS (only in CLEAN MODE)
- [HUMAN] README.md — remove "Status" section (out-of-convention)
- [HUMAN] README.md — remove "Project layout" section
- [HUMAN] docs/notes.md — remove copied .claude/ roadmap block
- ...
``` ```
**Tagging rules:** **Tagging rules:**
- **AUTO** — factual update Claude can write: command changed, - **AUTO** — factual update Claude can write: command changed, var
var renamed, param added, version bumped, file moved, dead renamed, param added, version bumped, file moved, dead reference
reference removed, new entry point added to a list, new link removed, new entry added to a list, new link added to an existing doc.
added to existing doc. - **HUMAN** — needs business context: feature wording, architecture
- **HUMAN** — needs business context: feature wording, rationale, changelog entry content, new section creation, deprecation
architecture rationale, changelog entry content, new section notes, DEPLOY bootstrap content, out-of-convention removals (CLEAN).
creation, deprecation notes, README/DEPLOY bootstrap content,
decisions.md ↔ code reconciliation.
**Feature delta tags:** **Feature delta tags:**
- `[ADDED]` — feature in code, not in docs. AUTO for list entry - `[ADDED]` — feature in code, not in docs. AUTO for list entry with
with obvious wording, HUMAN if needs new section. obvious wording, HUMAN if needs new section.
- `[REMOVED]` — feature in docs, not in code. AUTO for list entry - `[REMOVED]` — feature in docs, not in code. AUTO for list entry to
to delete, HUMAN if needs deprecation note. delete, HUMAN if needs deprecation note.
CHANGELOG entries always HUMAN. DEPLOY.md creation always HUMAN. CHANGELOG entries always HUMAN. DEPLOY.md creation always HUMAN.
**README.md creation is AUTO** — always render and write, never gate CLEAN removals always HUMAN.
on user input. The validation gate (STEP 8) still surfaces the **README.md creation is AUTO** — always render and write, never gate on
rendered file so the user can edit before write, but "skip" is not an user input. The validation gate (STEP 8) still surfaces the rendered
option for README bootstrap; it is mandatory. file so the user can edit before write, but "skip" is not an option for
README bootstrap; it is mandatory.
If no drift in any doc and no missing required doc: If no drift in any doc and no missing required doc (and, in CLEAN MODE,
`DOC SYNC: all docs current` and stop. nothing out-of-convention): `DOC SYNC: all docs current` and stop.
### STEP 8 — VALIDATION GATE (mandatory stop) ### STEP 8 — VALIDATION GATE (mandatory stop)
@ -608,10 +646,12 @@ CREATE items : <count>
- DEPLOY.md (HUMAN — approve before write) - DEPLOY.md (HUMAN — approve before write)
- … - …
REMOVE items : <count> REMOVE items : <count>
CLEAN items : <count> (only in CLEAN MODE — out-of-convention removals)
Apply AUTO patches? (yes / select items / cancel) Apply AUTO patches? (yes / select items / cancel)
Apply HUMAN items? (per-item: yes / no / edit) Apply HUMAN items? (per-item: yes / no / edit)
Apply CREATE items? (per-item: yes / edit / no — README has no `no`) Apply CREATE items? (per-item: yes / edit / no — README has no `no`)
Apply CLEAN removals? (per-item: yes / no)
``` ```
README.md CREATE is unconditional: the only valid responses are `yes` README.md CREATE is unconditional: the only valid responses are `yes`
@ -623,14 +663,16 @@ Wait for explicit approval. Do not proceed without it.
### STEP 9 — PATCH ### STEP 9 — PATCH
Apply only approved items: Apply only approved items. **Never write under `.claude/` or to
`CLAUDE.md`** — they are not targets under any circumstance.
- Surgical Edit for AUTO items. Preserve structure and tone. - Surgical Edit for AUTO items. Preserve structure and tone.
- Write for approved CREATE items (README, DEPLOY). Use real - Write for approved CREATE items (README, DEPLOY). Use real project
project data only — no `<TODO>` placeholders, no fabricated data only — no `<TODO>` placeholders, no fabricated feature
feature descriptions. descriptions.
- For removals, prefer Edit (delete dead lines) over Write. - For removals (REMOVE / INLINE / CLEAN), prefer Edit (delete the
- Re-read each modified file post-edit to verify no broken offending lines) over Write.
markdown, no orphaned references. - Re-read each modified file post-edit to verify no broken markdown,
no orphaned references.
### OUTPUT ### OUTPUT
@ -639,7 +681,7 @@ DOC SYNC COMPLETE
DOCS CHECKED : <count> DOCS CHECKED : <count>
AUTO PATCHED : <count> items across <count> files AUTO PATCHED : <count> items across <count> files
CREATED : <count> files CREATED : <count> files
REMOVED : <count> files REMOVED : <count> files / sections
HUMAN PENDING: <count> items (see report above) HUMAN PENDING: <count> items (see report above)
SKIPPED : <count> (user declined) SKIPPED : <count> (user declined)
``` ```
@ -653,36 +695,41 @@ Input format: `auto-mode scope: <file1> <file2> ...`
### STEP A1 — PARSE SCOPE ### STEP A1 — PARSE SCOPE
Extract file list from `$ARGUMENTS`. These are files modified Extract file list from `$ARGUMENTS`. These are files modified during
during the current session. the current session.
### STEP A2 — IDENTIFY RELEVANT DOCS ### STEP A2 — IDENTIFY RELEVANT PUBLIC DOCS
Map modified files to relevant docs: Map modified files to relevant PUBLIC docs only:
- Code files → README (examples, feature list), USAGE, docs/ - Code files → README (features, examples), USAGE, docs/
- Config files → INSTALL, CONFIGURE, README setup section - Config files / schema (`.env.example`, config struct) → CONFIGURE,
- Package manifest → README (prereqs, install), INSTALL INSTALL, README "Configuration" link
- Dockerfile/compose → README Docker section, INSTALL, DEPLOY - Package manifest → README (install/usage), INSTALL
- Deploy artifacts (fly.toml, workflows, k8s manifests, etc.) - Dockerfile/compose → DEPLOY, README "Deploy" link, INSTALL
→ DEPLOY (or trigger STEP 6 gate if no DEPLOY.md), README - Deploy artifacts (fly.toml, workflows, k8s manifests, etc.) → DEPLOY
- CLAUDE.md change → skip (self-documenting) (or trigger STEP 6 gate if no DEPLOY.md), README
- `.claude/memory/decisions.md` change with architectural impact - Security policy / supported-version change → SECURITY
→ CLAUDE.md, README - Architecture-level module change → ARCHITECTURE, README features
If no relevant docs exist for changed files → exit silently. A change to a file under `.claude/` (TODO, audits, memory) or to
`CLAUDE.md` is **never** a trigger to write a doc and is **never** a
target. It may only be read for context if a code/config change in scope
needs that context to be documented accurately.
If no relevant public docs exist for changed files → exit silently.
**Exception — README absence**: in AUTO MODE, if README.md is missing **Exception — README absence**: in AUTO MODE, if README.md is missing
AND any code/config file was modified this session, treat it as a AND any code/config file was modified this session, treat it as a
SIGNIFICANT item in STEP A4 and surface a "README missing — propose SIGNIFICANT item in STEP A4 and surface a "README missing — propose
creation" line with the rendered draft (per STEP 5 template). Auto creation" line with the rendered draft (per STEP 5 template). Auto mode
mode does NOT auto-write CREATE items; the rendered draft is shown so does NOT auto-write CREATE items; the rendered draft is shown so the
the user can approve in one step at end-of-session. user can approve in one step at end-of-session.
### STEP A3 — QUICK DRIFT CHECK ### STEP A3 — QUICK DRIFT CHECK
For each relevant doc, read it and check only sections affected For each relevant doc, read it and check only sections affected by
by scoped changes. No full git scan — compare doc content directly scoped changes. No full git scan — compare doc content directly against
against current state of modified files. current state of modified files.
Feature deltas in scoped files: Feature deltas in scoped files:
- New files added → feature/module documented? - New files added → feature/module documented?
@ -691,12 +738,12 @@ Feature deltas in scoped files:
Categorize: Categorize:
- **NONE** — no drift detected. - **NONE** — no drift detected.
- **MINOR** — factual correction (command, param, path, version), - **MINOR** — factual correction (command, param, path, version), dead
dead reference removal, new list entry add. reference removal, new list entry add.
- **SIGNIFICANT** — new feature undocumented, section outdated, - **SIGNIFICANT** — new feature undocumented, section outdated, breaking
breaking change not reflected, feature removed without doc change not reflected, feature removed without doc update, new deploy
update, new deploy artifact (Dockerfile, fly.toml, workflow) artifact (Dockerfile, fly.toml, workflow) without DEPLOY.md update or
without DEPLOY.md update or creation. creation.
### STEP A4 — ACT ### STEP A4 — ACT
@ -714,30 +761,33 @@ Categorize:
--- ---
## RULES ## RULES
- Never invent content. Only sync what changed in code. - **`.claude/` and `CLAUDE.md` are READ-ONLY context.** Never modify
- Never fabricate examples, feature descriptions, explanations. them, never list them as targets, never copy their content into a
- README.md creation is **AUTO and unconditional** — always created public doc. They inform the writing only.
when missing, using real project data only (no placeholders, no - Never invent content. Only sync what changed in code. Never fabricate
fabricated content). The validation gate surfaces the rendered file examples, feature descriptions, config options, or explanations.
- **Conventions are normative** (see CONVENTIONS): README = Standard
Readme; doc types separated per Diátaxis; CHANGELOG = Keep a Changelog
+ SemVer; commits/changelog entries = Conventional Commits.
- README is **lean**: only the Standard-Readme section set (STEP 5). No
roadmap / todo / status / project-layout / internal notes / decisions
/ learnings. README LINKS to delegated docs, never duplicates them.
- README.md creation is **AUTO and unconditional** — always created when
missing, real project data only. The gate surfaces the rendered file
for editing but never offers a "skip" option for README bootstrap. for editing but never offers a "skip" option for README bootstrap.
Strike through any project-level "no README" opt-out (e.g. in - DEPLOY.md creation requires HUMAN approval and uses real project data
CLAUDE.md "Exceptions to global rules") during the same patch. only. Produced only when `DEPLOY_COMPLEXITY == NON_TRIVIAL`, following
- DEPLOY.md creation requires HUMAN approval and uses real project the 14-section template in STEP 6. Trivial deploy belongs in README.
data only. Produced only when `DEPLOY_COMPLEXITY == NON_TRIVIAL`, - DEPLOY.md is **PROD-ONLY**. Dev quick-start lives in README "Usage". If
following the 14-section template in STEP 6. Trivial deploy belongs an existing DEPLOY.md mixes dev and prod, surface the dev section as
in README. drift and propose moving it to README in the same patch round.
- DEPLOY.md is **PROD-ONLY**. Dev quick-start lives in README under a - CONFIGURE.md is generated from the real schema (`.env.example`, config
"Quick start (dev)" section. If an existing DEPLOY.md mixes dev and struct/parsing) — every option real, none invented.
prod, surface the dev section as drift and propose moving it to - Doc list is dynamic — auto-detect from the modifiable-targets set,
README during the same patch round. never assume a fixed file always exists.
- Doc list is dynamic — auto-detect, never assume fixed set.
- CHANGELOG entries: always propose, never auto-write. - CHANGELOG entries: always propose, never auto-write.
- Inline comment updates: only for files in scope, only when - CLEAN removals: only in CLEAN MODE, always HUMAN, removal-only.
- Inline comment updates: only for files in scope, only when the
signature actually changed. signature actually changed.
- `.claude/memory/journal.md` and `evals.md` are append-only
logs — never edit.
- `.claude/memory/decisions.md` / `learnings.md` / `blockers.md`
are user-curated registries — surface drift, don't auto-edit
(HUMAN only).
- Preserve existing structure, formatting, tone. - Preserve existing structure, formatting, tone.
- Patches minimal — change what's wrong, nothing else. - Patches minimal — change what's wrong, nothing else.