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

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # 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

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.1",
+  "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.1",
+  "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

@@ -103,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 ---');
 

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/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(
@@ -302,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
@@ -310,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":

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