@antoneeo/agentic-sdlc-skill 1.20.3 → 1.21.1

package/CHANGELOG.md

@@ -2,6 +2,237 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.21.1 / kb 1.4.1 / mkt 0.4.1] - 2026-08-03
+
+### Added
+- **`version:` in every `SKILL.md` frontmatter.** An installed skill carries no
+  `package.json` and no `gemini-extension.json` — only doctrine and scripts — so nothing
+  in it said which build it was. Answering "is that fix in your copy?" took `npm view`
+  plus a shasum comparison; from a user's side it was unanswerable. Now the first thing
+  in the operating contract says it.
+- **A battery invariant asserting every bump point agrees** (`SKILL.md` ↔ `package.json`
+  ↔ `gemini-extension.json`). A hand-maintained version string rots, and this repository
+  has the scar: the third bump point was skipped for two whole releases with nothing to
+  catch it. The fourth arrives with its guard attached, and `GUIDE_release.md` step 1
+  now says FOUR.
+
+## [1.21.0 / kb 1.4.0 / mkt 0.4.0] - 2026-08-03
+
+F-028 — several people on one project. `templates.md` had claimed the workstream
+registry was "Parallel-safe by construction" since F-019, and nothing had ever exercised
+it. Two workstreams opened from one base conflict **twice in one file**: on the row
+insert, and on the file-global `Date:` header. Row-level ownership cannot save a file
+that has a file-level field.
+
+### Changed
+- **`audit/handoff.md` is now GENERATED** from one `HANDOFF_[unit].md` per open
+  workstream, whose frontmatter IS the row. Two writers on two workstreams touch two
+  different files, and the `Date:` header is derived — from the newest `updated:` VALUE
+  in the sources, never a filesystem timestamp (git does not preserve mtimes, and an
+  mtime-derived header would make the file regenerate differently in every fresh clone).
+- **`HANDOFF_[unit].md` is now written for every OPEN workstream**, with or without
+  volatile state — no file, no row. It still carries the resume logistics, and deleting
+  it at closure *is* what removes the row. The DRY boundary against the ANALYSIS Diary
+  is restated in the template, because what used to keep narrative out of that file was
+  its rarity, and the rarity is gone.
+- Project-wide notes move to their own source, `audit/project_notes.md`, so generating
+  the registry cannot destroy notes that belong to no workstream.
+
+### Added
+- **`validate` errors when the registry disagrees with its sources** — which is what
+  turns a merge resolved carelessly from permanent into loud. Resolution is mechanical:
+  re-run `index`. The generated view can still conflict; the authored truth does not.
+- **`index` refuses to write while anything in the file is unaccounted for**, and names
+  it. Converting one row at a time is the state that loses the others, so conversion is
+  per project. A project with no sources is untouched and sees no new finding.
+- **`init` writes a `.gitattributes` stanza** giving the append-only review log
+  `merge=union` — a **built-in** driver, unlike `merge=ours`, which silently does
+  nothing until every clone runs `git config` and leaves the file wrong even then.
+  Create-only; a user's own `.gitattributes` is never clobbered.
+- `scripts/test_merge_safety.py` (shared, ×3): the experiment that found the defect,
+  kept as a regression test — two workstreams from one base, merged, with the assertion
+  that only the generated view may conflict and that regenerating loses no state. Plus
+  the mixed-state, fresh-mtime, ordering, cap and duplicate-id guards, each
+  mutation-verified.
+- A warning when two files claim the same workstream: the collision this design does
+  **not** fix (two people opening the same work under two names) must not pass as two
+  ordinary rows.
+
+The mechanism is files and a generator: **it works with no VCS at all.** The
+`.gitattributes` stanza is defence in depth — without it the outcome is today's, one
+conflict resolved by hand, never a lost row.
+
+### Upgrading
+Nothing happens until you convert: with no `HANDOFF_*.md` sources, `index` and
+`validate` behave exactly as before. When you convert, convert the whole registry at
+once — `index` will tell you what is still unaccounted for.
+
+## [kb 1.3.0] - 2026-08-03
+
+F-031 — from the field: *"the ingestion agent takes shortcuts, and a lot of information
+is lost. The graph works only if all of a file's information is poured into it."* An
+agent handed a 200-page manual emitted a few dozen claims and reported done. Nothing it
+did broke a rule — and that is the finding. `distillation.md` carried a floor ("the
+extractor invents nothing") and no target, so an agent optimizing against it stops the
+moment nothing it wrote is false. **Nothing the field agent emitted was wrong.** Third
+appearance of one class: a rule that describes a good output and never says which
+outputs must exist.
+
+### Added
+- **A north star at the top of `distillation.md`**, above the rules rather than beside
+  them: *not one assertion the source makes may be lost, and not one it does not make
+  may appear.* One sentence, deliberately — two rules a paragraph apart get optimized
+  whichever was read last. The unit is the **assertion**, not the byte: layout and page
+  furniture are not assertions, exhaustive means **read** and never *a row per page*.
+- **`extracted_through:`** on the artifact's own sidecar (`p=<n>`, `L<n>`, `complete`) —
+  required once any claim cites it. It is what makes "I am finished" falsifiable, and it
+  makes the rows and the field check each other: claims with no coverage recorded error;
+  a claim addressing past the declared coverage, or coverage past the end of the stored
+  bytes, is a contradiction and errors; coverage short of the end warns, because partial
+  work is legal mid-ingestion. An artifact nobody has extracted from owes nothing.
+- **Bounded reading windows** — 30 pages by default, *the plan states the window used*
+  (a hard number baked into doctrine ages badly across models and page densities). One
+  plan task per window: the existing `PLAN_[topic].md` ledger is the register an
+  ingestion resumes from across sessions, so **no second register was built** — one
+  would have been the work board this method refuses.
+- **A coverage cell in `corpus/INDEX.md`**, printed for **every** artifact including the
+  finished ones. A list of only what is behind is the dashboard the Vision rejects, and
+  a test fails the suite if the report ever becomes one.
+- Cold-run scenario `long_source_is_exhausted_not_sampled.md`: sampling a long source and
+  reporting it ingested is the FAIL — and so is manufacturing a row per page.
+
+The limit is stated wherever the field is written, as with `original_sha256`: **nothing
+proves a page was read.** A field advanced without extracting is invisible to any
+checker, precisely because a page that asserts nothing legitimately yields no rows — that
+direction belongs to the ingestion review. What changed is that the shortcut must now be
+written down to pass, and a written claim can be reopened by anyone who cares to.
+
+### Upgrading an existing corpus
+`check` will error on every `corpus/given/` artifact that has claims and no
+`extracted_through:`. That is the migration, and it is the point: state how far each
+source was actually read (`complete` if it was finished). The message names the artifact,
+the first row citing it, and the three accepted forms. `corpus/INDEX.md` gains the
+coverage cell, so run `sdlc_check.py index` once — until then `validate` reports it
+out of alignment, as it does for any generated index.
+
+## [kb 1.2.0] - 2026-08-03
+
+F-030 — knowledge built in one project could not leave it. A practitioner who grounded
+82 claims against a vendor's manuals started the next project with nothing and paid the
+whole ingestion again from the same sources. The Core Problem this methodology exists
+against is that understanding evaporates; it was evaporating at the **project boundary**.
+
+### Added
+- **`export --out <dir>`** bundles a subgraph together with **the bytes its claims
+  cite** — a closure, not a selection. A claim whose source cannot be reopened is model
+  knowledge arriving by another route, so the artifacts, sidecars and extractions travel
+  with it. The closure also pulls in the other half of any `CONTESTED` set, because the
+  symmetry check refuses a set that lost members — and says which topics it added, never
+  silently.
+- **`import <dir>`** merges a bundle **additively**: never overwrites a node, never
+  deletes, and computes the whole plan before writing a byte (an import that half-applies
+  leaves a tree whose checks fail and whose owner cannot tell what landed). Refuses on a
+  path escaping the docs root, an artifact whose name matches an existing one with
+  different bytes, a directory carrying no `MANIFEST.md`, and a broken conflict set.
+  Placing an incoming concept stays the placement pass's job (`taxonomy.md`) — the import
+  reports the skipped node and decides nothing.
+- **`prov: IMPORTED`** (owner ruling, 2026-08-03). Knowledge crosses a project boundary;
+  authority does not. A ruling from another project keeps its text, span and original
+  `basis:` verbatim, must declare `imported_from:`, and **cannot supersede a local row**
+  — the validator errors on it. Re-ratification is one honest act: your own note, your
+  own basis, `prov: RULING`. Relabelling it `DERIVED` was rejected because the row would
+  then lie about where it came from.
+- **`portability.md`**, the doctrine the two commands cite.
+
+The feature is small because of one property it did not have to build: `kb_claim_id`
+hashes `path#locator#qty` with the **text excluded**, so the same artifact cited at the
+same span mints the same id in every project. Cross-project de-duplication is therefore
+mechanical rather than a judgement call, and importing the same bundle twice is a
+provable no-op.
+
+## [kb 1.1.1] - 2026-08-03
+
+Three inconsistencies the same field practitioner found by reading 1.1.0 against
+their own corpus — all of the class 1.1.0 exists to remove: the doctrine and the
+machinery disagreeing, where an agent reads one and the checker obeys the other.
+
+### Fixed
+- **`SKILL.md` never named `anchor`.** The command shipped working and listed in
+  `--help`, while the support-file line still said "the knowledge overlay: `graph`,
+  `corpus`, `claim-id`" — so an agent reading only the doctrine never learned it
+  exists, which is how the practitioner found it (from the prose, by accident). New
+  kb invariant derives the expected list from `INTERCEPTED` and fails when SKILL.md
+  omits any of it; deriving is the point, a second hand-maintained list would be the
+  same defect again.
+- **Two rules gave opposite outcomes on a binary corpus.** The Write Triggers row for
+  `corpus/given/*` still read "verbatim copy … non-text originals **also** get their
+  stored canonical extraction", contradicting the extraction-as-artifact rule added to
+  `distillation.md` §1 in 1.1.0. The row now states both forms and names §1 as the
+  owner of the rule.
+- **`anchor` only worked from inside the docs root**, an asymmetry with `graph`,
+  `corpus` and `check`, which take `--root`. Those scan a tree and this one takes a
+  path, so the fix is to make the path resolve rather than to document where to stand:
+  a path that does not resolve from the current directory is retried under the docs
+  root, which means it can be given exactly as a claim's `source` cell carries it.
+
+## [kb 1.1.0] - 2026-08-03
+
+Scoped to `@antoneeo/kb-agentic-skill`. `agentic-sdlc-skill` (1.20.3) and
+`mkt-agentic-sdlc` (0.3.1) are unchanged in what they ship: the shared invariant
+added here lives in `test_skill_invariants.py`, which no distribution packages.
+
+F-029 — six defects from the first full field application of `kb-agentic` by a
+practitioner other than its author (233 MB of manuals, 51 corpus artifacts, 22 topic
+nodes, 82 offset-verified claims). **None was an adherence failure**: in every one the
+agent did what it was told and was wrong anyway, which makes them agent-UX defects.
+Analysis: `ai_docs/solutions/ANALYSIS_kb_field_report.md`.
+
+### Fixed
+- **kb's triage levels were undecidable.** L1 and L2 carried the *identical* bound
+  ("at most 1-2 files"), so no request could be classified L2 and anything touching
+  three files fell to L3 by "when in doubt, go higher". Root cause: kb never performed
+  the restatement the Vision requires of every sibling — the file counts were the code
+  lens's units, and they contradicted the escalation triggers two lines below them.
+  Restated in knowledge units by owner ruling (2026-08-02): one claim row → propagation
+  of an already-settled fact → a new knowledge unit. The one limit: propagation that
+  changes what a claim *asserts* is not propagation. New shared invariant asserts no two
+  graded levels state the same criteria, lens-agnostically (`L1..L3` here, `E1..E3` in
+  marketing) — mutation-tested RED before the fix.
+- **The claim model recorded powers and skipped gates**, making every ledger
+  systematically optimistic on a corpus whose purpose is to deflate over-promising. A
+  query returned three verified rows saying "yes, supported" while omitting that the
+  feature ships disabled and needs a second construct — true, and a plan that fails on
+  site. `distillation.md` §3 now requires the gates alongside the powers, with the guard
+  that keeps it from becoming fabrication: the rule is *ask*, never *produce*.
+- **`--help` hid the knowledge overlay.** Forward-by-default handed `--help` to the
+  spine, whose usage lists nine commands and none of kb's, so a user concluded the
+  overlay was not installed. Intercepted at `argv[0]` only, and the spine's own usage is
+  still rendered — forward-by-default is intact, with a regression test that proves a
+  non-intercepted command still reaches the spine.
+- **kb's eval battery tested the wrong skill.** Six scenarios, none covering kb's own
+  method, two byte-identical to the code lens's and exercising an architect pass kb does
+  not ship — while extraction, placement, reconciliation, the corpus letter and locators
+  had no cold-run coverage at all. Rewritten in kb's units, three new scenarios added,
+  and a new invariant refuses any scenario citing a support file its distribution lacks.
+  The ANALYSIS template's example rows were the code lens's verbatim (Python paths in a
+  knowledge template); replaced with topic-graph rows.
+
+### Added
+- **`sdlc_check.py anchor <path> <phrase>`** — the half `claim-id` never had: it turns a
+  prose citation into a *verified* span. The check has always demanded resolved locators
+  and nothing produced them, so every one was hand-authored against a machine verifier.
+  Whitespace in the phrase matches as `\s+`, because a PDF extraction breaks phrases
+  mid-line and a probe that pretty-prints collapsed whitespace shows the phrase intact
+  while the checker sees the break. Refuses ambiguity and refuses what it cannot anchor,
+  and re-verifies every locator with `kb_check_locator` before emitting it — the tool can
+  never produce a span its own validator would reject.
+- **Extraction-as-artifact** for large binary corpora (`distillation.md` §1): the stored
+  extraction may be the corpus artifact on its own, `sha256:` covering it, with the
+  original recorded as `original_path:` + `original_sha256:` instead of copied in. The
+  code already allowed this; the doctrine said the extraction came "additionally", so a
+  faithful reader copied gigabytes for nothing. The recorded fields state their limit
+  where they are defined: `original_sha256` is never checked.
+
 ## [1.20.3] - 2026-08-02
 
 Three defects found by a field test in which cold agents operated the three published

package/README.md

@@ -9,6 +9,7 @@
 - **Architect pass — capabilities before files**: at L3, before listing what changes, the feature is stated as the *capabilities* it needs and each is ruled against the platform (EXISTS / INADEQUATE / MISSING); what is missing is designed as a component with its own contract, of which the feature is one consumer — never inlined into the feature's code path. A `## Component Map` in `strategic/architecture.md` is the durable inventory the pass reads, so the platform is not re-derived from source every session. On a codebase the methodology arrives in late, the map's silence is treated as **unread, not empty**: it can never ground a MISSING verdict.
 - **Execution disciplines**: explicit TDD (RED/GREEN/REFACTOR), systematic debugging, an L3 spec-elicitation round, and a single code-review definition wired into the workflow phases.
 - **Operative + comprehension guides + agent-global KB**: distil user-provided indications into source-faithful operative `GUIDE_*.md` (`source_kind: document`), and let the agent autonomously author **code-comprehension guides** (`source_kind: code`) for complex components — a source-faithful mental-model map that survives across sessions, so the next session doesn't re-derive and break the component from partial understanding. Consulted before work; shared cross-project via `~/.agentic-sdlc`.
+- **Several people, one project**: the workstream registry (`audit/handoff.md`) is **generated** from one file per open workstream, so two people opening or closing two workstreams on two branches edit two different files and their merge is clean. Row-per-workstream alone was not enough — a file-global `Date:` header defeats row-level ownership — so the header is derived from the sources and no writer touches it. The generated view can still conflict; that conflict is resolved by re-running `index`, never by hand, and `validate` refuses CLEAN until the file matches its sources. The append-only review log gets `merge=union` (a built-in driver, no per-clone configuration). It all works with no VCS at all: it is files and a generator.
 - **Opt-in subagent execution**: an approved design projects into a validated executable plan an orchestrator can drive through subagents.
 - **Self-activating**: a SessionStart hook emits repo-sourced orientation; a deterministic self-eval battery guards the skill's own doctrine as the release gate.
 - **Standalone complete**: works fully with local `ai_docs/` without requiring devPNT.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.20.3",
+  "version": "1.21.1",
   "description": "Documentation-First SDLC protocol with triage, Vision governance and optional devPNT integration.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,50 +1,50 @@
-{
-  "name": "@antoneeo/agentic-sdlc-skill",
-  "version": "1.20.3",
-  "description": "Documentation-First SDLC protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, installed support files and optional devPNT integration.",
-  "keywords": [
-    "claude-code",
-    "claude-skill",
-    "gemini-cli",
-    "skill",
-    "sdlc",
-    "documentation",
-    "ai-agent"
-  ],
-  "author": "Antonio Pinto (https://github.com/Antoneeo)",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "bin": {
-    "agentic-sdlc-init": "scripts/init.js",
-    "agentic-sdlc-install-skill": "scripts/postinstall.js"
-  },
-  "scripts": {
-    "postinstall": "node scripts/postinstall.js",
-    "preuninstall": "node scripts/preuninstall.js"
-  },
-  "files": [
-    "skills/agentic-sdlc-skill/SKILL.md",
-    "skills/agentic-sdlc-skill/templates.md",
-    "skills/agentic-sdlc-skill/architect.md",
-    "skills/agentic-sdlc-skill/guides.md",
-    "skills/agentic-sdlc-skill/vision.md",
-    "skills/agentic-sdlc-skill/tdd.md",
-    "skills/agentic-sdlc-skill/debugging.md",
-    "skills/agentic-sdlc-skill/elicitation.md",
-    "skills/agentic-sdlc-skill/review.md",
-    "skills/agentic-sdlc-skill/dispatch.md",
-    "skills/agentic-sdlc-skill/routing.md",
-    "skills/agentic-sdlc-skill/ENFORCEMENT.md",
-    "skills/agentic-sdlc-skill/scripts/sdlc_check.py",
-    "skills/agentic-sdlc-skill/scripts/sdlc_core.py",
-    "gemini-extension.json",
-    "README.md",
-    "CHANGELOG.md",
-    "scripts/lib.js",
-    "scripts/init.js",
-    "scripts/postinstall.js",
-    "scripts/preuninstall.js"
-  ]
-}
+{
+  "name": "@antoneeo/agentic-sdlc-skill",
+  "version": "1.21.1",
+  "description": "Documentation-First SDLC protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, installed support files and optional devPNT integration.",
+  "keywords": [
+    "claude-code",
+    "claude-skill",
+    "gemini-cli",
+    "skill",
+    "sdlc",
+    "documentation",
+    "ai-agent"
+  ],
+  "author": "Antonio Pinto (https://github.com/Antoneeo)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "agentic-sdlc-init": "scripts/init.js",
+    "agentic-sdlc-install-skill": "scripts/postinstall.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "preuninstall": "node scripts/preuninstall.js"
+  },
+  "files": [
+    "skills/agentic-sdlc-skill/SKILL.md",
+    "skills/agentic-sdlc-skill/templates.md",
+    "skills/agentic-sdlc-skill/architect.md",
+    "skills/agentic-sdlc-skill/guides.md",
+    "skills/agentic-sdlc-skill/vision.md",
+    "skills/agentic-sdlc-skill/tdd.md",
+    "skills/agentic-sdlc-skill/debugging.md",
+    "skills/agentic-sdlc-skill/elicitation.md",
+    "skills/agentic-sdlc-skill/review.md",
+    "skills/agentic-sdlc-skill/dispatch.md",
+    "skills/agentic-sdlc-skill/routing.md",
+    "skills/agentic-sdlc-skill/ENFORCEMENT.md",
+    "skills/agentic-sdlc-skill/scripts/sdlc_check.py",
+    "skills/agentic-sdlc-skill/scripts/sdlc_core.py",
+    "gemini-extension.json",
+    "README.md",
+    "CHANGELOG.md",
+    "scripts/lib.js",
+    "scripts/init.js",
+    "scripts/postinstall.js",
+    "scripts/preuninstall.js"
+  ]
+}

