@antoneeo/agentic-sdlc-skill 1.20.2 → 1.21.0

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.