@antoneeo/mkt-agentic-sdlc-skill 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## [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.
+
+## 0.3.1 — 2026-08-02
+
+### Fixed
+- **The multi-lens routing note announced this skill as the code lens.** `init.js` wrote
+  the row for the CURRENT lens as a hardcoded literal copied from the code distribution,
+  so a project initialised with `mkt-sdlc-init` listed `agentic-sdlc` twice and never
+  named `mkt-agentic-sdlc`. Both the self row and the sibling table are now derived from
+  the shared `routing.md` lens table. Found by a cold-agent field test.
+- **`FACT` was the way past the evidence rule.** `BENCHMARK` owes a source URL and
+  `ASSUMPTION` a range; `FACT` owed nothing, so a researched observation classed FACT
+  with source "see research/VOC.md" entered the ledger unsourced. `mkt_check.py` now
+  errors on a FACT with no source, or one pointing at a document of the engagement,
+  while exempting a cell that names the client as origin. `research.md` states the two
+  legal origins.
+- `review.md` (shared spine): a review verdict travels as the reviewer's final output.
+
+## 0.3.0 — 2026-08-01
+
+- **One shared core, three lenses.** This skill is now built from the family's spine
+  instead of a copy of it: triage, the Vision gate, the review gates, the guide router,
+  question discipline and the validator core are byte-identical with
+  `@antoneeo/agentic-sdlc-skill` and `@antoneeo/kb-agentic-skill`, and a drift guard
+  verifies it on every build. `routing.md` decides which lens owns a unit of work when
+  more than one is installed.
+- `mkt_check.py` forwards every spine subcommand it does not intercept by iterating the
+  spine's parser — the hand-copied command tuple used to drop `migrate` while `SKILL.md`
+  documented it.
+
 ## 0.2.1 — 2026-07-09
 
 - **Install DX fix**: README + the generated project protocol pointer no longer present `mkt-sdlc-install-skill` as a required second step. `npm i -g` alone installs the skill (the `postinstall` runs the installer); the manual command is documented as a fallback via `npx mkt-sdlc-install-skill` for setups that block install scripts, with an explicit note that the bare command is only on PATH after a global install. Prevents the "command not recognized" error after a local `npm i`.

package/README.md

@@ -47,6 +47,10 @@ npx mkt-sdlc-init        # creates mkt_docs/ + protocol pointers
 | E3 Full Plan | complete marketing plan | full SOSTAC workflow, 9 phases, all gates |
 | Research Spike | time-boxed market question | `mkt_docs/spikes/RESEARCH_[topic].md` |
 
+## 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.
+
 ## Modes
 
 - **Standalone** — everything on the filesystem under `mkt_docs/`.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "mkt-agentic-sdlc",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Evidence-First marketing planning protocol with engagement triage, SOSTAC workflow, evidence ledger and optional devPNT integration.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/mkt-agentic-sdlc-skill",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Evidence-First marketing planning protocol for Claude Code, Gemini CLI, Google Antigravity and Codex: engagement triage, SOSTAC workflow, evidence ledger, mechanical validator and optional devPNT integration.",
   "keywords": [
     "claude-code",

package/scripts/init.js

@@ -3,14 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { SKILL_SOURCE, CLIENTS, clientDetected, skillTarget, loadTemplates, templateFor } = require('./lib');
-
-// Sibling lenses of the same family: one shared core, one `ai_docs/` tree, a different
-// fidelity discipline each. Keyed by the installed skill directory name.
-const SIBLING_LENSES = {
-  'kb-agentic': 'knowledge',
-  'agentic-sdlc': 'code',
-};
+const { SKILL_SOURCE, INSTALLED_SKILL_NAME, SELF_LENS, SIBLING_LENSES, CLIENTS, clientDetected, skillTarget, loadTemplates, templateFor } = require('./lib');
 
 const cwd = process.cwd();
 
@@ -110,6 +103,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 = 'mkt_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 ---');
 
