@baldurpan/create-ai-workflow 0.5.0 → 0.6.0

package/README.md

@@ -40,7 +40,7 @@ starting point — nothing has to be looked up first.
 | `/feature-close` | retires a feature: a `history.md` row, a `git mv` into `archive/`, and a reviewed reference sweep |
 | `/orchestrate` | one ad-hoc, commit-sized change through the same gates — no entry, no ledger |
 | `/prototype` | a throwaway HTML/CSS mockup under `prototypes/`, to settle a layout question before a plan commits to it — no gates, no application code |
-| `/onboard` | fills in your own stubs, adopting what the repo already documented and running each verification command before writing it down |
+| `/onboard` | fills in your own stubs, adopting what the repo already documented, indexing where it documents itself, and running each verification command before writing it down |
 
 ## What makes it different
 
@@ -63,6 +63,13 @@ the agent does — and every command that lands code reads it before closing out
 commits*: a tool installed into a repository it knows nothing about does not get to write that
 repository's history unasked. Branches, pushes and pull requests are outside the workflow entirely.
 
+**Documentation is part of the change.** A plan starts by finding where the project explains itself —
+`context/stack.md` holds that index, `/onboard` fills it by sweeping the tree and asking what is published
+elsewhere — and every plan carries a §7 naming what the feature makes untrue there. Each row is assigned to
+a phase, and its path goes on that phase's `Files:` line, so the README lands with the rename rather than
+after it. Docs are the one output with no gate behind them: nothing fails when a page keeps describing a
+flag that no longer exists.
+
 **A finding outlives the session that found it.** A reviewer `FAIL` or a capped gate is written to
 `context/findings.md` *before* the loopback, so it survives the conversation ending. An open `P0`/`P1`
 blocks its phase from being marked `done` and blocks `/feature-close`.
@@ -109,6 +116,22 @@ npx @baldurpan/create-ai-workflow update --force     # back up edited files (.ba
 | missing | restores |
 | not in the manifest | nothing — it cannot reach it |
 
+**Run `/onboard` after an update.** That last row is the whole reason: a new version's tool-owned files can
+expect something of a project-owned one — a section of `context/stack.md` that every plan now reads, a
+`context/git.md` older than the file itself — and the updater is forbidden to write either. So it ends by
+naming each gap and stops:
+
+```
+Next
+  ! context/stack.md has no "Documentation" section — this version's stub has one
+  ! context/git.md is missing — a stub is project-owned, so update cannot write one
+  Run /onboard in your agent. It is re-runnable, and it is the only thing that
+  reaches these files — the commands above now read them.
+```
+
+It is a note, not a failure — the exit code is the conflict count's to set. A tool that failed an update
+over the shape of a file it may not touch would be calling someone else's business its own breakage.
+
 ## Standards
 
 `context/standards/` ships a vendored default, and `context/standards/README.md` holds a

package/dist/check/markdown.js

@@ -6,6 +6,13 @@
 export function stripComments(text) {
     return text.replace(/<!--[\s\S]*?-->/g, (match) => match.replace(/[^\n]/g, ' '));
 }