package/scripts/init.js

@@ -112,6 +112,34 @@ const writeIfNotExists = (relPath, content, description) => {
 
 seedFiles.forEach(([relPath, content]) => writeIfNotExists(relPath, content));
 
+const EOL = String.fromCharCode(10);
+// 5b. Merge hygiene for the append-only review log (F-028, defence in depth).
+// `merge=union` is a BUILT-IN driver: no per-clone `git config`, unlike
+// `merge=ours`, which silently does nothing until every clone configures it.
+// Rows are date-stamped, so interleaving them loses no information and their
+// order carries none. Create-only, and appended rather than rewritten: a user's
+// own .gitattributes is never clobbered.
+const gitattributes = () => {
+  const marker = 'ai_docs/audit/reviews/REVIEW_LOG.md';
+  const stanza = [
+    '',
+    '# agentic-sdlc: the review log is append-only and its rows are date-stamped,',
+    '# so a union merge keeps both sides instead of asking a human to pick one.',
+    marker + ' merge=union',
+    '',
+  ].join(EOL);
+  const filePath = path.join(cwd, '.gitattributes');
+  if (!fs.existsSync(path.join(cwd, '.git'))) return;   // not a git repo: nothing to do
+  const current = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+  if (current.includes(marker)) {
+    console.log('SKIP  .gitattributes already covers the review log.');
+    return;
+  }
+  fs.writeFileSync(filePath, current + stanza, 'utf8');
+  console.log('OK    .gitattributes: review log set to merge=union (concurrent reviews merge cleanly).');
+};
+gitattributes();
+
 // 6. Client discovery and protocol pointers
 console.log('\n--- Environment Analysis ---');
 

package/skills/agentic-sdlc-skill/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: agentic-sdlc
+version: 1.21.1
 description: Documentation-First SDLC protocol with risk-proportional triage, Vision as a guide, a complete Standalone mode and optional symbiosis with devPNT. Use for features, significant bugs, refactors, audits and documented maintenance.
 author: Antonio Pinto (https://github.com/Antoneeo)
 copyright: (c) 2026 Antonio Pinto
@@ -64,9 +65,10 @@ Triage decides IF documentation is due; this table decides WHICH document each e
 | `solutions/ANALYSIS_[feature].md` | Every L3, after elicitation and before any code. On topic match with an existing analysis, update that one instead of a new file. A capability the architect pass splits out as its own unit of change (`architect.md` §4) gets its own ANALYSIS, and the two documents name each other. | 3 |
 | `solutions/SPIKE_[topic].md` | Closing any Spike — including a failed one (a negative outcome is still an outcome). | — |
 | `vision/features/VISION_[feature].md` | Feature known multi-milestone at analysis time, OR the retroactive trigger: you are about to create the SECOND `ANALYSIS_*` on the same theme — extract the shared feature vision first, then let both analyses reference it. | 3 |
-| `audit/handoff.md` (workstream registry) | One row per OPEN workstream (feature, level, branch, status, since, next step, pointer to its Diary/HANDOFF file) — parallel-safe: closing one milestone touches one row, never another's resume point. Refresh the row at every L3 closure (remove it) and at session end when that ANALYSIS is IN_PROGRESS; discretionary after an L2. ≤ 20 lines. | 5 / session end |
-| `audit/handoff.md` — legacy narrative form (pre-1.17 projects) | **Convert lazily, on first write, never as a migration sweep.** A narrative handoff still works: read it as a single-row registry (`## Active features` bullets = the rows, `## Next step` = that row's next step). The first time the Write Trigger above fires, write it in registry form; until then, leave it. Nothing breaks in the meantime — the validator checks only the `Date:` header and its age, and the `orient` hook reads the file verbatim at the same path. | 5 / session end |
-| `audit/HANDOFF_[feature].md` | Session ends with that feature unfinished AND there is volatile resume state (branch/worktree, uncommitted work, environment notes, next command). **Resume logistics only — the ANALYSIS Diary keeps the durable narrative (DRY)**; the file is ephemeral and is DELETED at that feature's closure, same step that flips the ANALYSIS to COMPLETED. | 4 / 5 / session end |
+| `audit/handoff.md` (workstream registry) | **Never by hand — generated by `sdlc_check.py index` from the `HANDOFF_*.md` sources**, and `validate` errors when the two disagree. Regenerate at every L3 closure and at session end; the `Date:` header is derived, so no writer touches it. It is an inventory for lookup, not a work board: no assignment, no due dates, no ordering, no holder. | 5 / session end |
+| `audit/HANDOFF_[feature].md` | **One per OPEN workstream, with or without volatile state** — it is the authored home of that workstream's registry row (frontmatter `workstream`/`level`/`branch`/`status`/`since`/`next`/`details`/`updated`), so no file means no row. Also carries the resume logistics; **the ANALYSIS Diary keeps the durable narrative (DRY)**, and this file is DELETED at closure — deleting it *is* removing the row. | 4 / 5 / session end |
+| `audit/project_notes.md` | A note true for the whole project rather than for one workstream (release pending, environment quirk). Appended verbatim to the generated registry; it exists so regenerating cannot destroy notes that belong to no workstream. | 5 / session end |
+| `audit/handoff.md` — converting an existing project (hand-written or pre-1.17 narrative) | **Lazily, at the first write — and then ALL AT ONCE.** Converting one row at a time is the state that loses the others, so `index` refuses to write while anything in the file is unaccounted for and names it. Until the first source file exists nothing generates, nothing errors, and the file is read verbatim exactly as today. | 5 / session end |
 | `audit/audit_plan.md` (Standalone) | Bootstrap, and whenever a mapped area changes state (`sdlc_check.py mark` records the reference — git hash, else UTC timestamp). | 1 |
 | `reference/GUIDE_[topic].md` (`source_kind: document`) | Origin+purpose test (`guides.md`), or a proactive proposal the user accepted. Propose, never a silent write, never from model knowledge. | 4 / 5 |
 | `reference/GUIDE_[topic].md` (`source_kind: code`) | Recognized high-complexity component/feature/layer with no CURRENT guide — including one that breaks repeatedly across sessions → **duty to write autonomously** (no proposal; additive, code-anchored, reversible). Fidelity floor: every claim traces to a code excerpt. Signals + guard-rails: `guides.md` §1. Write it as soon as you recognize the signal; the Phase-5 Comprehension checkpoint is the backstop that asks the question, never the only moment it may fire. | 4 / 5 |
@@ -188,7 +190,7 @@ gate) instead of requiring an IN_PROGRESS ANALYSIS.
 
 ### 1. Audit and Alignment
 
-- Read `ai_docs/audit/handoff.md` if it exists — the **workstream registry**: one row per open workstream, so you see at a glance what is in PROGRESS, on which branch, since when, before touching anything. If a row's Date/Branch are inconsistent with reality, treat that row as history. When resuming a specific workstream, read its `audit/HANDOFF_[feature].md` (volatile resume logistics) AND its ANALYSIS Diary (durable narrative) — the registry row points at both. A **narrative handoff from a pre-1.17 project** reads as a single-row registry; convert it when you next write it, not now (Write Triggers).
+- Read `ai_docs/audit/handoff.md` if it exists — the **workstream registry**: one row per open workstream, so you see at a glance what is in PROGRESS, on which branch, since when, before touching anything. It is generated from the `HANDOFF_*.md` files, so it is read here and never edited here. If a row's Date/Branch are inconsistent with reality, treat that row as history. When resuming a specific workstream, read its `audit/HANDOFF_[feature].md` (its row plus the resume logistics) AND its ANALYSIS Diary (the durable narrative) — the registry row points at both. A hand-written or pre-1.17 narrative handoff still works and is converted when you next write it, not now (Write Triggers).
 - Read `ai_docs/README.md` (curated must-reads), `ai_docs/INDEX.md` (generated manifest of all canonical docs) and `ai_docs/reference/INDEX.md` (the guide router) to know what exists before exploring the code. The router is a mandatory read, not an optional one: it is the only orientation step that tells you a guide already governs the work you are about to do. On a project with no guides yet it exists as an empty stub (`sdlc_check.py index` writes it precisely so the mandatory read has something to read) — the honest verdict there is `router: no match`, and if the file is genuinely absent, say `router: absent (no router file)` and regenerate it rather than inventing a match. `solutions/` and `audit/` are not indexed per file: search them with glob/grep.
 - Recommended default: a SessionStart hook (`ENFORCEMENT.md` §4) emits this orientation automatically at session start (README + INDEX + guide router + handoff + triage reminder), so the router reaches the context even in a session that never opens Phase 1 explicitly. Wire it wherever Python is available; when it is not wired, do these reads manually as above — the process never depends on it, and it fails open (a missing/empty `ai_docs/` never blocks the session).
 - If `ai_docs/` is missing or incomplete, create the structure and the **bootstrap set** by analyzing the project in batches: `README.md`, the three `vision/` docs (`Status: DRAFT`), `strategic/architecture.md`, `strategic/existing_features.md` and — Standalone — `audit/audit_plan.md`; then regenerate `INDEX.md`. Nothing else is mandatory at bootstrap (per-document triggers: Write Triggers).
@@ -255,7 +257,7 @@ Hybrid L3:
 - If the work was governed by user-provided indications and is reusable, **PROPOSE distilling a guide** (proactive trigger, `guides.md` §1) — a proposal for the user, never a silent write, never from model knowledge.
 - **Comprehension checkpoint**: ask explicitly — *did this session force me to build a model of a high-complexity component that no CURRENT guide covers?* If yes, WRITE the `source_kind: code` guide now (a duty, not a proposal — `guides.md` §1) and say so in the closure. The knowledge you paid to build is at its most complete right here; one closure later it is gone, and the next session re-derives it or breaks the component from partial understanding.
 - Update only the documents actually impacted.
-- **Update the workstream registry (`audit/handoff.md`)** — mandatory at every L3 closure: REMOVE the closed workstream's row and DELETE its `audit/HANDOFF_[feature].md` (history lives in git and in the Diary); leave every other row untouched — that is the parallel-safety the registry exists for. ≤ 20 lines. The session-end rule and the L2 case: Write Triggers.
+- **Update the workstream registry (`audit/handoff.md`)** — mandatory at every L3 closure: DELETE the closed workstream's `audit/HANDOFF_[feature].md` (history lives in git and in the Diary) and re-run `sdlc_check.py index`. Deleting the file *is* removing the row, and no other workstream's file is touched — that is the parallel-safety the registry exists for. Never edit the generated file: `validate` errors when it disagrees with its sources. The session-end rule and the L2 case: Write Triggers.
 - **Aligned indexes (Poka-Yoke)**: if you created, moved or removed canonical documents (`vision/`, `reference/`, `architecture/`, `functional/`, `strategic/`):
   - regenerate the manifest with `sdlc_check.py index` (writes `ai_docs/INDEX.md`) — never write it by hand;
   - if the document is a must-read, add/update its line in the curated `README.md`;

package/skills/agentic-sdlc-skill/scripts/sdlc_core.py

@@ -215,7 +215,11 @@ DEFAULT_DOMAIN = "code"
 PORTABLE_CHECKS = {}
 # Which check namespaces this distribution actually carries. Set by the entry point;
 # a `checks:` entry outside it WARNS visibly rather than passing silently.
-_ENTRY_POINT = {"domain": DEFAULT_DOMAIN, "provides": ()}
+_ENTRY_POINT = {"domain": DEFAULT_DOMAIN, "provides": (), "script": "sdlc_check.py"}
+# "script" is what generated headers tell the reader to RUN. Declared, never
+# derived from sys.argv: the generated bytes must not depend on how the command
+# was invoked, or the alignment check would fail on the invocation instead of on
+# the content.
 
 
 # --- distribution profile ----------------------------------------------------
@@ -292,10 +296,17 @@ def portable_check(name):
     return register
 
 
-def set_entry_point(domain, provides=()):
+def set_entry_point(domain, provides=(), script=None):
     """Declare which domain this distribution is and which check namespaces it ships."""
     _ENTRY_POINT["domain"] = domain
     _ENTRY_POINT["provides"] = tuple(provides)
+    if script:
+        _ENTRY_POINT["script"] = script
+
+
+def entry_script():
+    """The command name a generated header tells the reader to run."""
+    return _ENTRY_POINT["script"]
 
 
 def project_default_domain(root):
@@ -727,6 +738,142 @@ def build_manifest(root):
     return "\n".join(lines).rstrip() + "\n"
 
 
+# ------------------------------------------------- workstream registry (F-028)
+# audit/handoff.md is GENERATED from one source file per open workstream, so two
+# writers working two workstreams touch two different files. Row-per-workstream
+# alone was not enough -- F-019 had that and the file still conflicted twice,
+# because a file-global `Date:` header defeats row-level ownership. The header is
+# now DERIVED, so no writer touches it.
+
+REGISTRY_COLUMNS = ("Workstream", "Level", "Branch", "Status", "Since",
+                    "Next step", "Details")
+REGISTRY_KEYS = ("workstream", "level", "branch", "status", "since", "next")
+REGISTRY_CAP = 20               # a signal, never a truncation (see cmd_index)
+PROJECT_NOTES = "project_notes.md"   # NOT handoff_notes.md: the HANDOFF_*.md
+# glob is case-insensitive on Windows, and that name would be collected as a
+# source. The trap is real; the name is the fix.
+
+
+def registry_header():
+    return (f"<!-- GENERATED by {entry_script()} index - do not edit by hand. "
+            f"Source of truth: the HANDOFF_*.md files in {docs_dir()}/audit/. -->")
+
+
+def list_workstreams(root):
+    """[(path, meta)] for audit/HANDOFF_*.md carrying registry frontmatter.
+
+    Opt-in by the presence of `workstream:` -- a project whose handoff is still
+    hand-written has no sources, so nothing generates and nothing errors (the
+    F-019 migration lesson). Sorted by workstream id: the alignment check is a
+    byte comparison, and glob order differs across filesystems."""
+    aud = ai_path(root, "audit")
+    out = []
+    if not aud.is_dir():
+        return out
+    for p in sorted(aud.glob("HANDOFF_*.md")):
+        meta = load_frontmatter(read_text(p).splitlines())
+        if str(meta.get("workstream") or "").strip():
+            out.append((p, meta))
+    out.sort(key=lambda pm: (str(pm[1].get("workstream")).strip().lower(), pm[0].name))
+    return out
+
+
+def _registry_cell(value):
+    text = str(value if value is not None else "").strip()
+    return text.replace("|", "\\|") or "-"
+
+
+def build_registry(root):
+    """The generated registry, or "" when there is no source to build it from.
+
+    Deterministic by construction: sorted rows, and a `Date:` taken from the
+    newest `updated:` VALUE written inside the sources -- never a filesystem
+    timestamp. Git does not preserve mtimes, so an mtime-derived header would
+    regenerate differently in every fresh clone and the alignment check would
+    fire on a tree nobody touched."""
+    rows = list_workstreams(root)
+    if not rows:
+        return ""
+    stamp = max(str(m.get("updated") or m.get("since") or "").strip() or "0000-00-00"
+                for _p, m in rows)
+    lines = ["# Handoff — workstream registry",
+             f"Date: {stamp} (UTC)",
+             "",
+             registry_header(),
+             "",
+             "| " + " | ".join(REGISTRY_COLUMNS) + " |",
+             "|" + "---|" * len(REGISTRY_COLUMNS)]
+    for p, meta in rows:
+        extra = str(meta.get("details") or "").strip()
+        details = f"{p.name} · {extra}" if extra else p.name
+        cells = [_registry_cell(meta.get(k)) for k in REGISTRY_KEYS]
+        lines.append("| " + " | ".join(cells) + f" | {_registry_cell(details)} |")
+    notes = ai_path(root, "audit", PROJECT_NOTES)
+    if notes.is_file():
+        body = read_text(notes).strip()
+        if body:
+            lines += ["", "## Project-wide notes", "", body]
+    return "\n".join(lines) + "\n"
+
+
+def parse_registry_rows(text):
+    """Workstream ids in a registry table, hand-written or generated."""
+    ids = []
+    for line in text.splitlines():
+        s = line.strip()
+        if not s.startswith("|") or set(s) <= {"|", "-", " ", ":"}:
+            continue
+        first = s.strip("|").split("|")[0].strip()
+        if first and first.lower() != "workstream":
+            ids.append(first)
+    return ids
+
+
+def registry_conversion_blockers(root):
+    """What stops `index` from writing over a hand-written handoff.md.
+
+    The mixed state is the trap this exists for: converting one row at a time
+    leaves a project at one source file and five hand-written rows, and
+    regenerating from the one source DELETES the other five -- silently, in the
+    file whose whole purpose is not losing them. So conversion is per project.
+    Empty list = writing is safe."""
+    hand = ai_path(root, "audit", "handoff.md")
+    if not hand.is_file():
+        return []
+    text = read_text(hand)
+    if "GENERATED by sdlc_check.py index" in text:
+        return []                                   # already ours
+    blockers = []
+    known = {str(m.get("workstream")).strip() for _p, m in list_workstreams(root)}
+    orphans = [r for r in parse_registry_rows(text) if r not in known]
+    if orphans:
+        blockers.append("rows no HANDOFF_*.md accounts for: " + ", ".join(orphans))
+    # Everything else in the file must have a home too, or it is lost on write:
+    # a pre-1.17 narrative handoff carries no table at all, so orphan rows alone
+    # would not notice it.
+    notes_ok = ai_path(root, "audit", PROJECT_NOTES).is_file()
+    leftovers, in_notes = [], False
+    for line in text.splitlines():
+        s = line.strip()
+        if not s or s.startswith("|") or s.startswith("<!--"):
+            continue
+        if s.startswith("# ") or re.match(r"^(?:Date|Data):", s):
+            continue
+        if re.match(r"^##\s+Project-wide notes\s*$", s):
+            in_notes = True
+            continue
+        if s.startswith("## "):
+            in_notes = False
+        if in_notes and notes_ok:
+            continue
+        leftovers.append(s)
+    if leftovers:
+        blockers.append("content outside the table with nowhere to go (%d line(s), first: %r) "
+                        "-- project-wide notes belong in audit/%s"
+                        % (len(leftovers), leftovers[0][:60], PROJECT_NOTES))
+    return blockers
+
+
 def list_guides(root):
     """[(rel_to_ai_docs, path, meta, text)] for ai_docs/reference/GUIDE_*.md."""
     ref = ai_path(root, "reference")
@@ -821,6 +968,30 @@ def cmd_index(root):
                         "a comprehension map (`source_kind: code`) -- see `guides.md`.\n",
                         encoding="utf-8")
         print(f"[ok] guide router regenerated (empty stub): {gidx}")
+    return max(rc_registry(root), 0)
+
+
+def rc_registry(root):
+    """Write the generated workstream registry, or refuse and say why (F-028)."""
+    ws = list_workstreams(root)
+    if not ws:
+        return 0                # no sources: a hand-written handoff is untouched
+    blockers = registry_conversion_blockers(root)
+    hand = ai_path(root, "audit", "handoff.md")
+    if blockers:
+        print(f"[ERROR] {docs_dir()}/audit/handoff.md NOT regenerated -- it still holds "
+              "state no source accounts for:")
+        for b in blockers:
+            print(f"          - {b}")
+        print("          Convert the whole registry at once (templates.md): converting "
+              "one row at a time is the state that loses the others.")
+        return 1
+    hand.parent.mkdir(parents=True, exist_ok=True)
+    hand.write_text(build_registry(root), encoding="utf-8")
+    print(f"[ok] workstream registry regenerated: {hand}")
+    if len(ws) > REGISTRY_CAP:
+        print(f"[warn] {len(ws)} open workstreams: the registry is meant to stay under "
+              f"{REGISTRY_CAP}. Nothing was truncated -- closing one is the fix.")
     return 0
 
 
@@ -1257,8 +1428,33 @@ def cmd_validate(root, strict=False, hybrid=False):
         elif norm_text(read_text(gidx)) != norm_text(build_guide_index(root)):
             errors.append(f"{docs_dir()}/reference/INDEX.md not aligned with the guides: run 'sdlc_check.py index'")
 
-    # Handoff: header and freshness
+    # Handoff: alignment with its sources (F-028), then header and freshness
     hand = ai / "audit" / "handoff.md"
+    workstreams = list_workstreams(root)
+    if workstreams:
+        if not hand.is_file():
+            errors.append(f"{docs_dir()}/audit/handoff.md missing while HANDOFF_*.md sources "
+                          "exist: the registry is the only place a cold agent sees the open "
+                          "workstreams -- run 'sdlc_check.py index'")
+        elif norm_text(read_text(hand)) != norm_text(build_registry(root)):
+            errors.append(f"{docs_dir()}/audit/handoff.md not aligned with its HANDOFF_*.md "
+                          "sources: run 'sdlc_check.py index'. A merge resolved by hand is "
+                          "exactly what this catches")
+        if len(workstreams) > REGISTRY_CAP:
+            warnings.append(f"{len(workstreams)} open workstreams: the registry is meant to "
+                            f"stay under {REGISTRY_CAP}")
+        # Two files claiming one workstream is the collision this design does NOT
+        # fix (two people opening the same work under different file names). It
+        # would otherwise show up as two identical-looking rows and nothing else.
+        seen = {}
+        for p, meta in workstreams:
+            wid = str(meta.get("workstream")).strip()
+            if wid in seen:
+                warnings.append(f"{docs_dir()}/audit/{p.name} and {seen[wid]} both claim "
+                                f"workstream '{wid}': the registry shows two rows for one "
+                                "workstream — decide which file owns it")
+            else:
+                seen[wid] = p.name
     if hand.is_file():
         m = re.search(r"(?:Date|Data):\s*(\d{4}-\d{2}-\d{2})", read_text(hand))
         if not m:

package/skills/agentic-sdlc-skill/templates.md

@@ -86,7 +86,7 @@ Must-reads for this project, in order. The full manifest of canonical docs is
 1. `reference/INDEX.md` — the guide router: which guide already governs the work you are about to do (generated).
 2. `vision/project_vision.md` — why the project exists (check its Status first).
 3. `strategic/architecture.md` — how it is built.
-4. `audit/handoff.md` — where work stopped last session (if present).
+4. `audit/handoff.md` — where work stopped last session (generated from the `HANDOFF_*.md` beside it; never edited by hand).
 
 Directory purposes: `vision/` (project direction), `strategic/` (architecture and
 feature catalog), `reference/` (operative guides), `solutions/` (per-feature
@@ -367,36 +367,50 @@ States: PENDING (to analyze) | ANALYZED (analyzed, with reference) | SKIPPED (wi
 | vendor/ | SKIPPED | - | vendored code |
 ```
 
-## ai_docs/audit/handoff.md — the workstream registry
-
-One row per OPEN workstream, ≤ 20 lines. **Parallel-safe by construction**: closing
-one milestone removes one row and never touches another's resume point — the defect
-this replaces was a single narrative slot where the last session to close overwrote
-everyone else's handoff. It is an **inventory for lookup** (like the generated
-manifest), not a work board: no assignment, no due dates, no execution ordering.
-
-Updated at every L3 closure (row removed) AND at session end with work still
-IN_PROGRESS (row refreshed) — see Write Triggers.
-
-**Coming from a pre-1.17 project** (narrative handoff with `## Active features` /
-`## Next step` / `## Session notes`): nothing is broken and nothing is urgent — the
-validator only checks the `Date:` header and its age, and the orientation hook reads
-the file verbatim. Read it as a one-row registry, and convert it the next time the
-write trigger fires: each `## Active features` bullet becomes a row, `## Next step`
-becomes that row's next step, `## Session notes` becomes `## Project-wide notes`.
-Migrating a repository that is not being worked on buys nothing.
+## ai_docs/audit/handoff.md — the workstream registry (GENERATED)
+
+One row per OPEN workstream. **Never written by hand**: `sdlc_check.py index` builds
+it from the `HANDOFF_[feature].md` files, and `validate` errors when the two disagree.
+It is an **inventory for lookup** (like the generated manifest), not a work board: no
+assignment, no due dates, no execution ordering, no holder.
+
+**Why generated, and not just one row per workstream.** Row-per-workstream alone was
+tried and was not enough: two workstreams opened from one base still conflicted twice
+in this file, because a file-global `Date:` header defeats row-level ownership no
+matter how few rows each writer touches. So the truth moved into the per-workstream
+file, and the header is derived (the newest `updated:` in the sources — a value, never
+a filesystem timestamp, which git does not preserve). Two writers on two workstreams
+now touch two different files. The generated view can still conflict at merge; that
+conflict is resolved **mechanically** by re-running `index`, never by hand, and
+`validate` refuses CLEAN until the file matches its sources.
+
+Project-wide notes have their own source, `ai_docs/audit/project_notes.md`, appended
+verbatim under `## Project-wide notes`. (Not `handoff_notes.md`: the `HANDOFF_*.md`
+glob is case-insensitive on Windows and would collect it as a workstream.)
+
+**Converting an existing project** — lazily, at the first write, and **all at once**.
+Converting one row at a time is the state that loses the others: the next `index`
+would regenerate from the one source and drop the rest. `index` refuses to write while
+anything in the file is unaccounted for, and names it. A pre-1.17 narrative handoff
+(`## Active features` / `## Next step` / `## Session notes`) is the same conversion:
+each bullet becomes a `HANDOFF_[feature].md`, `## Session notes` becomes
+`project_notes.md`. A project with no sources yet is not touched and reports nothing —
+migrating a repository nobody is working on buys nothing.
 
 ```markdown
 # Handoff — workstream registry
 Date: 2026-06-11 (UTC)
 
+<!-- GENERATED by sdlc_check.py index - do not edit by hand. Source of truth: the HANDOFF_*.md files in ai_docs/audit/. -->
+
 | Workstream | Level | Branch | Status | Since | Next step | Details |
 |---|---|---|---|---|---|---|
 | F-001 SSO login | L3 | feature/sso-login | PROGRESS | 2026-06-10 | wire callback tests | HANDOFF_login_sso.md · ANALYSIS_login_sso.md |
-| F-002 Audit refresh | L3 | feature/audit | PAUSED | 2026-06-02 | resume at Phase 4 | ANALYSIS_audit_refresh.md (no volatile state) |
+| F-002 Audit refresh | L3 | feature/audit | PAUSED | 2026-06-02 | resume at Phase 4 | HANDOFF_audit_refresh.md · ANALYSIS_audit_refresh.md |
 
 ## Project-wide notes
-<!-- one or two lines: release pending, environment quirks that affect everyone -->
+
+<!-- from audit/project_notes.md: release pending, environment quirks that affect everyone -->
 ```
 
 ## ai_docs/audit/reviews/REVIEW_LOG.md
@@ -431,21 +445,47 @@ records the realization actually used — fresh subagent, one-shot client run, o
 honest; writing nothing, or implying independence you did not have, is the failure
 this column exists to prevent. `findings_real` is how many raised findings survived
 triage: over time it is the only evidence of whether the gate earns its cost.
-
-## ai_docs/audit/HANDOFF_[feature].md — volatile resume logistics (ephemeral)
-
-**Resume logistics ONLY; the ANALYSIS Diary keeps the durable narrative (DRY).**
-The boundary: Diary = what happened and why (decisions, state of the work — survives
-forever); this file = how to pick the work back up (branch/worktree, uncommitted
-state, environment notes, the next concrete command — worthless once resumed).
-Created only when a session pauses the feature WITH volatile state to record;
-**DELETED at the feature's closure**, in the same step that flips the ANALYSIS to
-COMPLETED — anything in it worth keeping was in the wrong file.
+Concurrent reviews: `init` writes a `.gitattributes` stanza giving this file
+`merge=union` — a **built-in** driver (no per-clone `git config`, unlike
+`merge=ours`, which silently does nothing until every clone configures it).
+Rows are date-stamped and their order carries no meaning, so a union merge keeps
+both sides instead of asking a human to choose. It is defence in depth: without
+git, or without the stanza, the outcome is today's — one conflict you resolve by
+hand, never a lost row.
+
+
+## ai_docs/audit/HANDOFF_[feature].md — one open workstream, its own file
+
+**The authored home of that workstream's registry row**, and the only one: the
+registry is generated from these files. **One exists for every OPEN workstream**, with
+or without volatile state — a workstream whose file is missing has no row, and a
+workstream with no row is invisible to the next cold agent. **DELETED at the feature's
+closure**, in the same step that flips the ANALYSIS to COMPLETED: deleting it *is*
+removing the row.
+
+**The DRY boundary, restated because the file is no longer rare.** What used to keep
+narrative out of it was that it barely existed; now it always does. So: the ANALYSIS
+Diary keeps **what happened and why** (decisions, state of the work — survives
+forever), and this file keeps **the row plus the resume logistics** — how to pick the work back up (branch,
+worktree, uncommitted state, the next concrete command — worthless once resumed).
+Prose that would still be worth reading after closure is in the wrong file, because
+this one is deleted.
+
+The frontmatter IS the row. `workstream:` is what marks the file as a source: without
+it the file is still a perfectly good volatile note, and nothing generates.
 
 ```markdown
+---
+workstream: F-001 SSO login
+level: L3
+branch: feature/sso-login (worktree ../wt-sso)
+status: PROGRESS
+since: 2026-06-10
+next: wire the callback tests
+details: ANALYSIS_login_sso.md
+updated: 2026-06-11
+---
 # HANDOFF: [feature] (ephemeral — deleted at closure)
-Updated: 2026-06-11 (UTC)
-Branch: feature/sso-login (worktree ../wt-sso)
 
 ## Resume state
 <!-- uncommitted files, half-run migrations, env vars, running services -->
@@ -457,6 +497,19 @@ Branch: feature/sso-login (worktree ../wt-sso)
 <!-- traps discovered this session that bite on resume (locks, CRLF, flaky test) -->
 ```
 
+`updated:` is the date this file last changed, and the newest one across all sources
+becomes the registry's `Date:` header — which is why no writer ever edits that header
+and why two concurrent writers no longer collide on it. `details:` holds the *other*
+pointers (the ANALYSIS, a review log entry); the generator prepends this file's own
+name, so nothing points at itself by hand.
+
+## ai_docs/audit/project_notes.md — the registry's project-wide notes (source)
+
+Plain lines, no frontmatter, appended verbatim to the generated registry under
+`## Project-wide notes`. Release pending, environment quirks, anything true for
+everyone rather than for one workstream. It exists so that generating the registry
+cannot destroy notes that belong to no workstream.
+
 ## ai_docs/strategic/architecture.md and existing_features.md
 
 Canonical docs: they open with the header (`description:`/`status:`) so they enter the `INDEX.md` manifest cleanly.