@@ -159,7 +180,7 @@ if (siblings.size > 0) {
 This project has more than one lens of the Agentic SDLC family installed:
 
 ${list}
-- \`agentic-sdlc\` — the **code** lens
+- \`${INSTALLED_SKILL_NAME}\` — the **${SELF_LENS}** lens
 
 One \`ai_docs/\` tree, one project default (\`default_domain:\` in \`ai_docs/README.md\`),
 one lens per unit of work. Before acting on any L2, L3 or Spike, run the domain router
@@ -186,7 +207,7 @@ Delete it once the merge is done.
 `, 'multi-lens routing note');
   if (wrote && protocolPreexisting) {
     console.log('   ⚠️  A protocol pointer already existed and was NOT overwritten.');
-    console.log('       Merge the code-lens ladder from AGENTIC_MULTI_LENS.md into it by hand.');
+    console.log(`       Merge the ${SELF_LENS}-lens ladder from AGENTIC_MULTI_LENS.md into it by hand.`);
   }
 }
 

package/scripts/lib.js

@@ -1,183 +1,233 @@
-// Shared helpers for the Marketing Agentic SDLC npm scripts (init / postinstall / preuninstall).
-// Single source for client detection and skill-target paths: init and postinstall
-// must never disagree on what "Claude Code is installed" means.
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const { execSync } = require('child_process');
-
-const PACKAGE_ROOT = path.resolve(__dirname, '..');
-const SKILL_SOURCE = path.join(PACKAGE_ROOT, 'skills', 'mkt-agentic-sdlc');
-const TEMPLATES_PATH = path.join(SKILL_SOURCE, 'templates.md');
-// Kept for backward compatibility with this package's own scripts; the
-// authoritative value is INSTALLED_SKILL_NAME, derived from SKILL.md below.
-// The directory name each client loads the skill from. Derived from the manifest,
-// never hard-coded by a consumer: three distributions share these scripts, and a
-// literal here is how a copy-fork starts installing under its sibling's name.
-const INSTALLED_SKILL_NAME = (() => {
-  const m = fs.readFileSync(path.join(SKILL_SOURCE, 'SKILL.md'), 'utf8').match(/^name:\s*(\S+)/m);
-  if (!m) throw new Error(`SKILL.md carries no 'name:' field: ${SKILL_SOURCE}`);
-  return m[1];
-})();
-
-// One entry per supported AI client. `home` may be overridden by an env var
-// (Claude Desktop / portable installs); presence of the home dir counts as
-// detection even when the CLI is not on PATH.
-
-// One entry per supported AI client. `home` may be overridden by an env var
-// (Claude Desktop / portable installs); presence of the home dir counts as
-// detection even when the CLI is not on PATH.
-const CLIENTS = [
-  {
-    key: 'claude',
-    label: 'Claude Code',
-    cmd: 'claude',
-    home: process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'),
-    envVar: 'CLAUDE_CONFIG_DIR',
-    reload: 'Restart Claude Code to load it. Invoke via Skill tool as "mkt-agentic-sdlc".',
-  },
-  {
-    key: 'gemini',
-    label: 'Gemini CLI',
-    cmd: 'gemini',
-    home: process.env.GEMINI_HOME || path.join(os.homedir(), '.gemini'),
-    envVar: 'GEMINI_HOME',
-    reload: 'Run "gemini skills reload" or restart Gemini CLI to load it.',
-  },
-  {
-    key: 'codex',
-    label: 'Codex AI',
-    cmd: 'codex',
-    home: process.env.CODEX_HOME || path.join(os.homedir(), '.codex'),
-    envVar: 'CODEX_HOME',
-    reload: 'Restart Codex to load it. Invoke it as "$mkt-agentic-sdlc" or by asking for the Marketing SDLC skill.',
-  },
-  {
-    // Google Antigravity 2.0 discovers global agent skills under
-    // ~/.gemini/config/skills/ -- the SAME home the legacy Gemini CLI claims.
-    // To avoid a shared-home double-install, this entry sets:
-    //  - skillsSubdir 'config/skills': distinct target from gemini's ~/.gemini/skills
-    //  - homeMarker on ~/.gemini/config/skills: detection never fires on bare
-    //    ~/.gemini (which every Antigravity user has); only the Antigravity skills
-    //    dir, the `agy` CLI, or ANTIGRAVITY_HOME count as "Antigravity installed".
-    key: 'antigravity',
-    label: 'Google Antigravity',
-    cmd: 'agy',
-    home: process.env.ANTIGRAVITY_HOME || path.join(os.homedir(), '.gemini'),
-    envVar: 'ANTIGRAVITY_HOME',
-    skillsSubdir: 'config/skills',
-    homeMarker: path.join(
-      process.env.ANTIGRAVITY_HOME || path.join(os.homedir(), '.gemini'),
-      'config',
-      'skills',
-    ),
-    reload: 'Restart Antigravity, or run "agy skills reload", to load it. Invoke by asking for the Marketing SDLC skill.',
-  },
-];
-
-function commandExists(cmd) {
-  try {
-    execSync(`${cmd} --version`, { stdio: 'ignore' });
-    return true;
-  } catch (e) {
-    return false;
-  }
-}
-
-function clientDetected(client) {
-  // An entry may override the fs-existence probe with a `homeMarker` (a more
-  // specific path than the bare home) so two clients sharing a home dir do not
-  // both fire on its mere existence. Entries without a marker check `home`
-  // exactly as before (backward-compatible).
-  const homePathToCheck = client.homeMarker || client.home;
-  return commandExists(client.cmd)
-    || Boolean(process.env[client.envVar])
-    || fs.existsSync(homePathToCheck);
-}
-
-function skillTarget(client) {
-  // An entry may override the default `skills` sub-path with `skillsSubdir`
-  // (split on '/' to keep cross-platform path.join correctness). Entries
-  // without it resolve to <home>/skills/mkt-agentic-sdlc exactly as before.
-  const subdir = client.skillsSubdir ? client.skillsSubdir.split('/') : ['skills'];
-  return path.join(client.home, ...subdir, INSTALLED_SKILL_NAME);
-}
-
-function copyRecursive(src, dest) {
-  if (typeof fs.cpSync === 'function') {
-    fs.cpSync(src, dest, { recursive: true, force: true });
-    return;
-  }
-  // Fallback for Node < 16.7
-  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    const s = path.join(src, entry.name);
-    const d = path.join(dest, entry.name);
-    if (entry.isDirectory()) copyRecursive(s, d);
-    else fs.copyFileSync(s, d);
-  }
-}
-
-/**
- * Parse templates.md into { headingText: [fencedBlock, ...] }.
- * Templates are single-sourced there: the init script must extract them
- * instead of carrying its own inline copies (which historically drifted).
- */
-function loadTemplates() {
-  const text = fs.readFileSync(TEMPLATES_PATH, 'utf8');
-  const lines = text.split(/\r?\n/);
-  const sections = {};
-  let heading = null;
-  let block = null;
-  for (const line of lines) {
-    const h = line.match(/^##\s+(.*)$/);
-    if (h && block === null) {
-      heading = h[1].trim();
-      sections[heading] = sections[heading] || [];
-      continue;
-    }
-    if (/^```/.test(line)) {
-      if (block === null) {
-        block = [];
-      } else {
-        if (heading) sections[heading].push(block.join('\n') + '\n');
-        block = null;
-      }
-      continue;
-    }
-    if (block !== null) block.push(line);
-  }
-  return sections;
-}
-
-/**
- * Return the Nth fenced block of the section whose heading contains `needle`.
- * Throws with a clear message when missing: writing a wrong or empty
- * boilerplate silently would be worse than failing the init.
- */
-function templateFor(sections, needle, index = 0) {
-  const heading = Object.keys(sections).find((h) => h.includes(needle));
-  const blocks = heading ? sections[heading] : undefined;
-  if (!blocks || !blocks[index]) {
-    throw new Error(
-      `Template section containing "${needle}" (block ${index}) not found in ${TEMPLATES_PATH}. ` +
-      'The package is corrupted or templates.md was restructured: fix templates.md, do not improvise content.'
-    );
-  }
-  return blocks[index];
-}
-
-module.exports = {
-  INSTALLED_SKILL_NAME,
-  PACKAGE_ROOT,
-  SKILL_SOURCE,
-  TEMPLATES_PATH,
-  CLIENTS,
-  commandExists,
-  clientDetected,
-  skillTarget,
-  copyRecursive,
-  loadTemplates,
-  templateFor,
-};
+// Shared helpers for the Marketing Agentic SDLC npm scripts (init / postinstall / preuninstall).
+// Single source for client detection and skill-target paths: init and postinstall
+// must never disagree on what "Claude Code is installed" means.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const SKILL_SOURCE = path.join(PACKAGE_ROOT, 'skills', 'mkt-agentic-sdlc');
+const TEMPLATES_PATH = path.join(SKILL_SOURCE, 'templates.md');
+// Kept for backward compatibility with this package's own scripts; the
+// authoritative value is INSTALLED_SKILL_NAME, derived from SKILL.md below.
+// The directory name each client loads the skill from. Derived from the manifest,
+// never hard-coded by a consumer: three distributions share these scripts, and a
+// literal here is how a copy-fork starts installing under its sibling's name.
+const INSTALLED_SKILL_NAME = (() => {
+  const m = fs.readFileSync(path.join(SKILL_SOURCE, 'SKILL.md'), 'utf8').match(/^name:\s*(\S+)/m);
+  if (!m) throw new Error(`SKILL.md carries no 'name:' field: ${SKILL_SOURCE}`);
+  return m[1];
+})();
+
+// The family's lens table, read from the shared `routing.md` rather than restated
+// here. Same reason as INSTALLED_SKILL_NAME above, and the same failure it prevents:
+// BOTH the row for this lens and the rows for its siblings used to be literals copied
+// between distributions, so kb and mkt wrote a multi-lens note announcing themselves
+// as the code lens. routing.md is one of the byte-identical shared files, so this
+// lookup cannot drift between distributions.
+// Lazy on purpose: preuninstall.js needs INSTALLED_SKILL_NAME and nothing else, and
+// must keep working on an installation damaged badly enough to have lost routing.md.
+function lensTable() {
+  const routing = path.join(SKILL_SOURCE, 'routing.md');
+  if (!fs.existsSync(routing)) throw new Error(`routing.md missing from the skill: ${SKILL_SOURCE}`);
+  // Parsed as a table, not matched with a regex: a mis-escaped pattern matches the
+  // empty string and yields undefined instead of throwing, which is how this lookup
+  // failed the first time it was written.
+  const table = new Map();
+  for (const line of fs.readFileSync(routing, 'utf8').split(/\r?\n/)) {
+    const cells = line.split('|').map((cell) => cell.trim());
+    if (cells.length < 4) continue;
+    const [, lens, skill] = cells;
+    if (!/^[a-z]+$/.test(lens) || !/^`[a-z0-9-]+`$/.test(skill)) continue;
+    const name = skill.slice(1, -1);
+    // A duplicate row would otherwise be won silently by whichever came first, and a
+    // wrong routing.md propagates byte-identically to every distribution.
+    if (table.has(name)) throw new Error(`routing.md lists '${name}' more than once`);
+    table.set(name, lens);
+  }
+  if (!table.size) throw new Error(`routing.md carries no lens table: ${routing}`);
+  return table;
+}
+
+function selfLens() {
+  const lens = lensTable().get(INSTALLED_SKILL_NAME);
+  if (!lens) throw new Error(`routing.md has no lens row for '${INSTALLED_SKILL_NAME}'`);
+  return lens;
+}
+
+// Sibling lenses of the same family: one shared core, one docs tree, a different
+// fidelity discipline each. Keyed by the installed skill directory name.
+function siblingLenses() {
+  const table = lensTable();
+  selfLens();                       // this lens must be in the table too
+  table.delete(INSTALLED_SKILL_NAME);
+  return Object.fromEntries(table);
+}
+
+// One entry per supported AI client. `home` may be overridden by an env var
+// (Claude Desktop / portable installs); presence of the home dir counts as
+// detection even when the CLI is not on PATH.
+
+// One entry per supported AI client. `home` may be overridden by an env var
+// (Claude Desktop / portable installs); presence of the home dir counts as
+// detection even when the CLI is not on PATH.
+const CLIENTS = [
+  {
+    key: 'claude',
+    label: 'Claude Code',
+    cmd: 'claude',
+    home: process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'),
+    envVar: 'CLAUDE_CONFIG_DIR',
+    reload: 'Restart Claude Code to load it. Invoke via Skill tool as "mkt-agentic-sdlc".',
+  },
+  {
+    key: 'gemini',
+    label: 'Gemini CLI',
+    cmd: 'gemini',
+    home: process.env.GEMINI_HOME || path.join(os.homedir(), '.gemini'),
+    envVar: 'GEMINI_HOME',
+    reload: 'Run "gemini skills reload" or restart Gemini CLI to load it.',
+  },
+  {
+    key: 'codex',
+    label: 'Codex AI',
+    cmd: 'codex',
+    home: process.env.CODEX_HOME || path.join(os.homedir(), '.codex'),
+    envVar: 'CODEX_HOME',
+    reload: 'Restart Codex to load it. Invoke it as "$mkt-agentic-sdlc" or by asking for the Marketing SDLC skill.',
+  },
+  {
+    // Google Antigravity 2.0 discovers global agent skills under
+    // ~/.gemini/config/skills/ -- the SAME home the legacy Gemini CLI claims.
+    // To avoid a shared-home double-install, this entry sets:
+    //  - skillsSubdir 'config/skills': distinct target from gemini's ~/.gemini/skills
+    //  - homeMarker on ~/.gemini/config/skills: detection never fires on bare
+    //    ~/.gemini (which every Antigravity user has); only the Antigravity skills
+    //    dir, the `agy` CLI, or ANTIGRAVITY_HOME count as "Antigravity installed".
+    key: 'antigravity',
+    label: 'Google Antigravity',
+    cmd: 'agy',
+    home: process.env.ANTIGRAVITY_HOME || path.join(os.homedir(), '.gemini'),
+    envVar: 'ANTIGRAVITY_HOME',
+    skillsSubdir: 'config/skills',
+    homeMarker: path.join(
+      process.env.ANTIGRAVITY_HOME || path.join(os.homedir(), '.gemini'),
+      'config',
+      'skills',
+    ),
+    reload: 'Restart Antigravity, or run "agy skills reload", to load it. Invoke by asking for the Marketing SDLC skill.',
+  },
+];
+
+function commandExists(cmd) {
+  try {
+    execSync(`${cmd} --version`, { stdio: 'ignore' });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function clientDetected(client) {
+  // An entry may override the fs-existence probe with a `homeMarker` (a more
+  // specific path than the bare home) so two clients sharing a home dir do not
+  // both fire on its mere existence. Entries without a marker check `home`
+  // exactly as before (backward-compatible).
+  const homePathToCheck = client.homeMarker || client.home;
+  return commandExists(client.cmd)
+    || Boolean(process.env[client.envVar])
+    || fs.existsSync(homePathToCheck);
+}
+
+function skillTarget(client) {
+  // An entry may override the default `skills` sub-path with `skillsSubdir`
+  // (split on '/' to keep cross-platform path.join correctness). Entries
+  // without it resolve to <home>/skills/mkt-agentic-sdlc exactly as before.
+  const subdir = client.skillsSubdir ? client.skillsSubdir.split('/') : ['skills'];
+  return path.join(client.home, ...subdir, INSTALLED_SKILL_NAME);
+}
+
+function copyRecursive(src, dest) {
+  if (typeof fs.cpSync === 'function') {
+    fs.cpSync(src, dest, { recursive: true, force: true });
+    return;
+  }
+  // Fallback for Node < 16.7
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyRecursive(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+/**
+ * Parse templates.md into { headingText: [fencedBlock, ...] }.
+ * Templates are single-sourced there: the init script must extract them
+ * instead of carrying its own inline copies (which historically drifted).
+ */
+function loadTemplates() {
+  const text = fs.readFileSync(TEMPLATES_PATH, 'utf8');
+  const lines = text.split(/\r?\n/);
+  const sections = {};
+  let heading = null;
+  let block = null;
+  for (const line of lines) {
+    const h = line.match(/^##\s+(.*)$/);
+    if (h && block === null) {
+      heading = h[1].trim();
+      sections[heading] = sections[heading] || [];
+      continue;
+    }
+    if (/^```/.test(line)) {
+      if (block === null) {
+        block = [];
+      } else {
+        if (heading) sections[heading].push(block.join('\n') + '\n');
+        block = null;
+      }
+      continue;
+    }
+    if (block !== null) block.push(line);
+  }
+  return sections;
+}
+
+/**
+ * Return the Nth fenced block of the section whose heading contains `needle`.
+ * Throws with a clear message when missing: writing a wrong or empty
+ * boilerplate silently would be worse than failing the init.
+ */
+function templateFor(sections, needle, index = 0) {
+  const heading = Object.keys(sections).find((h) => h.includes(needle));
+  const blocks = heading ? sections[heading] : undefined;
+  if (!blocks || !blocks[index]) {
+    throw new Error(
+      `Template section containing "${needle}" (block ${index}) not found in ${TEMPLATES_PATH}. ` +
+      'The package is corrupted or templates.md was restructured: fix templates.md, do not improvise content.'
+    );
+  }
+  return blocks[index];
+}
+
+module.exports = {
+  INSTALLED_SKILL_NAME,
+  PACKAGE_ROOT,
+  SKILL_SOURCE,
+  TEMPLATES_PATH,
+  CLIENTS,
+  commandExists,
+  clientDetected,
+  skillTarget,
+  copyRecursive,
+  loadTemplates,
+  templateFor,
+};
+
+// Lazy: reading routing.md is deferred to the consumer that actually asks.
+Object.defineProperty(module.exports, 'SELF_LENS', { enumerable: true, get: selfLens });
+Object.defineProperty(module.exports, 'SIBLING_LENSES', { enumerable: true, get: siblingLenses });
+

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

@@ -66,7 +66,10 @@ One event, one destination: when the trigger fires and the document does not exi
 
 | Document | Write trigger | Phase |
 |---|---|---|
-| `audit/handoff.md` (workstream registry) | One row per OPEN engagement — refresh at every closure and at session end. ≤ 20 lines. | 9 / session end |
+| `audit/handoff.md` (workstream registry) | **Never by hand — generated by `mkt_check.py index` from the `HANDOFF_*.md` sources**, and `validate` errors when the two disagree. Regenerate at every closure and at session end; the `Date:` header is derived, so no writer touches it. Inventory for lookup, never a work board. | 9 / session end |
+| `audit/HANDOFF_[engagement].md` | **One per OPEN engagement, with or without volatile state** — it is the authored home of that engagement's registry row (frontmatter `workstream`/`level`/`branch`/`status`/`since`/`next`/`details`/`updated`), so no file means no row. DELETED at closure — deleting it *is* removing the row. | 9 / session end |
+| `audit/project_notes.md` | A note true for the whole engagement portfolio rather than one engagement. Appended verbatim to the generated registry, so regenerating cannot destroy it. | 9 / session end |
+| `audit/handoff.md` — converting an existing project | **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. | 9 / session end |
 | `audit/HANDOFF_[engagement].md` | Session ends with that engagement unfinished AND there is volatile resume state. Ephemeral, deleted at closure. | 8 / 9 / session end |
 | `audit/reviews/REVIEW_LOG.md` | Every completed review — when and what to write is `review.md`; schema is `templates.md`. | 6 / 9 |
 | `reference/GUIDE_[topic].md` | Origin+purpose test (`guides.md`), or a proactive proposal the user accepted. | 8 / 9 |

package/skills/mkt-agentic-sdlc/research.md

@@ -16,7 +16,13 @@ piece of evidence:
   numbers as `[EV-nn]`.
 - **Class** (exactly one):
   - `FACT` — user input or primary data (their analytics, their CRM export).
-    Source = "user, Wave 1" or the data file.
+    Source = "user, Wave 1" or the data file. **Only these two origins.** An
+    observation *you* gathered — a forum quote, a competitor's page, a review
+    site — is a `BENCHMARK` however solid it looks, and owes its URL. FACT is
+    the one class the URL rule cannot reach, so classing research as FACT is
+    the way an unsourced number gets in wearing the strongest label; the
+    validator now rejects a FACT whose Source names one of your own documents
+    or says "see X".
   - `BENCHMARK` — external number. Source URL **and** publication date
     mandatory. The Source cell must carry the actual external URL, NOT a
     pointer to one of your own research documents that aggregates it ("see

package/skills/mkt-agentic-sdlc/review.md

@@ -85,6 +85,14 @@ When you hand work to a reviewer (human or agent), give them:
   should have been. The design reviewer checks that every threat surface the change
   touches has a matching security requirement.
 
+**The verdict travels back as the reviewer's own final output** — the text it
+returns when it finishes, nothing else. A reviewer that tries to message the
+requester mid-run depends on a delivery channel it cannot verify (a subagent
+addressed by agent TYPE rather than by session gets no such channel, and the
+attempt fails silently); a requester that waits for such a message stalls
+holding a verdict that already exists. State the return form when you request
+the review, and read the verdict where it actually arrives.
+
 Never ask a reviewer to "review my session" or "review what I just did"
 without the artifacts above — that forces them to reconstruct scope from
 conversation instead of reviewing the change itself. Say which finding
@@ -109,6 +117,10 @@ When you are the reviewer:
 
 - Verify claims against the real source, not against the diff's own
   description of itself.
+- **Your verdict is your final output.** Deliver findings and verdict as the text
+  you return when you finish — never only through a message to the requester, a
+  channel you cannot verify and which fails silently when it is not there
+  (see `## Requesting`).
 - Cite evidence as `file:line` for every finding — a finding without a
   location is not actionable.
 - Keep severity honest: do not inflate a style preference to a blocker, and

package/skills/mkt-agentic-sdlc/scripts/mkt_check.py

@@ -53,7 +53,7 @@ except ImportError as exc:  # pragma: no cover - exercised by the copied-file te
 # has migrated to the family's single `ai_docs/` tree is reachable from here too.
 DOMAIN = "marketing"
 MKT_DOCS_DIR = "mkt_docs"
-sdlc_core.set_entry_point(DOMAIN, provides=("marketing",))
+sdlc_core.set_entry_point(DOMAIN, provides=("marketing",), script="mkt_check.py")
 sdlc_core.set_docs_dir(MKT_DOCS_DIR)
 
 sdlc_core.set_profile(
@@ -84,6 +84,18 @@ VALID_STATUS = ("CURRENT", "SUPERSEDED", "DRAFT", "DEPRECATED")
 LEDGER_CLASSES = ("FACT", "BENCHMARK", "ASSUMPTION")
 CONFIDENCE_VALUES = ("HIGH", "MED", "MEDIUM", "LOW")
 EV_REF = re.compile(r"\[(EV-\d+)\]")
+# A source that points INSIDE this engagement instead of at the world: a document of
+# OUR OWN under a canonical dir, or the "see X" form. Only FACT can carry it today,
+# because FACT is the one class the URL rule does not reach.
+INTERNAL_SOURCE_RE = re.compile(
+    r"(?:\b(?:mkt_docs|ai_docs|research|strategy|tactics|deliverables|vision)/\S*\.md\b"
+    r"|\b(?:see|vedi|cfr\.?)\s)", re.IGNORECASE)
+# The two origins research.md sanctions for a FACT. A cell that opens by naming the
+# client is exempt: their own primary data may well be a Markdown file they handed
+# over, and telling its author to "reclassify as BENCHMARK and add a URL" would be
+# advice to misclassify.
+CLIENT_ORIGIN_RE = re.compile(
+    r"^\s*(?:user|client|owner|utente|cliente|titolare|proprietario)\b", re.IGNORECASE)
 OBJECTIVE_HEADING = re.compile(r"^###\s+(O\d+)\b", re.MULTILINE)
 OBJECTIVE_TOKEN = re.compile(r"\bO\d+\b")
 EXAMPLE_MARKER = "(example)"
@@ -290,7 +302,10 @@ def cmd_index(root):
     out = sdlc_core.ai_path(root) / "INDEX.md"
     out.write_text(content, encoding="utf-8")
     print(f"[OK] wrote {out.relative_to(root).as_posix()}")
-    return 0
+    # F-028: the workstream registry is generated here too. This entry point does
+    # not reuse the spine's cmd_index, so wiring it explicitly is what keeps the
+    # doctrine ("generated by mkt_check.py index") from being false in this lens.
+    return sdlc_core.rc_registry(root)
 
 
 # ---------------------------------------------------------------- validate
@@ -298,6 +313,21 @@ def cmd_index(root):
 def run_validate(root):
     rep = Report()
     docs = sdlc_core.ai_path(root)
+    # F-028: the generated registry against its HANDOFF_*.md sources. Gated on
+    # source presence, so a project that has not converted sees nothing new.
+    workstreams = sdlc_core.list_workstreams(root)
+    if workstreams:
+        hand = docs / "audit" / "handoff.md"
+        if not hand.is_file():
+            rep.error("audit/handoff.md missing while HANDOFF_*.md sources exist: "
+                      "run 'mkt_check.py index'")
+        elif sdlc_core.norm_text(read_text(hand)) !=                 sdlc_core.norm_text(sdlc_core.build_registry(root)):
+            rep.error("audit/handoff.md not aligned with its HANDOFF_*.md sources: "
+                      "run 'mkt_check.py index'. A merge resolved by hand is exactly "
+                      "what this catches")
+        if len(workstreams) > sdlc_core.REGISTRY_CAP:
+            rep.warn(f"{len(workstreams)} open workstreams: the registry is meant to "
+                     f"stay under {sdlc_core.REGISTRY_CAP}")
     known = {p.name for p in docs.rglob("*.md")}
     for p in canonical_files(root):
         if p.name == "INDEX.md":
@@ -370,6 +400,20 @@ def run_ledger(root):
                 rep.error(f"ledger {rid}: BENCHMARK without a source URL")
             if not date:
                 rep.error(f"ledger {rid}: BENCHMARK without a date")
+        if cls == "FACT" and not source:
+            rep.error(f"ledger {rid}: FACT without a source -- name the origin "
+                      "('user, Wave 1' or the client's data file)")
+        if (cls == "FACT" and source and not CLIENT_ORIGIN_RE.match(source)
+                and INTERNAL_SOURCE_RE.search(source)):
+            # FACT means "the client told me" or "the client's own primary data" — the
+            # one class that legitimately has no URL. Pointing it at another document
+            # of this engagement is how a researched observation gets in without the
+            # URL its class would owe: the row cites a file that cites the source, the
+            # validator resolves nothing, and "see VOC.md" is exactly the form the
+            # BENCHMARK rule rejects. Observed in a cold-agent field test, 2026-08-02.
+            rep.error(f"ledger {rid}: FACT sourced to an internal document ('{source}') -- "
+                      "a FACT is what the client stated or their own primary data; an "
+                      "observation gathered by research is a BENCHMARK and owes its URL")
         if cls == "ASSUMPTION":
             if confidence not in CONFIDENCE_VALUES:
                 rep.error(f"ledger {rid}: ASSUMPTION without confidence (HIGH|MED|LOW)")

package/skills/mkt-agentic-sdlc/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/mkt-agentic-sdlc/templates.md

@@ -38,7 +38,7 @@ index`, never edit by hand).
 1. `vision/MKT_VISION.md` — why this plan exists (check its Status first).
 2. `research/evidence_ledger.md` — the single source for every number.
 3. `strategy/STRATEGY.md` — the approved strategy (if present).
-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/` (marketing vision and principles), `research/`
 (evidence ledger and research outputs, discovery-by-grep), `strategy/`
@@ -446,36 +446,50 @@ Agent: Claude
 <!-- gates passed? open review findings? ledger rows pending sources? -->
 ```
 
-## audit/handoff.md (under the docs root) — 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.
+## audit/handoff.md (under the docs root) — the workstream registry (GENERATED)
+
+One row per OPEN workstream. **Never written by hand**: `sdlc_check.py index` builds
+it from the `HANDOFF_[engagement].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, `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_[engagement].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 -->
 ```
 
 ## audit/reviews/REVIEW_LOG.md (under the docs root)
@@ -510,21 +524,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.
-
-## audit/HANDOFF_[engagement].md (under the docs root) — 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.
+
+
+## audit/HANDOFF_[engagement].md (under the docs root) — 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: [engagement] (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 -->
@@ -536,6 +576,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.
+
+## 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.
+
 ## strategic/architecture.md and existing_features.md (under the docs root)
 
 Canonical docs: they open with the header (`description:`/`status:`) so they enter the `INDEX.md` manifest cleanly.
@@ -605,7 +658,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