+/**
+ * Blank out fenced code blocks, preserving line count. A `##` inside a fence is an illustration — the
+ * stubs sketch a directory layout in one — not a heading of the document.
+ */
+export function stripFences(text) {
+    return text.replace(/^```[\s\S]*?^```/gm, (match) => match.replace(/[^\n]/g, ' '));
+}
 function splitCells(line) {
     return line
         .trim()

package/dist/cli.js

@@ -10,7 +10,8 @@ const USAGE = `${bold('create-ai-workflow')} — overlay a tiered planning workf
 ${bold('Usage')}
   npx @baldurpan/create-ai-workflow                      install into this repository
   npm  create @baldurpan/ai-workflow                     the same thing, shorter
-  npx @baldurpan/create-ai-workflow update               replace the tool-owned files with this version
+  npx @baldurpan/create-ai-workflow update               replace the tool-owned files with this version,
+                                                         and name what only ${cyan('/onboard')} can fill
   npx @baldurpan/create-ai-workflow standards add <url>  swap context/standards/ for a git repository
   npx @baldurpan/create-ai-workflow check                report structural breakage; never writes
 

package/dist/commands/update.js

@@ -2,9 +2,10 @@ import { copyFileSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'no
 import path from 'node:path';
 import { apply as applyBlock, BlockConflictError, inspect } from "../agents-block.js";
 import { AGENTS_BLOCK_KEY, DEFAULT_ADAPTERS, STANDARDS_PREFIX, agentsBlockBody, managedFiles, renderManaged, } from "../layout.js";
-import { bold, cyan, dim, green, info, red, UserError, warn, yellow } from "../log.js";
+import { bold, cyan, dim, green, info, red, UserError, yellow } from "../log.js";
 import { readManifest, writeManifest } from "../manifest.js";
 import { exists, hash, packageVersion } from "../paths.js";
+import { stubGaps } from "../stubs.js";
 const LABEL = {
     replace: green('update '),
     restore: green('restore'),
@@ -138,9 +139,11 @@ export function update(root, options) {
         info();
         info(`${yellow('!')} the bundled standards moved: ${dim(installedRef.slice(0, 8))} → ${dim(bundledRef.slice(0, 8))}`);
     }
+    const gaps = stubGaps(root);
     if (options.dryRun) {
         info();
         info(dim('--dry-run: nothing was written.'));
+        reportStubGaps(gaps);
         return conflicts.length > 0 && !options.force ? 1 : 0;
     }
     if (conflicts.length > 0 && !options.force) {
@@ -201,8 +204,30 @@ export function update(root, options) {
     writeManifest(root, manifest);
     info();
     info(`${green('done')} ${written} file${written === 1 ? '' : 's'} written. Review the diff — nothing was committed.`);
+    reportStubGaps(gaps);
     return 0;
 }
+/**
+ * What this version's stubs expect and the install does not have. Printed last, because it is the only
+ * part of an update that needs a person: everything above it has already happened, and nothing here can.
+ *
+ * This is a note, never an error — the exit code is the conflict count's to set. A tool that fails an
+ * update over the shape of a file it is forbidden to touch would be reporting someone else's business as
+ * its own breakage.
+ */
+function reportStubGaps(gaps) {
+    if (gaps.length === 0)
+        return;
+    info();
+    info(bold('Next'));
+    for (const gap of gaps) {
+        info(gap.section === undefined
+            ? `  ${yellow('!')} ${gap.dest} ${dim('is missing — a stub is project-owned, so update cannot write one')}`
+            : `  ${yellow('!')} ${gap.dest} ${dim(`has no "${gap.section}" section — this version's stub has one`)}`);
+    }
+    info(`  Run ${cyan('/onboard')} in your agent. ${dim('It is re-runnable, and it is the only thing that')}`);
+    info(`  ${dim('reaches these files — the commands above now read them.')}`);
+}
 function describeBad(state) {
     return state.kind === 'duplicate'
         ? `${state.count} ai-workflow blocks in AGENTS.md — delete the extra one`

package/dist/layout.js

@@ -93,15 +93,22 @@ export function managedFiles(adapters) {
     }
     return files;
 }
-/** Project-owned files. Written once, at install, and never reachable by `update`. */
+/**
+ * Project-owned files. Written once, at install, and never reachable by `update`.
+ *
+ * `onboard` marks the four whose content a person supplies, through `/onboard`. The other three are
+ * written by the workflow as it runs — a roadmap entry, a history row, a finding — so a question about
+ * their shape is `check`'s, and pointing at `/onboard` for one of them would name a command that does not
+ * touch it.
+ */
 export const STUBS = [
-    { source: 'stubs/stack.md', dest: 'context/stack.md' },
-    { source: 'stubs/verify.md', dest: 'context/verify.md' },
-    { source: 'stubs/executors.md', dest: 'context/executors.md' },
-    { source: 'stubs/git.md', dest: 'context/git.md' },
-    { source: 'stubs/roadmap.md', dest: 'context/roadmap.md' },
-    { source: 'stubs/history.md', dest: 'context/history.md' },
-    { source: 'stubs/findings.md', dest: 'context/findings.md' },
+    { source: 'stubs/stack.md', dest: 'context/stack.md', onboard: true },
+    { source: 'stubs/verify.md', dest: 'context/verify.md', onboard: true },
+    { source: 'stubs/executors.md', dest: 'context/executors.md', onboard: true },
+    { source: 'stubs/git.md', dest: 'context/git.md', onboard: true },
+    { source: 'stubs/roadmap.md', dest: 'context/roadmap.md', onboard: false },
+    { source: 'stubs/history.md', dest: 'context/history.md', onboard: false },
+    { source: 'stubs/findings.md', dest: 'context/findings.md', onboard: false },
 ];
 export const STUB_DIRS = ['context/drafts', 'context/plans', 'context/archive'];
 export function readTemplate(source) {

package/dist/stubs.js

@@ -0,0 +1,51 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { stripComments, stripFences } from "./check/markdown.js";
+import { readTemplate, STUBS } from "./layout.js";
+import { exists } from "./paths.js";
+/**
+ * The `##` headings of a markdown document, in order.
+ *
+ * Fenced blocks and HTML comments are blanked first: the stubs ship their examples commented out and
+ * `stack.md` carries a fenced layout sketch, and a heading inside either is an illustration rather than a
+ * section of the document.
+ */
+export function sections(text) {
+    return [...stripComments(stripFences(text)).matchAll(/^## +(.+?)\s*$/gm)].map((m) => m[1]);
+}
+/** Backticks, case and run-together whitespace are formatting, not identity. */
+function normalise(heading) {
+    return heading.replace(/`/g, '').replace(/\s+/g, ' ').trim().toLowerCase();
+}
+/**
+ * What this version's stubs expect that the install does not have — a stub file that is missing outright,
+ * or one whose sections this version has added to.
+ *
+ * `update` reports this and writes nothing. Stubs are project-owned and deliberately absent from the
+ * manifest, so nothing here can reach them; `/onboard` is the only thing that fills one, and until it runs
+ * a command can be pointed at a section of a file that does not have it.
+ *
+ * **Only the stubs `/onboard` fills are examined.** `roadmap.md`, `history.md` and `findings.md` are
+ * written by the workflow rather than by a person, so their shape is `check`'s question — and a report
+ * that named `/onboard` for a file that command never opens would be sending someone somewhere useless.
+ *
+ * A section the user deleted on purpose and one this version added look identical from here, and both are
+ * reported. Telling them apart would mean recording stub state in the manifest, which is the one place the
+ * design keeps free of project-owned files — and the fix is the same either way.
+ */
+export function stubGaps(root) {
+    const gaps = [];
+    for (const stub of STUBS.filter((s) => s.onboard)) {
+        const full = path.join(root, stub.dest);
+        if (!exists(full)) {
+            gaps.push({ dest: stub.dest });
+            continue;
+        }
+        const have = new Set(sections(readFileSync(full, 'utf8')).map(normalise));
+        for (const section of sections(readTemplate(stub.source))) {
+            if (!have.has(normalise(section)))
+                gaps.push({ dest: stub.dest, section });
+        }
+    }
+    return gaps;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baldurpan/create-ai-workflow",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Overlay a tiered planning workflow — roadmap, plans, phase ledgers, verification gates — onto an existing repository, for coding agents.",
   "keywords": [
     "ai",

package/templates/blocks/agents-block.md

@@ -17,7 +17,7 @@ the standing rules, and every command cites it rather than restating it.
 
 | Read | For |
 |---|---|
-| [`context/stack.md`](context/stack.md) | runtime, layout, conventions |
+| [`context/stack.md`](context/stack.md) | runtime, layout, conventions, and where this project documents itself |
 | [`context/standards/README.md`](context/standards/README.md) | engineering standards — load per its conditional table |
 | [`context/verify.md`](context/verify.md) | the real lint / typecheck / build / test commands — the only file that names one |
 | [`context/git.md`](context/git.md) | who commits, and at what granularity — read it before closing out any change |
@@ -31,5 +31,8 @@ the working tree and the user commits it.
 
 **An open `P0` or `P1` in [`context/findings.md`](context/findings.md) blocks its phase from being `done`.**
 
+**Documentation is part of the change.** Whatever a change makes untrue in this project's own docs is fixed
+by the phase that makes it untrue, not by a follow-up.
+
 **Require evidence, not assertion.** A claim about what a file contains needs the file read, not recalled —
 yours as much as a subagent's.

package/templates/claude/agents/planner.agent.md

@@ -33,9 +33,13 @@ The default shape below applies only when the brief names none.
    generic principles.
 2. **Read the project.** `context/stack.md` for what this repo is; `context/verify.md` for how it proves
    itself. Search the codebase and find the patterns that already exist.
-3. **Verify externals.** Check documentation for every library and API involved. Cite what you confirmed.
-4. **Consider.** Edge cases, error states, and implicit requirements the request did not mention.
-5. **Draft.** Say *what* needs to happen, not *how* to code it.
+3. **Find the documentation.** `context/stack.md`'s Documentation section says where this project explains
+   itself. If it is empty, sweep for it — READMEs, `docs/`, a docs site in the tree, an API reference, a
+   changelog, help text in the code. Report what the change would make untrue there, per surface. An empty
+   index is not evidence that there are none.
+4. **Verify externals.** Check documentation for every library and API involved. Cite what you confirmed.
+5. **Consider.** Edge cases, error states, and implicit requirements the request did not mention.
+6. **Draft.** Say *what* needs to happen, not *how* to code it.
 
 ## Default output shape
 

package/templates/context/README.md

@@ -32,7 +32,7 @@ generated "current state" file — hand-editing a ledger row changes every comma
 | [`plan-template.notes.md`](plan-template.notes.md) | what goes in each section of that skeleton | tool |
 | [`roles/coder.md`](roles/coder.md) | the coder system prompt — names no commands | tool |
 | [`standards/`](standards/README.md) | engineering standards, loaded per that README's conditional table | tool* |
-| [`stack.md`](stack.md) | this project's runtime, layout, conventions, and an index of your own files | project |
+| [`stack.md`](stack.md) | this project's runtime, layout, conventions, where it documents itself, and an index of your own files | project |
 | [`verify.md`](verify.md) | this project's real lint / typecheck / build / test commands | project |
 | [`executors.md`](executors.md) | how this project dispatches a coder and a reviewer | project |
 | [`git.md`](git.md) | who commits the work an agent produces, and at what granularity | project |
@@ -71,6 +71,11 @@ hash, `update` walks that manifest, and a project-owned file is not in it — so
 
 `update` prints both columns when it runs. A visible boundary beats a documented one.
 
+The boundary has a cost, and `update` prints that too: a new version's tool-owned files can expect
+something of a project-owned one — a section of [`stack.md`](stack.md), a `git.md` that predates the
+file — and nothing in the updater may write it. So it names each gap under **Next** and stops there.
+Closing them is `/onboard`, which is re-runnable for exactly this reason.
+
 **Anything else you add under `context/` is yours forever**, by the same property — `context/decisions.md`,
 `context/glossary.md`, `context/ops-notes.md` all survive by default, with no feature required to protect
 them. Index your own additions in [`stack.md`](stack.md), not here: this file is replaced on every update,
@@ -80,3 +85,7 @@ so a line you add to it is a line you lose.
 
 Planning artifacts live in `context/`, wherever else your docs live. Product specs, API references and
 anything else written for humans or library consumers stay where this project already keeps them.
+
+They are not out of scope for being elsewhere, though. [`stack.md`](stack.md)'s Documentation section
+indexes where "elsewhere" is, so a plan can name what a feature makes untrue there and a phase can carry
+the fix — the standing rule is in [`workflow.md`](workflow.md).

package/templates/context/plan-template.md

@@ -36,9 +36,11 @@ Written <YYYY-MM-DD>. <One line on what this is.> The `<name>` entry in
 | 1 | <name> | not started | — | |
 | 2 | <name> | not started | 1 | |
 
-Status is one of `not started`, `in progress`, `blocked`, `done`. `done` only when the scope landed and both
-gates passed, and whoever finishes a phase updates the row as part of the same change as the work — who
-commits that change is [`../git.md`](../git.md)'s answer, not this table's.
+Status is one of `not started`, `in progress`, `blocked`, `done`. A row goes to `in progress` when work on
+the phase starts, before any code, so an interrupted run leaves a ledger that says what was underway. `done`
+only when the scope landed and both gates passed, and whoever finishes a phase updates the row as part of
+the same change as the work — who commits that change is [`../git.md`](../git.md)'s answer, not this
+table's.
 
 **Exactly one table in this document has these columns.** Do not add a second phase table — a
 differently-shaped one nearby is a decoy that gets read by mistake.
@@ -61,10 +63,22 @@ differently-shaped one nearby is a decoy that gets read by mistake.
 
 **Done when:** <a condition checkable against the repo>
 
-## 7. Verification
+## 7. Documentation
+
+<What this feature makes untrue in the project's own documentation. Start from the Documentation index in
+[`../stack.md`](../stack.md), and from the repository itself if that index is empty.>
+
+| Surface | What changes | Phase |
+|---|---|---|
+| <path, or the URL of a docs site> | <what it claims now that this makes wrong, or what it will not say yet> | <n> |
+
+<If nothing changes, name the surfaces you checked and why none of them describe this. An empty section
+reads as "not checked", and nothing downstream can tell those apart.>
+
+## 8. Verification
 
 <How to prove the feature works, beyond `context/verify.md` passing.>
 
-## 8. Open questions
+## 9. Open questions
 
 - <Anything the plan could not settle. An honest gap is worth more than an invented decision.>

package/templates/context/plan-template.notes.md

@@ -36,11 +36,19 @@ repo match the ledger" has no answer. A phase is a **commit-sized unit of work w
 not a category of activity — "grammar plus container support for the new token" is a phase; "testing" is
 not.
 
-**§7 Verification** — how to prove the feature works, beyond [`verify.md`](verify.md) passing. Commands to
+**§7 Documentation** — every place this project explains itself that the feature makes wrong, out of date
+or incomplete. The surfaces come from [`stack.md`](stack.md)'s Documentation index, and from a sweep of the
+repository when that index is empty — an index nobody filled in is not evidence that there are no docs.
+**Each row names the phase that carries it, and that phase's `Files:` line names the same path.** A
+documentation row with no phase is a follow-up nobody does. If the feature genuinely changes nothing, the
+section says which surfaces were checked and why: *"no surface describes this"* is an answer, and it is
+distinguishable from silence only when it is written down.
+
+**§8 Verification** — how to prove the feature works, beyond [`verify.md`](verify.md) passing. Commands to
 run by hand, files to eyeball, numbers to compare against §1's measurements. Anything that belongs to the
 project's standing verification stack goes in `verify.md` instead, not here.
 
-**§8 Open questions** — what the plan could not settle. Do not paper over them.
+**§9 Open questions** — what the plan could not settle. Do not paper over them.
 
 ## Standing rules
 
@@ -48,7 +56,8 @@ project's standing verification stack goes in `verify.md` instead, not here.
   [`roadmap.md`](roadmap.md), phase status in §6.1, retired outcomes in [`history.md`](history.md) — one
   place each. `check` fails a plan that grows one.
 - **`/feature-plan` produces a reviewable skeleton plus open questions**, not a finished plan of record.
-  §1, §3 and §6.1 are the sections research can usefully draft. §4 and §5 usually arrive as open questions.
+  §1, §3, §6.1 and §7 are the sections research can usefully draft — §7 in particular is a search, not a
+  judgement call. §4 and §5 usually arrive as open questions.
 - **Cite by §-number, not by line number.** Source comments cite plan sections; line numbers rot on the
   first edit, and a §-number survives the move into `archive/`.
 - **Never mark a phase `done` in a plan that has not been executed.** Every phase in a new plan is

package/templates/context/workflow.md

@@ -96,6 +96,20 @@ policy, resolves by committing on its own every phase. That is a call about some
 it is a written answer rather than an inference. Branching and pushing are outside it: nothing here creates
 a branch, pushes, or opens a pull request under either answer.
 
+### Documentation is part of the change
+
+> **Find where this project documents itself before planning — the Documentation index in
+> [`stack.md`](stack.md), and the repository itself when that index is missing or empty. Whatever a change
+> makes untrue there is fixed by the phase that makes it untrue, not by a follow-up.**
+
+Documentation is the one output with no gate behind it. Nothing fails when a README goes on describing a
+flag that was renamed, so the drift is invisible until someone follows the old instructions and it is not
+invisible to them. `/feature-plan` writes the affected surfaces into the plan's §7, each assigned to a
+phase, and that phase's **Files:** line carries the path like anything else it touches.
+
+*"Nothing here describes this feature"* is a legitimate answer, and it names the surfaces that were
+checked. Saying nothing is not that answer.
+
 ### Never transcribe a credential
 
 > **A DSN, token or key is described and pointed at the secret store, never copied into a tracked file.**
@@ -125,10 +139,16 @@ To pick the next phase: take the **lowest-numbered phase that is not `done` and
 are all `done`.** State which one you picked before starting. If it is already `in progress`, read its Note
 and resume — do not restart it.
 
+**A phase's row is written twice.** It opens to `in progress` when the work starts, before any code, and
+closes to `done`, `in progress` or `blocked` when the phase ends. The opening write is what makes an
+interruption survivable: a run that dies mid-phase leaves a tree with half the work in it, and the row is
+the only thing that can say so.
+
 `done` means the phase's scope landed and both gates passed — **a verdict about the gates, not about git.**
 Whoever finishes a phase updates its row **as part of the same change as the work**: one commit where the
-agent commits, one working tree handed over where the user does. A row updated separately is a row that
-disagrees with the repository in between.
+agent commits, one working tree handed over where the user does. A closing row updated separately is a row
+that disagrees with the repository in between. The opening write is not a change of its own — it is left in
+the tree and lands with the work it describes.
 
 If the ledger's claim disagrees with the repo — a phase marked `done` whose files do not exist, or the
 reverse — **stop and say so.** Never silently re-do or skip a phase on a stale ledger. A `done` row whose

package/templates/skills/feature-implement/SKILL.md

@@ -38,7 +38,8 @@ detailed it looks.
 This is the step that used to be structural: `/feature-plan` stopped and you typed a second command. It is
 explicit here now, or it is lost.
 
-1. **Surface the plan's §8 Open questions and require an acknowledgement.** Do not proceed on silence.
+1. **Surface the plan's Open questions section and require an acknowledgement.** Do not proceed on
+   silence. Cite it by name — a plan written against an earlier template numbers its sections differently.
 2. **Re-check that the files the plan cites still exist.** A plan drafted a month ago against a
    since-changed tree is a state that can now exist and could not before. Name anything that has moved.
 3. **Check the one-active-feature rule** in [`context/workflow.md`](../../../context/workflow.md). If
@@ -65,10 +66,31 @@ If the ledger's claim contradicts the repo — a phase marked `done` whose **Fil
 plainly in the tree under a phase marked `not started` — **say so and stop.** Never silently re-do or skip
 a phase on a stale ledger.
 
-## 6. Do the work
+## 6. Open the ledger row
+
+Set the phase's Status to `in progress` and write a Note naming what is underway — **before any code.**
+
+This row is what a *later* session reads. A phase interrupted here — context exhausted, session closed, run
+cancelled — leaves a working tree with half a phase in it. A row still reading `not started` sends the next
+run into step 5's disagreement stop, or into redoing work that is already there.
+
+One token and one Note, in the row that is already there — do not move the entry, restructure the table, or
+write a summary anywhere else. If the row is already `in progress` because you are resuming it, leave it
+alone; step 11 rewrites the Note.
+
+**This write is not a change of its own.** Leave it in the working tree — it lands with the phase's work
+under either answer in [`context/git.md`](../../../context/git.md). Never commit it on its own.
+
+## 7. Do the work
 
 Read the phase's §6.2 sub-section: its scope, its **Files:**, and what `done` means for it.
 
+**The plan's Documentation rows assigned to this phase are part of this phase**, not a follow-up — their
+paths are on the same **Files:** line as the code. Per the standing rule in
+[`context/workflow.md`](../../../context/workflow.md), whatever this phase makes untrue is fixed by this
+phase. If the work turned out differently from the plan and made something *else* untrue — a README the
+plan never listed — fix that too and say so; the sweep happened before the code existed.
+
 Delegate to a coder per [`context/executors.md`](../../../context/executors.md) if one is configured;
 otherwise implement in-host. The coder's system prompt is
 [`context/roles/coder.md`](../../../context/roles/coder.md).
@@ -79,7 +101,7 @@ this repository can open them, and a brief that inlines them is a brief that goe
 
 Describe **what** needs to happen, never **how** to code it. Scope each delegated task to specific files.
 
-## 7. Gate 1 — verification
+## 8. Gate 1 — verification
 
 Per the gate contract in [`context/workflow.md`](../../../context/workflow.md): read
 [`context/verify.md`](../../../context/verify.md) and run its sections in order — Lint → Typecheck → Build →
@@ -89,9 +111,9 @@ Test.
 so, never faked. Exit 0 is the verdict regardless of summary text. If `verify.md` does not exist or has no
 filled-in section, stop and say so. Docs-only changes run Lint plus a read of the diff.
 
-A failure is the verdict — go to step 9 with the failing output verbatim as the feedback.
+A failure is the verdict — go to step 10 with the failing output verbatim as the feedback.
 
-## 8. Gate 2 — review
+## 9. Gate 2 — review
 
 Dispatch per [`context/executors.md`](../../../context/executors.md). With no independent reviewer
 configured, review the diff yourself against the plan's review expectations and the standards — weaker, and
@@ -100,13 +122,13 @@ configured, review the diff yourself against the plan's review expectations and
 Require concrete evidence — file paths, command output — for every verdict, and a `P0`–`P3` severity on
 every blocking finding.
 
-- `PASS` or `PASS WITH NOTES` → the phase's work is done; go to step 10.
-- `FAIL` → **write it to [`context/findings.md`](../../../context/findings.md) first, then** go to step 9.
+- `PASS` or `PASS WITH NOTES` → the phase's work is done; go to step 11.
+- `FAIL` → **write it to [`context/findings.md`](../../../context/findings.md) first, then** go to step 10.
 
 **Write the finding before the loopback, not after it.** A verdict that lives only in this session's
 transcript evaporates when the conversation ends — including a `P0` the cap never got to.
 
-## 9. Loopback
+## 10. Loopback
 
 Cap: **two loops per gate, per phase.**
 
@@ -118,11 +140,12 @@ At the cap: **write a finding** (`P1` for a Gate 1 cap-out — a phase whose ver
 blocked by definition), then escalate to the user with the current state and the last feedback.
 **Escalating is not a substitute for recording.**
 
-## 10. Close out the ledger row
+## 11. Close out the ledger row
 
 The row is part of the same change as the work — never a separate step afterwards:
 
-- **All of the phase's scope landed and both gates passed** → `done`.
+- **All of the phase's scope landed and both gates passed** → `done`. Its documentation rows are part of
+  that scope: a phase whose doc update has not landed has not landed.
 - **Some landed** → stays `in progress`, Note rewritten to name exactly what remains.
 - **A gate hit its cap, or something external blocks it** → `blocked`, with the blocker in the Note.
 
@@ -131,7 +154,7 @@ open `P0` or `P1` is tied to this phase**; leave it `in progress` and name the f
 
 `done` is a verdict about the gates, not about git. Whether the change is committed at all is the next step.
 
-## 11. Land it — read [`context/git.md`](../../../context/git.md)
+## 12. Land it — read [`context/git.md`](../../../context/git.md)
 
 **Do not commit until you have read that file, and do not commit at all unless it says the agent does.**
 It is the only place this project's answer lives, the same way `verify.md` is the only place its commands
@@ -142,7 +165,7 @@ once, and name `/onboard`.
   and stop. Do not stage-and-commit "to be helpful", and do not push or branch under either answer.
 - **The agent commits** → the code and the ledger row in one commit, at the granularity that file names.
 
-## 12. Report
+## 13. Report
 
 - What changed, and which files — and whether it is committed or waiting in the tree.
 - Gate 1 output, and Gate 2's verdict.

package/templates/skills/feature-plan/SKILL.md

@@ -98,6 +98,13 @@ planner's own default shape:
   acceptance-criteria — a per-phase artifact, not a plan — and you will throw it away.
 - Pointers to `context/stack.md`, `context/standards/README.md` (load per its conditional table) and
   `context/verify.md`. Cite the paths; do not paste the files in. Anything reading this repo can open them.
+- **Where this project documents itself, and what this feature makes untrue there.** Start from the
+  Documentation section of `context/stack.md`. **If that section is empty, missing, or names less than the
+  tree plainly holds, sweep for it** — the root `README`, a `README` in each package, `docs/`, a docs site
+  or landing page in the repository, an API reference or OpenAPI document, a changelog, help text and
+  format comments that live in the code. Ask the user about anything hosted elsewhere: a wiki, a docs site
+  built from another repo, a published reference. **An index nobody filled in is not evidence that there
+  are no docs**, and a plan that assumes it is ships the drift.
 - **Cite file paths and command output for every claim about the current codebase.** Anything unverified is
   an open question, not an assertion.
 - Phases are **commit-sized units with checkable outcomes**, each with a real `Depends on` value and a
@@ -111,7 +118,11 @@ Fill in the template's shape. Then:
 - Date it and point its header at the roadmap entry.
 - **No `**Status:**` header.** Feature status lives in `roadmap.md`, phase status in the ledger. A document
   that claims its own status is a copy that goes stale.
-- Fill in **§8 Open questions** honestly. An honest gap is worth more than an invented decision.
+- Fill in **§7 Documentation** from what the sweep found: one row per surface the feature changes, each
+  assigned to the phase that carries it, **and that phase's `Files:` line names the same path.** A
+  documentation row with no phase is a follow-up nobody does. If nothing changes, say which surfaces you
+  checked and why none of them describe this — that is an answer, and leaving the section blank is not.
+- Fill in **§9 Open questions** honestly. An honest gap is worth more than an invented decision.
 - Every phase is `not started`.
 
 ### 6. Update the roadmap entry
@@ -129,7 +140,8 @@ own; discarding it over a marker would undo the point of the split.
 
 ### 7. Report and stop
 
-State the document path, the phase count, and the open questions. Then say plainly that **what you produced
+State the document path, the phase count, the documentation surfaces §7 commits to updating, and the open
+questions. Then say plainly that **what you produced
 is a reviewable skeleton plus open questions, not a finished plan of record** — the value is the structure
 and the research. Name the next step: the user reviews and edits the plan, and `/feature-implement` runs it
 once they are satisfied.

package/templates/skills/onboard/SKILL.md

@@ -9,6 +9,11 @@ Fills the project-owned stubs the installer deliberately left empty, and folds w
 already documented into them. **Re-runnable** — run it again after the stack changes, and it re-proposes
 against what is there now.
 
+**Run it after an `update`, too.** The updater replaces tool-owned files only; the stubs are project-owned
+and it cannot reach them, so a section a new version's stub gained arrives only through this command. The
+update prints the gaps it found under **Next** — every one of them is this command's work. Until it runs,
+a command can be pointed at a section of a file that does not have it.
+
 **Asking is not guessing.** The installer could have detected a test command and written it in; that is
 exactly how a file ends up naming a command that has never run. This command asks, and where it can, it
 *checks*.
@@ -22,7 +27,7 @@ Read [`context/workflow.md`](../../../context/workflow.md) for the tier model.
 | [`context/verify.md`](../../../context/verify.md) | the real Lint / Typecheck / Build / Test commands — **only ones that exited 0** |
 | [`context/executors.md`](../../../context/executors.md) | how this project dispatches a coder and a reviewer |
 | [`context/git.md`](../../../context/git.md) | who commits the work, and at what granularity |
-| [`context/stack.md`](../../../context/stack.md) | runtime, layout, conventions |
+| [`context/stack.md`](../../../context/stack.md) | runtime, layout, conventions, and the index of where this project documents itself |
 | [`AGENTS.md`](../../../AGENTS.md) | pruned, on confirmation, of what moved into those four. The region between the `ai-workflow` markers is never touched |
 
 Show every proposed edit before writing it, and **do not commit.** The user reviews and commits.
@@ -45,6 +50,7 @@ Break what you read into claims — a paragraph, a table row, a bullet — and p
 | A claim about | Goes to |
 |---|---|
 | what the project is, its layout, its conventions | `context/stack.md` |
+| where the project's own documentation lives, or how it is published | `context/stack.md`, its Documentation section |
 | a lint, typecheck, build or test command | a **candidate** for `context/verify.md` — Step 6 still has to run it |
 | how a coder or a reviewer is dispatched | `context/executors.md` |
 | a rule about who commits, or when work is committed | `context/git.md` |
@@ -69,6 +75,11 @@ old file is a candidate like any other and still has to run.
 
 On a re-run, a claim its destination file already states is already adopted. Say so in a line and move on.
 
+**If an `update` named a missing section** — `context/stack.md` with no Documentation section, a stub that
+is not there at all — add the heading in the shipped stub's order, then fill it through the step below that
+owns it. Do not rewrite what is already there to match a newer stub: the section is the part that is new,
+not the prose someone wrote about their own project.
+
 ## Step 2 — Coder dispatch
 
 Ask whether implementation runs **in-host** or is **offloaded** to an external coder CLI.
@@ -183,6 +194,23 @@ Start from what Step 1 routed here, show it back as a draft, and ask only for th
   that earns its keep; the rest is discoverable. Inherited prose is usually strongest here and weakest at
   describing layout, which drifts.
 
+Then fill in the **Documentation** section, which is the one every later plan reads:
+
+1. **Sweep the repository.** The root `README`, a `README` in every package, `docs/`, a docs site or
+   landing page built from this repo, an API reference or OpenAPI document, a changelog, a `man` page or
+   `--help` text that lives in the code, a comment that is the only description of a file format.
+2. **Ask what is published elsewhere** — a wiki, a hosted docs site built from another repository, a
+   support centre, a public API reference. Nothing in the tree can reveal those, and they are the surfaces
+   that rot longest without anyone noticing.
+3. **Ask which of them are actually maintained.** A directory nobody has touched in two years is worth
+   recording as exactly that; a plan can then say so instead of proposing an update to a dead file.
+4. **Write "none" if there is none.** An empty section reads as "nobody checked", and `/feature-plan`
+   cannot tell those apart — it sweeps the tree itself when the section is empty, which finds files but
+   never finds the docs site nobody mentioned.
+
+Say what this is for: every plan's §7 starts from this list, and whatever a feature makes untrue there is
+fixed by the phase that makes it untrue.
+
 Point out that anything else added under `context/` should be indexed in `stack.md`, not in
 `context/README.md`, which is tool-owned and replaced on update.
 

package/templates/skills/orchestrate/SKILL.md

@@ -45,6 +45,11 @@ A refusal here is the workflow working.
 
 Read `context/stack.md` and load `context/standards/README.md` per its conditional table.
 
+**Check that file's Documentation section, and the tree if it is empty.** If this change makes something
+there wrong — a README, a docs page, a changelog, help text in the code — the fix is part of this change,
+per the standing rule in [`context/workflow.md`](../../../context/workflow.md). A one-shot change is where
+that gets skipped most, because there is no plan holding the row.
+
 Delegate to a coder per [`context/executors.md`](../../../context/executors.md) if one is configured;
 otherwise implement in-host. The coder's system prompt is
 [`context/roles/coder.md`](../../../context/roles/coder.md). The brief **cites paths, it does not paste

package/templates/stubs/stack.md

@@ -25,6 +25,19 @@ What this project is, and what an agent has to know before touching it. Run `/on
      things deliberately kept separate, where local secrets live, what must never be run against
      production. -->
 
+## Documentation
+
+<!-- Every place this project explains itself, one line each: the path or URL, who reads it, and what kind
+     of change has to reach it. READMEs at the root and in each package, docs/, a docs site or landing page,
+     an API reference or OpenAPI document, a changelog, a wiki, help text that lives in the code, comments
+     that are the only description of a format.
+
+     Say which ones are actually maintained — a directory nobody has updated in two years is worth writing
+     down as that, rather than leaving the next reader to discover it.
+
+     If this project documents itself nowhere, write "none". An empty section reads as "nobody checked",
+     and a plan cannot tell those two apart. -->
+
 ## Also in `context/`
 
 <!-- Index anything you add under context/ here — decisions.md, glossary.md, ops-notes.md. Not in