@antoneeo/course-creator 0.1.0-beta.1

package/skills/course-creator/scripts/sdlc_core.py

@@ -0,0 +1,2707 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Mechanical validator for the Agentic SDLC family — the shared core.
+
+This module is the SPINE: it is authored once here and shipped verbatim in every
+distribution of the family (code, knowledge, marketing). It carries nothing that
+belongs to a single domain. Each distribution ships a thin entry point beside it —
+`sdlc_check.py` for code, `mkt_check.py` for marketing — which names the domain it
+implements and delegates everything else here. A drift guard fails CI when the
+copies diverge, so do not fork this file: fix it once and copy it.
+
+It is also runnable on its own (`python sdlc_core.py check`) for the same reason
+the entry points are thin: the behaviour is here, not in them.
+
+Commands:
+  check      single closure gate: validate + stale in one command (exit 1 if either fails)
+  validate   verify the structural coherence of the docs root (default ai_docs/; exit 1 on
+             errors; --strict also fails on warnings or on a missing docs root, for CI)
+  index      regenerate the generated indexes: strategic/features_history.md (from the
+             frontmatter of ANALYSIS_*.md files) and ai_docs/INDEX.md (manifest of canonical docs)
+  stale      list areas modified after the last analysis recorded in audit_plan.md (exit 1 if any)
+  mark       record paths as ANALYZED with the current reference (git hash, else UTC timestamp)
+  gate       PreToolUse hook: block writes on protected paths without an IN_PROGRESS ANALYSIS (exit 2)
+
+Hybrid/devPNT mode: pass --hybrid explicitly on check/stale (skips audit-plan
+staleness, delegated to devPNT/KL) and on gate (also unlocks when an approved
+E-TDD shadow, solutions/SHADOW_*tdd*.md, exists).
+
+Canonical language is English. Legacy Italian frontmatter keys (stato, livello,
+data_inizio, data_fine) and section headings are still accepted for existing projects,
+but are deprecated: new documents should use the English forms.
+
+Standard library only (Python >= 3.8). Windows and POSIX compatible.
+"""
+import argparse
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+VALID_STATES = {"PLANNED", "IN_PROGRESS", "COMPLETED", "CANCELLED"}
+VALID_LEVELS = {"L1", "L2", "L3", "SPIKE"}
+VISION_FILES = ("project_vision.md", "roadmap.md", "principles.md")
+SKIP_DIRS = {".git", ".hg", ".svn", "node_modules", "__pycache__", ".venv", "venv",
+             "dist", "build", ".idea", ".vs"}  # the docs root is excluded separately: its
+# name is resolved per invocation, so it cannot live in a frozen set (see docs_dir()).
+INDEX_HEADER = ("<!-- GENERATED by sdlc_check.py index - do not edit by hand. "
+                "Source of truth: frontmatter of the ANALYSIS_*.md files -->")
+def manifest_header():
+    return ("<!-- GENERATED by sdlc_check.py index - do not edit by hand. "
+            f"Source of truth: the headers of the canonical documents in {docs_dir()}/. -->")
+# Directories whose .md files are durable canonical documents: manifested in INDEX.md.
+# audit/ and solutions/ stay discovery-by-grep (session / process artifacts), not manifested.
+MANIFEST_DIRS = ("vision", "reference", "architecture", "functional", "strategic")
+# Recognized states: canonical docs (CURRENT/SUPERSEDED/...), vision (DRAFT/APPROVED),
+# ADR (Accepted/Proposed/Rejected). Union, to avoid false warnings on conventions in use.
+CANONICAL_STATES = {"CURRENT", "SUPERSEDED", "DRAFT", "DEPRECATED",
+                    "APPROVED", "ACCEPTED", "PROPOSED", "REJECTED"}
+GENERATED_DOCS = {"features_history.md", "INDEX.md"}  # generated: never manifest entries
+MTIME_GRACE = timedelta(seconds=2)
+def guide_index_header():
+    return ("<!-- GENERATED by sdlc_check.py index - do not edit by hand. "
+            f"Source of truth: the headers of the GUIDE_*.md files in {docs_dir()}/reference/. -->")
+GUIDE_PROVENANCE_KEYS = ("source", "distilled_from", "source_hash")  # source_version optional
+# a guide section is "covered" when it carries a source marker or an explicit gap marker
+GUIDE_MARKER_RE = re.compile(r"\[(?:source:[^\]]+|not covered by source)\]")
+# Agent-global KB (Feature B unit 2): ONE client-agnostic root under home.
+# AGENTIC_SDLC_KB_ROOT env var is a TEST/CI seam only (scenario battery must
+# not touch the real user KB); the documented product path is fixed.
+DEFAULT_KB_ROOT = Path(os.environ.get("AGENTIC_SDLC_KB_ROOT", "")) if os.environ.get("AGENTIC_SDLC_KB_ROOT") else Path.home() / ".agentic-sdlc"
+# Subagent Execution (Feature A): a PLAN_[feature].md task must carry these keys,
+# plus at least one of paths/produces (checked separately in cmd_plan).
+PLAN_TASK_REQUIRED = ("id", "title", "verify")
+
+# Deprecated Italian frontmatter keys, mapped to the canonical English ones.
+LEGACY_KEYS = {"stato": "status", "livello": "level",
+               "data_inizio": "start_date", "data_fine": "end_date"}
+
+# Architect pass (F-020): the Capability Ledger is due for ACTIVE L3 analyses
+# born on/after the day the pass shipped. Grandfathering by start_date -- an
+# in-flight analysis from before the pass existed never nags (same lazy-convert
+# doctrine as the pre-1.17 narrative handoff).
+ARCHITECT_PASS_EPOCH = "2026-07-28"
+# Design-review gate (F-021): an L3 started on/after this date owes a REVIEW_LOG
+# row. Same grandfathering discipline as the pass above -- never nag work that
+# predates the rule.
+DESIGN_REVIEW_EPOCH = "2026-07-28"
+def review_log_rel():
+    return f"{docs_dir()}/audit/reviews/REVIEW_LOG.md"
+# Component Map 'Where' refs: a dotted token counts as a path only with one of
+# these suffixes. Deliberately a closed list -- a generic ".\w{1,5}$" turns
+# `app.core`, `OrderStore.save` and `1.18.0` into "the map is rotting".
+FILE_SUFFIXES = ("md", "py", "js", "mjs", "cjs", "ts", "tsx", "jsx", "json", "yaml",
+                 "yml", "toml", "ini", "cfg", "sh", "bat", "ps1", "go", "rs", "java",
+                 "kt", "rb", "php", "cs", "swift", "c", "h", "cpp", "hpp", "sql",
+                 "css", "scss", "html", "vue", "svelte", "tf", "proto", "txt")
+
+# ANALYSIS sections: (canonical English heading, legacy Italian heading).
+SECURITY_SECTION = ("## Security", "## Sicurezza")
+ANALYSIS_SECTIONS = (
+    ("## Objective", "## Obiettivo"),
+    ("## Feature Vision", "## Vision della Feature"),
+    ("## Impact", "## Impatto"),
+    ("## Action Plan", "## Piano d'Azione"),
+    ("## Test Strategy", "## Strategia di Test"),
+    ("## Diary", "## Diario"),
+)
+
+# ------------------------------------------------------------------- docs root
+# `ai_docs/` is the ONE surviving documentation root and the default everywhere.
+# The name is a parameter for exactly two reasons, both temporary by nature: a
+# project that predates the convention has to be READ before it can be migrated,
+# and the migration tool has to see both sides. It is not an invitation to keep a
+# second permanent root -- which is why `init.js` has no rename knob.
+DEFAULT_DOCS_DIR = "ai_docs"
+DOCS_DIR_CANDIDATES = ("ai_docs", "mkt_docs")
+DOCS_DIR_ENV = "AGENTIC_SDLC_DOCS_DIR"  # test/CI seam, read per invocation
+_DOCS_DIR = {"name": DEFAULT_DOCS_DIR}
+
+
+def docs_dir():
+    """The resolved documentation root NAME for this invocation."""
+    return _DOCS_DIR["name"]
+
+
+def set_docs_dir(name):
+    _DOCS_DIR["name"] = name or DEFAULT_DOCS_DIR
+
+
+def ai_path(root, *parts):
+    """A path inside the resolved documentation root."""
+    return Path(root).joinpath(docs_dir(), *parts)
+
+
+def resolve_docs_dir(args=None, start=None):
+    """Explicit beats guessed, exactly like --hybrid.
+
+    Order: --docs-dir, then the env seam (read now, not at import, or it could not
+    be varied by a test), then discovery, then the default. Returns (root, name);
+    the root is None when discovery did not run.
+    """
+    explicit = getattr(args, "docs_dir", None) or os.environ.get(DOCS_DIR_ENV)
+    if explicit:
+        return None, explicit
+    return discover_docs_root(start)
+
+
+def discover_docs_root(start=None):
+    """Walk up looking for a candidate root. PER LEVEL: the nearest one wins.
+
+    Two candidates at the SAME level is the shape of a half-migrated project.
+    Returning either would validate half of it and print a verdict, so it refuses
+    -- naming both -- and the caller exits without a verdict.
+    """
+    cur = Path(start or os.getcwd()).resolve()
+    for p in [cur] + list(cur.parents):
+        found = [c for c in DOCS_DIR_CANDIDATES if (p / c).is_dir()]
+        if len(found) > 1:
+            raise AmbiguousDocsRoot(p, found)
+        if found:
+            return p, found[0]
+    return None, DEFAULT_DOCS_DIR
+
+
+class AmbiguousDocsRoot(Exception):
+    """Two documentation roots side by side: a verdict here would be a guess."""
+
+    def __init__(self, where, found):
+        self.where = where
+        self.found = found
+        super().__init__(
+            f"{where} contains more than one documentation root ({', '.join(found)}): "
+            "refusing to guess which one this project uses. Pass --docs-dir <name> "
+            "to say which, or finish the migration so only one remains.")
+
+
+# --------------------------------------------------------------------- domains
+# One entry per lens of the family. The DATA lives here, in the shared core, so a
+# mixed tree is validated identically from every installed distribution: an entry
+# point never picks rules, it only declares which portable checks it can run.
+#
+# The exclusive part of a rule set -- template, mandatory sections, the risk slot
+# -- has exactly one owner per document. It is the part that never composes:
+# unioning it would demand every domain's ceremony of every document, intersecting
+# it would demand nothing. The risk slot is translated per domain, never dropped.
+DOMAINS = {
+    "code": {
+        "risk_section": SECURITY_SECTION,
+        "risk_label": "## Security and Threat Model",
+        "id_prefix": "F-",
+    },
+    "knowledge": {
+        "risk_section": ("## Sources and Verification",),
+        "risk_label": "## Sources and Verification",
+        "id_prefix": "K-",
+    },
+    "marketing": {
+        "risk_section": ("## Threat Map / Plan Risks", "## Threat Map"),
+        "risk_label": "## Threat Map / Plan Risks",
+        "id_prefix": "M-",
+    },
+    "course": {
+        "risk_section": ("## Learning and Content Risks",),
+        "risk_label": "## Learning and Content Risks",
+        "id_prefix": "C-",
+    },
+}
+# Absent everything -- no `default_domain:` line, no `domain:` field -- a project is
+# `code`. That is what every project created before this field existed already is,
+# so the default is chosen to leave them untouched, not because code is special.
+DEFAULT_DOMAIN = "code"
+
+# Portable checks: composable, opt-in per document via `checks:`. An imported check
+# may only ADD findings, never relax what the owning domain requires -- monotonic, so
+# importing one is safe by construction. Registered by name `<domain>.<check>`.
+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": (), "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 ----------------------------------------------------
+# Each distribution declares what it carries. The battery reads this instead of
+# assuming the code overlay, which is what lets one shared battery run in three
+# distributions without either failing on files a domain legitimately does not have
+# or quietly excusing a domain from doctrine it owes.
+#
+# REQUIRED_CAPABILITIES is the spine: process discipline that is domain-neutral, so
+# no distribution may drop it. A profile missing one fails a shared test -- editing
+# your own profile is therefore NOT a way out of the doctrine, only a way to declare
+# an overlay you genuinely do not have.
+REQUIRED_CAPABILITIES = frozenset({
+    "triage",              # Rule Zero, with the router verdict as a declared output
+    "write_triggers",      # one event, one destination
+    "workstream_registry", # audit/handoff.md as a parallel-safe registry
+    "vision_gate",         # DRAFT informs, APPROVED binds, blind check before promotion
+    "design_review_gate",  # a design reviewed by somebody other than its author
+    "guide_router",        # the mandatory pre-work lookup
+    "worktree_hygiene",    # isolate the work
+})
+# Optional overlays: real capabilities that a domain may legitimately not have.
+# Listed here so "this distribution does not claim it" is a visible decision.
+OPTIONAL_CAPABILITIES = frozenset({
+    "architect_pass",         # does the component already exist? (code overlay)
+    "interaction_contract",   # actor-facing surface spec between use cases and solution (code overlay)
+    "taxonomy_pass",          # do the categories/topics already exist? (knowledge overlay)
+    "comprehension_guides",   # source_kind: code maps of complex components
+    "tdd",                    # test-first discipline
+    "subagent_dispatch",      # opt-in PLAN_[feature].md execution
+    "legacy_narrative_handoff",  # published before the registry format: owes a migration clause
+    "question_discipline",    # when a question to the user is legal (elicitation.md);
+                              # spine candidate once every sibling's elicitation carries it
+})
+# `unit_noun` is vocabulary, not structure: the code domain works on a "feature",
+# the knowledge domain on a "topic". The shared battery asserts the SHAPE
+# (HANDOFF_[<unit>].md) and reads the word from here, so a domain keeps its own
+# language without either weakening the assertion or forking the test.
+# `design_gate_between` is the pair of SKILL.md headings the design review must sit
+# between: after the design exists, before the work is executed. The headings are each
+# domain's own wording -- the code overlay runs five phases, the marketing overlay nine
+# -- so the battery asserts the ORDER, never a shared phase name.
+_PROFILE = {
+    "skill_name": "agentic-sdlc",
+    "unit_noun": "feature",
+    "support_files": (),
+    "capabilities": frozenset(),
+    "design_gate_between": (),
+    "remind_line": "",
+}
+
+
+def set_profile(skill_name, support_files=(), capabilities=(), unit_noun="feature",
+                design_gate_between=(), remind_line=""):
+    _PROFILE.update(skill_name=skill_name,
+                    unit_noun=unit_noun,
+                    support_files=tuple(support_files),
+                    capabilities=frozenset(capabilities),
+                    design_gate_between=tuple(design_gate_between),
+                    remind_line=remind_line)
+
+
+def profile():
+    return dict(_PROFILE)
+
+
+def has_capability(name):
+    return name in _PROFILE["capabilities"]
+
+
+def portable_check(name):
+    """Register a portable check. The callable takes (rel, meta, text) and returns
+    a list of (severity, message) with severity in {'error', 'warning', 'advisory'}."""
+    def register(fn):
+        PORTABLE_CHECKS[name] = fn
+        return fn
+    return register
+
+
+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):
+    """The project's answer for every artifact that declares no `domain:`.
+
+    Read once from `ai_docs/README.md`'s frontmatter. Project-level ON PURPOSE: a
+    per-distribution default would give the same tree two different verdicts
+    depending on which lens the agent happened to load."""
+    readme = ai_path(root, "README.md")
+    if not readme.is_file():
+        return DEFAULT_DOMAIN
+    meta = load_frontmatter(read_text(readme).splitlines())
+    declared = (meta.get("default_domain") or "").strip().strip("'\"").lower()
+    return declared if declared in DOMAINS else DEFAULT_DOMAIN
+
+
+def resolve_domain(meta, default):
+    """(domain, declared_but_unknown) for one artifact. The field RECORDS the answer;
+    it never invents one, and an unrecognized value is reported, not obeyed."""
+    declared = (meta.get("domain") or "").strip().strip("'\"").lower()
+    if not declared:
+        return default, None
+    if declared not in DOMAINS:
+        return default, declared
+    return declared, None
+
+
+def declared_checks(meta):
+    """The `checks:` list, accepted as `[a, b]` or as a comma-separated string."""
+    raw = (meta.get("checks") or "").strip()
+    if not raw:
+        return []
+    return [c.strip().strip("'\"") for c in raw.strip("[]").split(",") if c.strip()]
+
+
+def run_portable_checks(rel, meta, text, errors, warnings, advisories):
+    """Run the checks a document imported. Findings are ADDED to the owning domain's;
+    an unavailable check is a visible warning -- never a silent pass."""
+    for name in declared_checks(meta):
+        namespace = name.split(".", 1)[0]
+        if name not in PORTABLE_CHECKS:
+            if namespace in _ENTRY_POINT["provides"]:
+                warnings.append(f"{rel}: check '{name}' is unknown (no such portable check)")
+            else:
+                warnings.append(
+                    f"{rel}: check '{name}' is not available in this distribution "
+                    f"(it ships {', '.join(_ENTRY_POINT['provides']) or 'no checks'}): "
+                    "the document was NOT checked against it")
+            continue
+        for severity, message in PORTABLE_CHECKS[name](rel, meta, text) or []:
+            {"error": errors, "warning": warnings}.get(severity, advisories).append(
+                f"{rel}: [{name}] {message}")
+
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+except Exception:
+    pass
+
+
+# --- orient (SessionStart hook) ---
+# Fixed, hard-coded doc set (label, path-relative-to-root). No content- or
+# user-derived paths -> no traversal input (P-TM T3); confine_under is
+# defense-in-depth. Emitted at session start by the orient subcommand.
+def orient_docs():
+    d = docs_dir()
+    return [
+        ("Reading guide (README)", f"{d}/README.md"),
+        ("Canonical manifest (INDEX)", f"{d}/INDEX.md"),
+        ("Guide router (when-to-consult)", f"{d}/reference/INDEX.md"),
+        ("Last session handoff", f"{d}/audit/handoff.md"),
+    ]
+ORIENT_PER_DOC_CHARS = 6000     # per-doc truncation
+ORIENT_MAX_TOTAL_CHARS = 16000  # total ingestion cap (P-TM T2); tunable
+
+
+# ----------------------------------------------------------------- utilities
+
+def utc_now_iso():
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def find_project_root(start=None):
+    cur = Path(start or os.getcwd()).resolve()
+    for p in [cur] + list(cur.parents):
+        if (p / docs_dir()).is_dir():
+            return p
+    return cur
+
+
+def require_ai_docs(root, command):
+    """Fail fast when the docs root is missing: prevents silently creating a second
+    documentation root in the wrong working directory."""
+    if not ai_path(root).is_dir():
+        print(f"[ERROR] {ai_path(root)} not found: refusing to run '{command}' here. "
+              "Run agentic-sdlc-init first, or pass --root <project_root>.")
+        return False
+    return True
+
+
+def confine_under(base, rel):
+    """Fail-closed path confinement: resolve `rel` under `base` and require the
+    result to stay inside `base`. Returns None (reject) if `rel` is absolute,
+    contains a '..' part, or resolves outside `base` (including an OSError
+    during resolution, e.g. an unresolvable/reparse-point path on Windows).
+    Single source for path confinement (T2/T3): reused by check_kb_collisions'
+    `overrides:` check and cmd_validate's `distilled_from` check, and by the
+    new `plan` command's paths/consumes/produces/guides confinement."""
+    p = Path(rel)
+    if p.is_absolute() or ".." in p.parts:
+        return None
+    try:
+        t = (base / rel).resolve()
+        t.relative_to(base.resolve())
+        return t
+    except (ValueError, OSError):
+        return None
+
+
+def read_text(path):
+    # utf-8-sig: strips a leading BOM (files authored on Windows) so the
+    # frontmatter '---' on line 0 stays recognizable; reads plain utf-8 otherwise.
+    return path.read_text(encoding="utf-8-sig", errors="replace")
+
+
+def sha256_file(path):
+    # CRLF->LF before hashing: a Windows checkout with core.autocrlf=true
+    # rewrites snapshot files, and a raw-byte hash would flag every guide
+    # [stale] on a fresh clone. Recorded hashes are LF-based, so normalizing
+    # maps CRLF copies back to the same digest.
+    h = hashlib.sha256()
+    h.update(path.read_bytes().replace(b"\r\n", b"\n"))
+    return h.hexdigest()
+
+
+def parse_iso(value):
+    if not value:
+        return None
+    try:
+        dt = datetime.fromisoformat(value.strip().replace("Z", "+00:00"))
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt
+    except ValueError:
+        return None
+
+
+def norm_text(s):
+    return "\n".join(line.rstrip() for line in s.strip().splitlines())
+
+
+def load_frontmatter(lines):
+    meta = {}
+    if not lines or lines[0].strip() != "---":
+        return meta
+    for line in lines[1:60]:
+        if line.strip() == "---":
+            break
+        m = re.match(r"^([A-Za-z_][\w-]*):\s*(.*)$", line)
+        if m:
+            meta[m.group(1).strip().lower()] = m.group(2).strip()
+    # Legacy Italian keys: accepted, normalized to canonical English (deprecated).
+    for legacy, canon in LEGACY_KEYS.items():
+        if legacy in meta and canon not in meta:
+            meta[canon] = meta[legacy]
+    return meta
+
+
+def is_shadow(path, first_line):
+    """A shadow mirror of a devPNT-governed document, not an authoritative ANALYSIS.
+    Recognized by filename (SHADOW_*) or by the marker comment on the FIRST line
+    (legacy shadows saved under an ANALYSIS_* name)."""
+    return path.name.startswith("SHADOW") or first_line.lstrip().startswith("<!-- SHADOW")
+
+
+def list_analyses(root):
+    """Returns [(path, frontmatter, text)] for the ANALYSIS_*.md files (shadows excluded)."""
+    sol = ai_path(root, "solutions")
+    out = []
+    if not sol.is_dir():
+        return out
+    for p in sorted(sol.glob("ANALYSIS_*.md")):
+        text = read_text(p)
+        first_line = text.splitlines()[0] if text else ""
+        if is_shadow(p, first_line):
+            continue
+        out.append((p, load_frontmatter(text.splitlines()), text))
+    return out
+
+
+def has_etdd_shadow(root):
+    """True if an E-TDD shadow exported from devPNT exists in solutions/.
+    In Hybrid mode the approved E-TDD (exported BEFORE implementation) is the
+    design authorization that replaces the IN_PROGRESS ANALYSIS."""
+    sol = ai_path(root, "solutions")
+    if not sol.is_dir():
+        return False
+    return any("tdd" in p.name.lower() for p in sol.glob("SHADOW_*.md"))
+
+
+def iter_files(target):
+    if target.is_file():
+        yield target
+        return
+    for dirpath, dirnames, filenames in os.walk(target):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and d != docs_dir() and not d.startswith(".")]
+        for name in filenames:
+            yield Path(dirpath) / name
+
+
+# ---------------------------------------------------------------------- git
+
+def git_available(root):
+    try:
+        r = subprocess.run(["git", "rev-parse", "--is-inside-work-tree"],
+                           cwd=str(root), capture_output=True, text=True, timeout=10)
+        return r.returncode == 0 and r.stdout.strip() == "true"
+    except Exception:
+        return False
+
+
+def git_head(root):
+    try:
+        r = subprocess.run(["git", "rev-parse", "--short=12", "HEAD"],
+                           cwd=str(root), capture_output=True, text=True, timeout=10)
+        return r.stdout.strip() if r.returncode == 0 else ""
+    except Exception:
+        return ""
+
+
+def git_has_changes(root, rel_path):
+    """True if there are tracked/untracked changes under rel_path."""
+    try:
+        rel = rel_path.replace("\\", "/")
+        r = subprocess.run(["git", "status", "--porcelain", "--", rel],
+                           cwd=str(root), capture_output=True, text=True, timeout=30)
+        return r.returncode == 0 and bool(r.stdout.strip())
+    except Exception:
+        return False
+
+
+def git_changed_since(root, ref, rel_path):
+    """Files changed (tracked + untracked) under rel_path since ref. None if ref unresolvable."""
+    try:
+        r = subprocess.run(["git", "diff", "--name-only", ref, "--", rel_path],
+                           cwd=str(root), capture_output=True, text=True, timeout=30)
+        if r.returncode != 0:
+            return None
+        changed = [l.strip() for l in r.stdout.splitlines() if l.strip()]
+        r2 = subprocess.run(["git", "ls-files", "--others", "--exclude-standard", "--", rel_path],
+                            cwd=str(root), capture_output=True, text=True, timeout=30)
+        if r2.returncode == 0:
+            changed += [l.strip() for l in r2.stdout.splitlines() if l.strip()]
+        return sorted(set(changed))
+    except Exception:
+        return None
+
+
+def git_ref_state(root, ref):
+    """Where a recorded commit stands against HEAD (F-056).
+
+    'ancestor' -- in HEAD's history; 'orphan' -- a commit HEAD's history does not
+    contain (amended, rebased or squash-merged away, or marked on another branch:
+    it stops resolving once pruned, and on any fresh clone); 'missing' -- not a
+    commit in this repository; 'unknown' -- git gave no yes/no answer.
+    Callers pass a hash-shaped ref only: that check is what keeps document
+    content from reaching git's argv as an option."""
+    try:
+        r = subprocess.run(["git", "cat-file", "-e", ref + "^{commit}"],
+                           cwd=str(root), capture_output=True, text=True, timeout=30)
+        if r.returncode != 0:
+            return "missing"
+        r = subprocess.run(["git", "merge-base", "--is-ancestor", ref, "HEAD"],
+                           cwd=str(root), capture_output=True, text=True, timeout=30)
+    except Exception:
+        return "unknown"
+    return {0: "ancestor", 1: "orphan"}.get(r.returncode, "unknown")
+
+
+def git_is_shallow(root):
+    try:
+        r = subprocess.run(["git", "rev-parse", "--is-shallow-repository"],
+                           cwd=str(root), capture_output=True, text=True, timeout=10)
+        return r.returncode == 0 and r.stdout.strip() == "true"
+    except Exception:
+        return False
+
+
+# -------------------------------------------------------------------- index
+
+def build_index(root):
+    analyses = list_analyses(root)
+    # SYNTACTIC predicate, on purpose: the column appears when some analysis WRITES
+    # a `domain:` field, not when one resolves to a domain (every analysis does).
+    # So the generated file is a function of the tree alone -- identical from every
+    # entry point, and byte-identical on every tree that predates the field.
+    tagged = any((meta.get("domain") or "").strip() for _, meta, _ in analyses)
+    default_domain = project_default_domain(root) if tagged else None
+    rows = []
+    for p, meta, _ in analyses:
+        row = [
+            meta.get("id", "?"),
+            meta.get("feature", p.stem.replace("ANALYSIS_", "")),
+            meta.get("level", ""),
+            meta.get("status", "?"),
+            meta.get("start_date", ""),
+            meta.get("end_date", ""),
+            "solutions/" + p.name,
+        ]
+        if tagged:
+            row.insert(2, resolve_domain(meta, default_domain)[0])
+        rows.append(tuple(row))
+    rows.sort(key=lambda r: r[0])
+    header = "| ID | Feature | Level | Status | Started | Finished | Doc |"
+    sep = "|---|---|---|---|---|---|---|"
+    if tagged:
+        header = "| ID | Feature | Domain | Level | Status | Started | Finished | Doc |"
+        sep = "|---|---|---|---|---|---|---|---|"
+    lines = [INDEX_HEADER,
+             "# Feature History (generated)",
+             "",
+             header,
+             sep]
+    for r in rows:
+        lines.append("| " + " | ".join(r) + " |")
+    return "\n".join(lines) + "\n"
+
+
+# "Status:"/"Stato:" line in the body (with or without ** **), prefix before the description
+_STATUS_LINE = re.compile(r"^\**\s*(?:status|stato)\s*\**\s*:\s*\**\s*([A-Za-z][\w-]*)", re.I)
+# pure metadata lines to skip when picking the fallback description
+_META_LINE = re.compile(r"^\**\s*(date|data|task ref|version|versione|owner|autore|branch|agente|agent|created|creato|updated|aggiornato)\b", re.I)
+
+
+def extract_doc_meta(path):
+    """(title, description, status, supersedes) of a canonical doc.
+
+    Recognizes TWO header conventions: the YAML-lite frontmatter
+    (description/status/supersedes/title) and the in-body `**Status:** X`
+    line (used by ADRs and legacy docs). As a fallback it derives the title
+    from the first '# H1' and the description from the first prose line,
+    skipping metadata lines.
+    """
+    text = read_text(path)
+    lines = text.splitlines()
+    meta = load_frontmatter(lines)
+    body = lines
+    if lines and lines[0].strip() == "---":
+        for i in range(1, min(len(lines), 60)):
+            if lines[i].strip() == "---":
+                body = lines[i + 1:]
+                break
+
+    title = meta.get("title", "")
+    if not title:
+        for line in body:
+            m = re.match(r"^#\s+(.*)$", line)
+            if m:
+                title = m.group(1).strip()
+                break
+    title = title or path.stem
+
+    status = meta.get("status", "").upper()
+    if not status:
+        for line in body[:25]:
+            m = _STATUS_LINE.match(line.strip())
+            if m:
+                status = m.group(1).upper()
+                break
+
+    desc = meta.get("description", "")
+    if not desc:
+        in_comment = False
+        for line in body:
+            s = line.strip()
+            # track HTML-comment state across lines: skipping only the OPENING
+            # line made line 2 of a multi-line comment the manifest description
+            # (the shipped vision template opens with a 3-line comment, so the
+            # most-read row of the manifest read '... -->')
+            if in_comment:
+                if "-->" in s:
+                    in_comment = False
+                    s = s.split("-->", 1)[1].strip()
+                    if not s:
+                        continue
+                else:
+                    continue
+            elif s.startswith("<!--"):
+                if "-->" not in s:
+                    in_comment = True
+                    continue
+                s = s.split("-->", 1)[1].strip()
+                if not s:
+                    continue
+            # a table row or a bare bullet is not a description: the manifest is
+            # the first thing an agent reads to orient, and '| Milestone | ... |'
+            # in that column is a row carrying no information
+            if (not s or s.startswith("#") or s.startswith("|") or s.startswith("---")
+                    or re.match(r"^[-*+]\s", s) or _META_LINE.match(s)):
+                continue
+            if s.startswith(">"):
+                s = s.lstrip(">").strip()
+            m = _STATUS_LINE.match(s)
+            if m:
+                # "Status: X — description": keep the part after the status; if empty, skip
+                rest = s[m.end():].strip(" *—–-:.")
+                if not rest:
+                    continue
+                s = rest
+            if s:
+                desc = s
+                break
+    desc = re.sub(r"\s+", " ", desc).strip()
+    if len(desc) > 160:
+        desc = desc[:157].rstrip() + "..."
+    return title, desc, status, meta.get("supersedes", "").strip()
+
+
+def list_canonical_docs(root):
+    """[(rel_to_ai_docs, path, (title, desc, status, supersedes))] for canonical docs."""
+    ai = ai_path(root)
+    out = []
+    for d in MANIFEST_DIRS:
+        base = ai / d
+        if not base.is_dir():
+            continue
+        for p in sorted(base.rglob("*.md")):
+            rel_parts = p.relative_to(base).parts
+            if any(part.startswith(".") for part in rel_parts[:-1]):
+                continue  # dot-subdirs (e.g. reference/.sources/) are never canonical
+            if p.name in GENERATED_DOCS or p.name == "README.md":
+                continue
+            out.append((p.relative_to(ai).as_posix(), p, extract_doc_meta(p)))
+    return out
+
+
+def build_manifest(root):
+    docs = list_canonical_docs(root)
+    lines = [manifest_header(),
+             f"# `{docs_dir()}/` document index (generated)",
+             "",
+             "Complete manifest of the canonical documents. For the reading priority",
+             "(must-reads) see the hand-curated `README.md`. The ANALYSIS history is in",
+             "`strategic/features_history.md`. `audit/` and `solutions/` are discovery-by-grep,",
+             "not manifested here."]
+    by_dir = {}
+    for rel, _, meta in docs:
+        by_dir.setdefault(rel.split("/", 1)[0], []).append((rel, meta))
+    for top in MANIFEST_DIRS:
+        rows = by_dir.get(top)
+        if not rows:
+            continue
+        lines += ["", f"## {top}/", "",
+                  "| Document | Status | Description |", "|---|---|---|"]
+        for rel, (title, desc, status, _sup) in rows:
+            d = (desc or title).replace("|", "\\|")
+            lines.append(f"| `{rel}` | {status or '-'} | {d} |")
+    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)
+    # "Already ours" = written by ANY family entry point: the header is WRITTEN
+    # with entry_script(), so recognition must not hard-code one distribution's
+    # script name (a registry generated by mkt_check.py is just as generated).
+    if re.search(r"GENERATED by \S+ index - do not edit by hand", text):
+        return []
+    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")
+    out = []
+    if not ref.is_dir():
+        return out
+    for p in sorted(ref.glob("GUIDE_*.md")):
+        text = read_text(p)
+        out.append((p.relative_to(ai_path(root)).as_posix(), p,
+                    load_frontmatter(text.splitlines()), text))
+    return out
+
+
+def check_kb_collisions(root, project_guides, errors, warnings):
+    """Cross-root awareness (unit 2): project-wins precedence, declared via 'overrides:'."""
+    kb_root = DEFAULT_KB_ROOT
+    # The agent-global KB is client-agnostic and shared across lenses: it keeps its
+    # own fixed layout and NEVER follows a project's docs-root name (TS16).
+    kb_ref = (kb_root / "ai_docs" / "reference")
+    try:
+        if root.resolve() == kb_root.resolve():
+            return  # validating the KB itself: no self-comparison
+    except OSError:
+        return
+    if not kb_ref.is_dir():
+        return  # no KB on this machine: zero behavior change
+    kb_names = {p.name for _, p, _, _ in list_guides(kb_root)}
+    for rel, p, meta, _ in project_guides:
+        ov = (meta.get("overrides") or "").strip()
+        if ov:
+            # T6: untrusted cross-root pointer — distilled_from parity, fail closed
+            target = confine_under(kb_ref, ov)
+            if target is None:
+                errors.append(f"{rel}: overrides '{ov}' is absolute, contains '..', or escapes the KB "
+                              "reference dir — rejected (fail closed)")
+                continue
+            if not target.is_file():
+                warnings.append(f"{rel}: overrides target '{ov}' not found in KB ({kb_ref})")
+        if p.name in kb_names and ov != p.name:
+            warnings.append(f"{rel}: undeclared collision with KB guide '{p.name}' (project wins) — declare overrides: {p.name}")
+
+
+def build_guide_index(root):
+    lines = [guide_index_header(),
+             "# Operative guides (generated router)",
+             "",
+             "One row per guide. `description` is the when-to-consult line; provenance",
+             "shows what the guide was distilled from. Freshness: run `sdlc_check.py stale`.",
+             "",
+             "| Guide | Status | When to consult | Source | Source version |",
+             "|---|---|---|---|---|"]
+    for rel, p, meta, _ in list_guides(root):
+        lines.append("| `{}` | {} | {} | {} | {} |".format(
+            p.name, meta.get("status", "-") or "-",
+            (meta.get("description", "") or "-").replace("|", "\\|"),
+            (meta.get("source", "") or "-").replace("|", "\\|"),
+            meta.get("source_version", "") or "-"))
+    return "\n".join(lines) + "\n"
+
+
+def cmd_index(root):
+    if not require_ai_docs(root, "index"):
+        return 1
+    hist = ai_path(root, "strategic", "features_history.md")
+    hist.parent.mkdir(parents=True, exist_ok=True)
+    hist.write_text(build_index(root), encoding="utf-8")
+    print(f"[ok] ANALYSIS index regenerated: {hist}")
+    # INDEX.md only if canonical docs exist: no empty manifest on minimal projects
+    if list_canonical_docs(root):
+        manifest = ai_path(root, "INDEX.md")
+        manifest.write_text(build_manifest(root), encoding="utf-8")
+        print(f"[ok] document manifest regenerated: {manifest}")
+    else:
+        print("[info] no canonical documents: INDEX.md not generated")
+    guides = list_guides(root)
+    gidx = ai_path(root, "reference", "INDEX.md")
+    if guides:
+        gidx.write_text(build_guide_index(root), encoding="utf-8")
+        print(f"[ok] guide router regenerated: {gidx}")
+    else:
+        # An EMPTY router still gets written: Rule Zero makes reading it a
+        # mandatory, declared step, and `no match` may not be faked. Without the
+        # stub, the required verdict is unsatisfiable on every new project --
+        # and a rule that cannot be obeyed on first contact gets discarded.
+        gidx.parent.mkdir(parents=True, exist_ok=True)
+        gidx.write_text(guide_index_header() + "\n# Operative guides (generated router)\n\n"
+                        "No guides in this project yet. This file exists so the Rule Zero "
+                        "router lookup has something to read: the honest verdict here is "
+                        "`router: no match`.\n\n"
+                        "A guide is written when the user hands over indications to follow "
+                        "(`source_kind: document`), or when a high-complexity component needs "
+                        "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
+
+
+# ----------------------------------------------------------------- validate
+
+def has_section(text, aliases):
+    return any(a in text for a in aliases)
+
+
+def section_body(text, aliases):
+    """The body of the first matching `## ` section, or None if no alias is present.
+
+    Portable checks read a section rather than the whole document, so a phrase that
+    happens to appear elsewhere cannot satisfy a check about this section."""
+    lines = text.splitlines()
+    for i, line in enumerate(lines):
+        if not any(line.startswith(a) for a in aliases):
+            continue
+        body = []
+        for nxt in lines[i + 1:]:
+            if nxt.startswith("## "):
+                break
+            body.append(nxt)
+        return "\n".join(body).strip()
+    return None
+
+
+def design_review_due(meta):
+    """True when an L3 ANALYSIS owes a design-review row (review.md moment 1):
+    implementation has started or finished, and it began on/after the gate
+    shipped. PLANNED is exempt -- the review is due at the END of Phase 3, so an
+    analysis still being drafted is not late."""
+    if meta.get("level", "").upper() != "L3":
+        return False
+    if meta.get("status") not in ("IN_PROGRESS", "COMPLETED"):
+        return False
+    started = parse_iso((meta.get("start_date") or "").strip().strip("'\""))
+    return started is not None and started >= parse_iso(DESIGN_REVIEW_EPOCH)
+
+
+def review_logged(root, analysis_name):
+    """True when REVIEW_LOG.md carries a design-moment row naming this ANALYSIS.
+    The filename matches anywhere in the row (loose on purpose: a freshness
+    signal must not turn a formatting slip into a false 'you skipped the
+    review'), but the moment is read from the `tier` COLUMN -- the schema
+    reserves it for exactly this, and matching 'design' anywhere in the row let
+    a CLOSURE row saying 'conformance to the design' satisfy the check."""
+    log = root / review_log_rel()
+    if not log.is_file():
+        return False
+    stem = analysis_name[:-3] if analysis_name.endswith(".md") else analysis_name
+    # match the filename on a word boundary: a plain substring lets a longer
+    # sibling (ANALYSIS_vision_clarity) satisfy a shorter one (ANALYSIS_vision)
+    name_re = re.compile(r"(?<![\w-])" + re.escape(stem) + r"(?![\w-])")
+    tier_idx = None
+    for line in read_text(log).splitlines():
+        line = line.strip()
+        if not line.startswith("|"):
+            continue
+        cells = [c.strip() for c in line.strip("|").split("|")]
+        if tier_idx is None:
+            lowered = [c.lower() for c in cells]
+            if "tier" in lowered:          # header found: trust it over position
+                tier_idx = lowered.index("tier")
+                continue
+        if not name_re.search(line):
+            continue
+        # schema: | date | doc_key | tier | reviewer | raised | real | verdict | rounds |
+        idx = tier_idx if tier_idx is not None else 2
+        if len(cells) > idx and re.match(r"design\b", cells[idx], re.I):
+            return True
+    return False
+
+
+def has_ledger_heading(text):
+    """True when a REAL '## Capability Ledger' heading exists: fenced code
+    blocks are removed first, then HTML comments. An unterminated '<!--' only
+    opens a comment at the start of a line -- nuking to EOF on an inline
+    mention (or an unclosed example inside a fence) made a document that
+    HAS its ledger get told it has none."""
+    stripped = re.sub(r"^(```|~~~).*?^\1", "", text, flags=re.M | re.S)
+    stripped = re.sub(r"<!--.*?-->", "", stripped, flags=re.S)
+    stripped = re.sub(r"^[ \t]*<!--(?!.*?-->).*\Z", "", stripped, flags=re.M | re.S)
+    return bool(re.search(r"^##[ \t]+Capability Ledger[ \t]*$", stripped, re.M))
+
+
+def ledger_due(meta):
+    """True when an ANALYSIS owes a '## Capability Ledger' (architect.md):
+    an L3 started on/after the day the pass shipped. Grandfathered by
+    start_date ALONE -- deliberately NOT by status: closure flips the ANALYSIS
+    to COMPLETED before `check` runs (SKILL.md phase 5), so a status filter
+    would silence the backstop at the only moment the process mandates the
+    validator. A malformed/absent start_date is not due (fail-open: cmd_validate
+    already errors on a missing one, and guessing an epoch from garbage would
+    nag projects the pass never reached)."""
+    if meta.get("level", "").upper() != "L3":
+        return False
+    if meta.get("status") == "CANCELLED":
+        return False   # abandoned work has no legitimate way to satisfy this
+    started = parse_iso((meta.get("start_date") or "").strip().strip("'\""))
+    return started is not None and started >= parse_iso(ARCHITECT_PASS_EPOCH)
+
+
+MAP_SECTION_RE = re.compile(r"^#{2,3}[ \t]+Component Map\b.*?$(.*?)(?=^#{1,3}[ \t]+\S|\Z)",
+                            re.M | re.S | re.I)
+
+
+def map_where_refs(arch_text):
+    """Normalized, symbol-stripped paths from the Component Map's 'Where' column
+    ONLY -- never from the whole document. Harvesting the whole file let the
+    canonical template's own '## Directory Structure' backticks satisfy the check
+    and silently disable it on every project that fills that section in.
+    Returns None when the document has no Component Map at all."""
+    m = MAP_SECTION_RE.search(arch_text)
+    if not m:
+        return None
+    refs, where_idx = [], None
+    for ln in m.group(1).splitlines():
+        ln = ln.strip()
+        if not ln.startswith("|"):
+            continue
+        cells = [c.strip() for c in ln.strip("|").split("|")]
+        if len(cells) < 2 or not cells[0] or set(cells[0]) <= {"-", ":"}:
+            continue
+        if where_idx is None:
+            lowered = [c.lower() for c in cells]
+            if "where" not in lowered:
+                return []          # no Where column: nothing is mapped
+            where_idx = lowered.index("where")
+            continue
+        if where_idx < len(cells):
+            for _ref, path_part, _sym in _map_refs(cells[where_idx]):
+                refs.append(path_part.lstrip("./").strip("/"))
+    return refs
+
+
+def _map_refs(where):
+    """Backticked refs in a 'Where' cell that are file paths: they contain a
+    separator, or end in a KNOWN source-file suffix. Windows separators are
+    normalized. Everything else in that cell is prose and must stay silent --
+    a false 'the map is rotting' teaches readers to ignore the output, which is
+    worse than the rot. `app.core`, `OrderStore.save` and `1.18.0` are prose."""
+    out = []
+    for ref in re.findall(r"`([^`]+)`", where):
+        path_part, _, symbol = ref.partition("#")
+        path_part = path_part.replace("\\", "/").strip()
+        if not path_part or "://" in path_part:
+            continue  # a URL is not a repo path
+        # A slash-less token counts only if it looks like a FILENAME. The one
+        # real false-positive class is `Next.js` / `Node.js` / `Vue.js`: a
+        # CamelCase stem with a `.js` tail is a framework name, not a file.
+        # The exclusion is scoped to that suffix ON PURPOSE -- a blanket
+        # CamelCase rule would silence `App.tsx`, `Program.cs`, `Main.java`,
+        # which are exactly what React/C#/Java projects put in a Where cell.
+        stem, _, suffix = path_part.rsplit("/", 1)[-1].rpartition(".")
+        framework_name = (suffix.lower() == "js"
+                          and bool(re.fullmatch(r"[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]*)*", stem)))
+        looks_like_path = "/" in path_part or (
+            bool(re.search(r"\.(" + "|".join(FILE_SUFFIXES) + r")$", path_part, re.I))
+            and not framework_name)
+        if looks_like_path:
+            out.append((ref, path_part, symbol.strip()))
+    return out
+
+
+def check_component_map(root, text, advisories):
+    """Anti-rot for the '## Component Map' of strategic/architecture.md
+    (architect.md): every path-shaped backticked ref in the 'Where' column must
+    still resolve on disk, and its '#symbol' must still appear as a whole word
+    in a matched file. This is the map's equivalent of the guides' source_hash.
+    ADVISORY: a freshness signal, never a gate -- not even under --strict (the
+    accepted ceremony budget was a warning, not a blocked pipeline)."""
+    m = MAP_SECTION_RE.search(text)   # one regex for both checks: they cannot drift
+    if not m:
+        return
+    rows = [ln.strip() for ln in m.group(1).splitlines() if ln.strip().startswith("|")]
+    where_idx, header_cells, checked, data_rows, ragged = None, 0, 0, 0, 0
+    for row in rows:
+        cells = [c.strip() for c in row.strip("|").split("|")]
+        if len(cells) < 2 or not cells[0] or set(cells[0]) <= {"-", ":"}:
+            continue
+        if where_idx is None:  # the first non-separator row is the header
+            lowered = [c.lower() for c in cells]
+            if "where" not in lowered:
+                advisories.append("strategic/architecture.md: Component Map has no 'Where' "
+                                  "column in its header -- the anti-rot check cannot run; "
+                                  "give the table a Where column of `path/to/file#Symbol` refs")
+                return
+            where_idx, header_cells = lowered.index("where"), len(cells)
+            continue
+        if all(c in ("", "...", "…") for c in cells):
+            continue                      # untouched template placeholder row
+        data_rows += 1
+        if len(cells) != header_cells:    # ragged: never silently unchecked
+            ragged += 1
+            continue
+        component, where = cells[0], cells[where_idx]
+        for ref, path_part, symbol in _map_refs(where):
+            checked += 1
+            if confine_under(root, re.sub(r"[*?\[\]]", "x", path_part)) is None:
+                advisories.append(f"strategic/architecture.md: Component Map row '{component}': "
+                                  f"ref '{ref}' escapes the project root: rejected")
+                continue
+            target = root / path_part
+            try:
+                if target.exists():          # literal first: `app/[id]/page.tsx` is a real path
+                    matches = [target]
+                elif any(c in path_part for c in "*?["):
+                    matches = list(root.glob(path_part))
+                else:
+                    matches = []
+            except (ValueError, OSError):
+                matches = []
+            if not matches:
+                advisories.append(f"strategic/architecture.md: Component Map row '{component}': "
+                                  f"'{path_part}' no longer exists -- the map is rotting, "
+                                  "update the row or drop it")
+                continue
+            files = [f for f in matches if f.is_file()]
+            if symbol and files:
+                word = re.compile(r"(?<![A-Za-z0-9_])" + re.escape(symbol) + r"(?![A-Za-z0-9_])")
+                if not any(word.search(read_text(f)) for f in files):
+                    advisories.append(f"strategic/architecture.md: Component Map row '{component}': "
+                                      f"symbol '{symbol}' not found in '{path_part}' -- renamed or "
+                                      "removed, update the row")
+    if ragged:
+        advisories.append(f"strategic/architecture.md: Component Map has {ragged} row(s) whose "
+                          "column count differs from the header -- unchecked; an escaped '|' in "
+                          "a cell shifts the columns")
+    if data_rows and not checked and not ragged:
+        # only once the map claims real components: a freshly seeded project
+        # carries the template placeholder and must NOT be nagged on day zero
+        advisories.append("strategic/architecture.md: Component Map has rows but no checkable "
+                          "path in its 'Where' column -- the anti-rot check is inert; write refs "
+                          "as `path/to/file#Symbol`")
+
+
+def cmd_validate(root, strict=False, hybrid=False):
+    # advisories: architect-pass freshness signals. Reported, never escalated by
+    # --strict -- the accepted ceremony budget (project_vision.md "no ceremony
+    # ratchet") was a warning, and a warning that reddens CI is a gate.
+    errors, warnings, advisories = [], [], []
+    ai = ai_path(root)
+    if not ai.is_dir():
+        if strict:
+            print(f"[ERROR] {ai} does not exist: nothing to validate. In --strict mode this "
+                  "fails so a wrong working directory cannot produce a green pipeline.")
+            return 1
+        print(f"[info] {ai} does not exist: nothing to validate (project without SDLC docs).")
+        return 0
+
+    # Vision: presence and declared state
+    for name in VISION_FILES:
+        f = ai / "vision" / name
+        if not f.is_file():
+            warnings.append(f"vision/{name} missing")
+            continue
+        head = "\n".join(read_text(f).splitlines()[:12])
+        m = re.search(r"(?:Status|Stato):\s*(DRAFT|APPROVED)", head)
+        if not m:
+            errors.append(f"vision/{name}: missing 'Status: DRAFT|APPROVED' in the first lines")
+        elif m.group(1) == "DRAFT":
+            # advisory, not a warning: bootstrap MANDATES DRAFT, so a warning here
+            # makes `validate --strict` red on every freshly bootstrapped project
+            # until a human runs the blind check -- and teams delete the CI step
+            # rather than block on it. DRAFT is a state, not a defect.
+            advisories.append(f"vision/{name} is DRAFT: not a gating authority, "
+                              "have the user validate it")
+
+    # ANALYSIS: frontmatter and mandatory sections
+    # Ids are unique WITHIN a domain (prefixes F-/K-/M-/C- keep them apart in practice):
+    # two lenses over one tree must not collide on a number neither of them chose.
+    seen_ids = {}
+    default_domain = project_default_domain(root)
+    analyses = list_analyses(root)
+    for p, meta, text in analyses:
+        rel = "solutions/" + p.name
+        if not meta:
+            errors.append(f"{rel}: frontmatter missing")
+            continue
+        domain, unknown_domain = resolve_domain(meta, default_domain)
+        if unknown_domain:
+            warnings.append(f"{rel}: domain '{unknown_domain}' not recognized "
+                            f"({'/'.join(sorted(DOMAINS))}): validated as '{domain}'")
+        fid = meta.get("id")
+        if not fid:
+            errors.append(f"{rel}: 'id' field missing")
+        elif (domain, fid) in seen_ids:
+            errors.append(f"{rel}: id '{fid}' duplicated (already used in {seen_ids[(domain, fid)]})")
+        else:
+            seen_ids[(domain, fid)] = rel
+        status = meta.get("status", "")
+        if status not in VALID_STATES:
+            errors.append(f"{rel}: status '{status}' not valid ({'/'.join(sorted(VALID_STATES))})")
+        if not meta.get("start_date"):
+            errors.append(f"{rel}: 'start_date' missing")
+        if status == "COMPLETED" and not meta.get("end_date"):
+            errors.append(f"{rel}: COMPLETED without 'end_date'")
+        level = meta.get("level")
+        if level and level.upper() not in VALID_LEVELS:
+            warnings.append(f"{rel}: level '{level}' not recognized ({'/'.join(sorted(VALID_LEVELS))})")
+        # The risk slot is translated per domain, never dropped: whichever lens owns
+        # the document, it owes ITS account of what could go wrong.
+        rules = DOMAINS[domain]
+        if not has_section(text, rules["risk_section"]):
+            errors.append(f"{rel}: section '{rules['risk_label']}' missing (mandatory)")
+        for en, it in ANALYSIS_SECTIONS:
+            if not has_section(text, (en, it)):
+                warnings.append(f"{rel}: section '{en}' missing")
+        run_portable_checks(rel, meta, text, errors, warnings, advisories)
+        if not level and (parse_iso((meta.get("start_date") or "").strip().strip("'\"")) or
+                          parse_iso("1970-01-01")) >= parse_iso(ARCHITECT_PASS_EPOCH):
+            # advisory + epoch-gated, exactly like the check it guards: a warning
+            # here would redden --strict CI on every pre-1.18 analysis that never
+            # carried the optional field. (Same defect the advisories bucket was
+            # invented to prevent -- reintroduced once, caught in review.)
+            advisories.append(f"{rel}: 'level' missing (L1/L2/L3/Spike) -- risk-proportional "
+                              "checks cannot apply, and dropping the line is cheaper than "
+                              "doing the work it triggers")
+        # comment-stripped, anchored: a '<!-- TODO: the ## Capability Ledger -->'
+        # must not read as the section being present
+        # Hybrid: the design lives in devPNT and its §4.5 gate owns this slot
+        # (the Hybrid ownership matrix: "run ONE of them, never both"), and its log
+        # rows are keyed on e_isp_/e_tdd_ doc_keys, not on this filename -- so
+        # firing here would be a permanent, unfixable false positive.
+        if not hybrid and design_review_due(meta) and not review_logged(root, p.name):
+            advisories.append(f"{rel}: L3 in implementation with no design-review row in "
+                              f"{review_log_rel()} -- the design was reviewed by nobody but its "
+                              "author before code was written (review.md moment 1)")
+        if ledger_due(meta) and not has_ledger_heading(text):
+            advisories.append(f"{rel}: L3 without '## Capability Ledger' -- the architect pass "
+                              "left no record (architect.md); run it before the Impact")
+
+    # Generated index aligned
+    hist = ai / "strategic" / "features_history.md"
+    if analyses:
+        if not hist.is_file():
+            errors.append("strategic/features_history.md missing: run 'sdlc_check.py index'")
+        elif norm_text(read_text(hist)) != norm_text(build_index(root)):
+            errors.append("strategic/features_history.md not aligned with the ANALYSIS files: run 'sdlc_check.py index'")
+
+    # Canonical document manifest aligned (Poka-Yoke: unindexed file = dirty closure)
+    docs = list_canonical_docs(root)
+    manifest = ai / "INDEX.md"
+    if docs:
+        if not manifest.is_file():
+            errors.append(f"{docs_dir()}/INDEX.md missing: run 'sdlc_check.py index'")
+        elif norm_text(read_text(manifest)) != norm_text(build_manifest(root)):
+            errors.append(f"{docs_dir()}/INDEX.md not aligned with the canonical documents: run 'sdlc_check.py index'")
+
+    # Canonical document lifecycle: declared status + supersedes coherence
+    canon_status = {rel: meta[2] for rel, _, meta in docs}
+    for rel, _, (title, desc, status, supersedes) in docs:
+        if not status:
+            warnings.append(f"{rel}: missing 'status:' in the header (CURRENT/SUPERSEDED/DRAFT/DEPRECATED)")
+        elif status not in CANONICAL_STATES:
+            warnings.append(f"{rel}: status '{status}' not recognized ({'/'.join(sorted(CANONICAL_STATES))})")
+        if supersedes:
+            base = os.path.basename(supersedes)
+            for other, ost in canon_status.items():
+                if (other == supersedes or other.endswith("/" + supersedes)
+                        or os.path.basename(other) == base) and ost == "CURRENT":
+                    warnings.append(f"{other}: still CURRENT but superseded by {rel} (set status: SUPERSEDED)")
+
+    # Component Map anti-rot (architect.md): rows must still resolve on disk
+    arch = ai / "strategic" / "architecture.md"
+    if arch.is_file():
+        arch_text = read_text(arch)
+        check_component_map(root, arch_text, advisories)
+        # the missing half of the loop: `mark` asserts an area was read closely
+        # enough to name its capability owners, and nothing verified that claim.
+        # An ANALYZED area with no map row is how the brownfield guard is
+        # disarmed -- the area looks read, so the map's silence becomes groundable.
+        _, _, plan_rows = parse_audit_plan(root)
+        mapped = map_where_refs(arch_text)
+        if plan_rows and mapped is not None:
+            for prow in plan_rows:
+                if prow["status"] != "ANALYZED":
+                    continue
+                if confine_under(root, prow["path"]) is None:
+                    continue                     # stale already rejects these
+                if re.search(r"owns no component", prow.get("note", ""), re.I):
+                    continue                     # declared, not forgotten: the opt-out
+                area = prow["path"].replace("\\", "/").strip("/")
+                if area.startswith("./"):
+                    area = area[2:]
+                if area in ("", "."):
+                    continue                     # the whole root: every row is inside it
+                if not (root / area).exists():
+                    continue                     # gone from disk: not a mapping gap
+                if not any(mp == area or mp.startswith(area + "/") for mp in mapped):
+                    advisories.append(
+                        f"strategic/architecture.md: '{prow['path']}' is ANALYZED in the audit "
+                        "plan but owns no Component Map row -- marking asserts the area was read "
+                        "closely enough to name what it owns, and the map's silence there is now "
+                        "groundable for a MISSING verdict (architect.md). If it genuinely owns no "
+                        "component, say so in the audit plan's Notes column: 'owns no component'")
+
+    # Guide checks (ai_docs/reference/GUIDE_*.md): structure only — freshness is stale's job
+    guides = list_guides(root)
+    for rel, p, meta, text in guides:
+        missing = [k for k in GUIDE_PROVENANCE_KEYS if not meta.get(k)]
+        if missing:
+            warnings.append(f"{rel}: guide missing provenance key(s): {', '.join(missing)}")
+        # (b) per-section fidelity markers: every '## ' section body must carry a marker
+        body = text.split("---", 2)[-1]
+        sections = re.split(r"^##\s+", body, flags=re.M)[1:]
+        unmarked = [s.splitlines()[0].strip() for s in sections if not GUIDE_MARKER_RE.search(s)]
+        if unmarked:
+            warnings.append(f"{rel}: section(s) without [source: ...] / [not covered by source] marker: "
+                            + "; ".join(unmarked[:5]))
+        # (c) distilled_from confinement — fail closed (P-TM T6, distilled_from vector)
+        df = meta.get("distilled_from", "")
+        if df and confine_under(root, df) is None:
+            errors.append(f"{rel}: distilled_from '{df}' is absolute, contains '..', or resolves "
+                          "outside the project root: rejected")
+    check_kb_collisions(root, guides, errors, warnings)
+    # guide-router alignment (mirror of the root-manifest check)
+    gidx = ai_path(root, "reference", "INDEX.md")
+    if not gidx.is_file() and not guides:
+        # zero guides: the stub is a convenience for the mandatory Rule Zero read
+        advisories.append(f"{docs_dir()}/reference/INDEX.md missing: Rule Zero requires reading the "
+                          "guide router and forbids faking its verdict, so the router exists "
+                          "even with zero guides -- run 'sdlc_check.py index'")
+    if guides:
+        if not gidx.is_file():
+            # guides EXIST and the router does not: the agent's mandatory lookup
+            # finds nothing and legally declares 'absent', so the guide that
+            # governs the work is never consulted. An absent router must not be
+            # graded below a merely stale one.
+            errors.append(f"{docs_dir()}/reference/INDEX.md missing while GUIDE_*.md files exist: "
+                          "the router is the only thing that routes work to them -- "
+                          "run 'sdlc_check.py index'")
+        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: 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:
+            warnings.append("audit/handoff.md without a 'Date: YYYY-MM-DD' header")
+        else:
+            try:
+                stamp = datetime.strptime(m.group(1), "%Y-%m-%d").replace(tzinfo=timezone.utc)
+                age = (datetime.now(timezone.utc) - stamp).days
+                if age > 14:
+                    warnings.append(f"audit/handoff.md is {age} days old: treat it as history, not current state")
+            except ValueError:
+                warnings.append("audit/handoff.md: date not parseable")
+
+    for a in advisories:
+        print(f"[note]  {a}")
+    for w in warnings:
+        print(f"[warn]  {w}")
+    for e in errors:
+        print(f"[ERROR] {e}")
+    print(f"\nValidation: {len(errors)} errors, {len(warnings)} warnings, "
+          f"{len(advisories)} advisories.")
+    if advisories:
+        print("[note] advisories are freshness signals: never fail a build, not even --strict.")
+    if strict and warnings and not errors:
+        print("[strict] warnings are failures in --strict mode.")
+    return 1 if errors or (strict and warnings) else 0
+
+
+# ------------------------------------------------------------- audit_plan
+
+def parse_audit_plan(root):
+    f = ai_path(root, "audit", "audit_plan.md")
+    rows, lines = [], []
+    if f.is_file():
+        lines = read_text(f).splitlines()
+        for i, line in enumerate(lines):
+            if not line.strip().startswith("|"):
+                continue
+            cells = [c.strip() for c in line.strip().strip("|").split("|")]
+            if len(cells) < 2:
+                continue
+            if cells[0].lower() in ("path", "percorso") or set(cells[0]) <= set("-: "):
+                continue
+            rows.append({
+                "line": i,
+                "path": cells[0],
+                "status": cells[1].upper(),
+                "ref": cells[2] if len(cells) > 2 else "",
+                "note": cells[3] if len(cells) > 3 else "",
+            })
+    return f, lines, rows
+
+
+def cmd_stale(root, hybrid=False):
+    rc = 0
+    # --- guide freshness (source_hash vs snapshot) — runs in EVERY mode
+    drifted = []
+    for rel, p, meta, _ in list_guides(root):
+        df, rec = meta.get("distilled_from", ""), meta.get("source_hash", "")
+        if not df or not rec:
+            continue  # structure problems are validate's job
+        src = root / df
+        if not src.is_file():
+            print(f"[warn]  {rel}: distilled_from '{df}' not found — snapshot missing")
+            rc = 1
+            continue
+        if sha256_file(src) != rec:
+            drifted.append((rel, df))
+    for rel, df in drifted:
+        print(f"[stale] {rel}: source snapshot '{df}' changed since distillation — regenerate the guide")
+    if drifted:
+        rc = 1
+    # --- audit-plan staleness — delegated to devPNT/KL in hybrid
+    if hybrid:
+        print("[info] hybrid mode: audit-plan staleness is delegated to devPNT/KL, skipping.")
+        return rc                                  # was: implicit skip-all; guide rc survives
+    f, _, rows = parse_audit_plan(root)
+    if not rows:
+        print(f"[info] no rows in {f}: nothing to check "
+              "(audit not initialized, or Hybrid mode where mapping is delegated to devPNT).")
+        return rc                                  # was: return 0 — MUST carry guide rc
+    use_git = git_available(root)
+    entry = entry_script()
+    # The audit plan records the marks: its own edits are not a change to the area
+    # that contains it. Counting them made a committed hash mark of that area
+    # stale again, and every re-mark repeated the loop.
+    try:
+        plan_rel = f.resolve().relative_to(Path(root).resolve()).as_posix()
+    except ValueError:
+        plan_rel = None
+    # F-056: an ANALYZED row whose reference cannot be evaluated is UNVERIFIED,
+    # never fresh. Each `continue` below that skips such a row records it here;
+    # skipping silently is how a pruned reference printed `[ok]` over three areas.
+    unverifiable = []
+    stale = []
+    for row in rows:
+        if row["status"] != "ANALYZED":
+            continue
+        rel, ref = row["path"], row["ref"]
+        # Confine BEFORE touching the filesystem: audit_plan.md is document
+        # content, so an absolute row ('/'), a drive-relative one or a '..'
+        # escape would otherwise walk outside the project (P-TM T2/T3). A bare
+        # '/' is the row init.js used to seed, and `root / "/"` is the drive.
+        target = confine_under(root, rel)
+        if target is None:
+            print(f"[warn]  {rel}: path is absolute, contains '..', or resolves outside "
+                  "the project root: rejected (use a project-relative path, '.' for the root)")
+            continue
+        if not target.exists():
+            print(f"[warn]  {rel}: path does not exist")
+            continue
+        changed = []
+        remark = f"re-analyze the area, then run: {entry} mark {rel}"
+        if re.fullmatch(r"[0-9a-fA-F]{7,40}", ref or ""):
+            if not use_git:
+                print(f"[stale] {rel}: reference '{ref}' is a git commit, but git is not usable "
+                      "here (not a git work tree, git missing, or the repository refused): its "
+                      "freshness cannot be evaluated. Run stale inside the git work tree, or "
+                      + remark)
+                unverifiable.append(rel)
+                continue
+            state = git_ref_state(root, ref)
+            if state == "missing":
+                shallow = (" This clone is shallow: full history may hold it "
+                           "(git fetch --unshallow)." if git_is_shallow(root) else "")
+                print(f"[stale] {rel}: git ref '{ref}' is not a commit in this repository "
+                      "(amended, rebased or squash-merged away and pruned, or never fetched "
+                      f"here): its freshness cannot be evaluated.{shallow} To fix, " + remark)
+                unverifiable.append(rel)
+                continue
+            if state == "orphan":
+                print(f"[warn]  {rel}: git ref '{ref}' is not an ancestor of HEAD (amended, "
+                      "rebased, squash-merged, or marked on another branch): it stops "
+                      "resolving once git prunes it, and on any fresh clone. Re-mark now: "
+                      f"{entry} mark {rel}")
+            res = git_changed_since(root, ref, rel.replace("\\", "/"))
+            if res is None:
+                print(f"[stale] {rel}: git could not compare against ref '{ref}': its "
+                      "freshness cannot be evaluated. To fix, " + remark)
+                unverifiable.append(rel)
+                continue
+            changed = res
+        else:
+            ts = parse_iso(ref)
+            if ts is None:
+                print(f"[stale] {rel}: reference '{ref}' is neither a git commit nor an ISO "
+                      "UTC timestamp: its freshness cannot be evaluated. To fix, " + remark)
+                unverifiable.append(rel)
+                continue
+            for fp in iter_files(target):
+                mtime = datetime.fromtimestamp(fp.stat().st_mtime, tz=timezone.utc)
+                if mtime > ts + MTIME_GRACE:
+                    try:
+                        name = str(fp.relative_to(root)).replace("\\", "/")
+                    except ValueError:   # symlink out of the tree: report absolute, never crash
+                        name = str(fp)
+                    changed.append(name)
+        changed = [c for c in changed if c != plan_rel]
+        if changed:
+            stale.append((rel, changed))
+
+    if unverifiable:
+        rc = 1                                     # unverified is not fresh (F-056)
+    if not stale:
+        if not unverifiable:
+            print("[ok] no analyzed area was modified after its last recorded analysis.")
+        return rc                                  # was: return 0 — MUST carry guide rc
+    print("Areas modified after the last recorded analysis:")
+    for rel, changed in stale:
+        print(f"  {rel}  ({len(changed)} files)")
+        for c in changed[:10]:
+            print(f"    - {c}")
+        if len(changed) > 10:
+            print(f"    ... and {len(changed) - 10} more")
+    print(f"\nAfter re-analyzing, record it with: {entry} mark <path>")
+    return 1                                       # stale areas dominate: rc already implied
+
+
+def cmd_mark(root, paths):
+    if not require_ai_docs(root, "mark"):
+        return 1
+    f, lines, rows = parse_audit_plan(root)
+    use_git_ref = git_available(root) and not any(
+        git_has_changes(root, raw.replace("\\", "/").rstrip("/")) for raw in paths
+    )
+    ref = git_head(root) if use_git_ref else utc_now_iso()
+    by_path = {r["path"].replace("\\", "/").rstrip("/"): r for r in rows}
+
+    if not lines:
+        lines = ["# Audit Plan", "",
+                 "| Path | Status | Reference | Notes |",
+                 "|---|---|---|---|"]
+        rows = []
+
+    def row_text(path, note):
+        return f"| {path} | ANALYZED | {ref} | {note} |"
+
+    # validate EVERY path before printing or mutating anything: a rejection
+    # after an '[ok] ... added as ANALYZED' line is a lie the agent will act on
+    keys = []
+    for raw in paths:
+        key = raw.replace("\\", "/").rstrip("/") or "."
+        if confine_under(root, key) is None:
+            print(f"[ERROR] {raw}: absolute, '..'-escaping, or outside the project root: "
+                  "refusing to mark (use a project-relative path, '.' for the root). "
+                  "Nothing was written.")
+            return 1
+        keys.append(key)
+
+    appended = []
+    for key in keys:
+        display = key + ("/" if (root / key).is_dir() and key != "." else "")
+        existing = by_path.get(key)
+        if existing:
+            lines[existing["line"]] = row_text(existing["path"], existing["note"])
+            print(f"[ok] {existing['path']} -> ANALYZED ({ref})")
+        else:
+            appended.append(row_text(display, ""))
+            print(f"[ok] {display} added as ANALYZED ({ref})")
+
+    if appended:
+        insert_at = (max(r["line"] for r in rows) + 1) if rows else len(lines)
+        lines[insert_at:insert_at] = appended
+
+    f.parent.mkdir(parents=True, exist_ok=True)
+    f.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    if use_git_ref:
+        # F-056: the reference is born here, so this is where the gestures that
+        # orphan it are named. An amend was the observed one.
+        print(f"[info] {ref} is the current HEAD. Commit this audit plan change as a new "
+              "commit: amending, rebasing or squash-merging that commit orphans the "
+              f"reference, and `{entry_script()} stale` fails once it no longer resolves. "
+              "After a squash or rebase merge, re-mark on the integration branch.")
+    return 0
+
+
+# ------------------------------------------------- orientation-hook wiring
+# F-041: read-only mirror of the installer-side detection in lib.js
+# (findOrientHook + orientHookValidator). The JS owns WRITING hooks, with its
+# injection guards; this side only DETECTS, at `check`, so a project whose
+# sessions start unoriented hears about it in-project (ENFORCEMENT par.4: the
+# hook is wired at init only -- pre-F-036 and agent-bootstrapped projects never
+# got it, and a wired-but-dead hook is "the worst of the three states").
+# The file list is a SUPERSET of the JS one: .codex/hooks.json is documented in
+# ENFORCEMENT par.4 but never written by init. Pinned equal on both sides:
+# the entry-point names, and (F-042) the user-settings path derivation --
+# CLAUDE_CONFIG_DIR when set, else <home>/.claude -- empty-string env falsy
+# on both sides.
+ORIENT_HOOK_ENTRY_POINTS = ("sdlc_check.py", "mkt_check.py")
+ORIENT_HOOK_CONFIG_FILES = (".claude/settings.json",
+                            ".claude/settings.local.json",
+                            ".codex/hooks.json")
+ORIENT_HOOK_CONFIG_CAP = 1024 * 1024  # settings are tiny; cap pathological files
+_ORIENT_HOOK_CMD_RE = re.compile(r" orient(\s|$)")
+_ORIENT_HOOK_TOKEN_RE = re.compile(r'"([^"]*)"|(\S+)')
+
+
+def _orient_entries_in(p):
+    """Yield the SessionStart commands invoking an orient entry point from ONE
+    client config file. Fail-open: an unreadable, oversized, malformed or
+    directory-shaped file contributes nothing. Reads are utf-8-sig -- a BOM'd
+    settings.json (PowerShell/Notepad) must not read as unwired (declared
+    divergence from Node's JSON.parse)."""
+    try:
+        if not p.is_file() or p.stat().st_size > ORIENT_HOOK_CONFIG_CAP:
+            return
+        data = json.loads(p.read_text(encoding="utf-8-sig"))
+    except Exception:
+        return
+    if not isinstance(data, dict):
+        return
+    hooks = data.get("hooks")
+    groups = hooks.get("SessionStart") if isinstance(hooks, dict) else None
+    if groups is None:
+        groups = data.get("SessionStart")  # the .codex/hooks.json shape
+    if not isinstance(groups, list):
+        return
+    for group in groups:
+        if not isinstance(group, dict):
+            continue
+        inner = group.get("hooks")
+        for h in inner if isinstance(inner, list) else [group]:
+            cmd = h.get("command") if isinstance(h, dict) else None
+            if (isinstance(cmd, str)
+                    and any(n in cmd for n in ORIENT_HOOK_ENTRY_POINTS)
+                    and _ORIENT_HOOK_CMD_RE.search(cmd)):
+                yield cmd
+
+
+def _orient_user_settings_path():
+    """The machine-global settings file (F-042 wires it at install time).
+
+    Read at CALL time -- a DECLARED divergence from AGENTIC_SDLC_KB_ROOT's
+    import-time read: unittest imports this module once before any test runs,
+    so an import-time seam would be frozen before the matrix could set it.
+    AGENTIC_SDLC_USER_SETTINGS is the test-isolation seam (python-side only);
+    the production derivation mirrors lib.js: CLAUDE_CONFIG_DIR || ~/.claude."""
+    seam = os.environ.get("AGENTIC_SDLC_USER_SETTINGS")
+    if seam:
+        return Path(seam)
+    cfg = os.environ.get("CLAUDE_CONFIG_DIR")
+    return (Path(cfg) if cfg else Path.home() / ".claude") / "settings.json"
+
+
+def _orient_hook_commands(root):
+    """Yield (command, at_user_level) across every known client config: the
+    three project-relative files, then the machine-global user settings --
+    the file the installer wires (F-042), without which a fixed machine's
+    projects would read as unwired forever."""
+    for rel in ORIENT_HOOK_CONFIG_FILES:
+        for cmd in _orient_entries_in(Path(root) / rel):
+            yield cmd, False
+    for cmd in _orient_entries_in(_orient_user_settings_path()):
+        yield cmd, True
+
+
+def orient_hook_state(root):
+    """'wired' | 'dead' | 'unwired'.
+
+    A matching entry whose tokens name no validator is "cannot tell" and counts
+    as wired (the lib.js contract: never report broken on cannot-tell). 'dead'
+    requires every matching entry to name a validator that does not resolve:
+    the client runs ALL SessionStart hooks -- project-level AND user-level
+    merge -- so one live entry at either level still orients the session
+    (any-resolves aggregation across levels). Relative tokens resolve against
+    the project root (the vendored-validator convention); a USER-level relative
+    token has no cwd to resolve against and is treated as cannot-tell."""
+    matched = False
+    for cmd, at_user_level in _orient_hook_commands(root):
+        matched = True
+        token = None
+        for m in _ORIENT_HOOK_TOKEN_RE.finditer(cmd):
+            tok = m.group(1) if m.group(1) is not None else m.group(2)
+            if any(tok.endswith(n) for n in ORIENT_HOOK_ENTRY_POINTS):
+                token = tok
+                break
+        if token is None:
+            return "wired"
+        tp = Path(token)
+        if not tp.is_absolute():
+            if at_user_level:
+                return "wired"  # cannot tell: no cwd exists at user level
+            tp = Path(root) / tp
+        if tp.exists():
+            return "wired"
+    return "dead" if matched else "unwired"
+
+
+def print_orient_hook_note(root):
+    """Print the FS-A wiring note (unwired / dead), or nothing when wired.
+
+    Informational only, by contract: never an exit code, never a validate
+    warning (--strict CI must not fail on a hook that legitimately lives in
+    git-ignored settings.local.json). Called by the spine's cmd_check AND by
+    an overlay that replaces check with its own pipeline (the marketing lens
+    does): the note is check-layer behaviour, whoever owns the check."""
+    try:
+        state = orient_hook_state(root)
+        if state == "unwired":
+            print("[note] agent sessions start without automatic orientation on this "
+                  "machine (no session-orientation hook found at project or user level). "
+                  "Fix once: update or reinstall the skill npm package (on Claude Code "
+                  "with Python it wires the hook machine-wide), or wire it per "
+                  "ENFORCEMENT.md par.4")
+        elif state == "dead":
+            print("[note] a session-orientation hook is configured but points at a "
+                  "validator that no longer exists, so sessions start unoriented. Fix: "
+                  "update or reinstall the skill npm package, or correct the command. "
+                  "Details: ENFORCEMENT.md par.4")
+    except Exception:
+        pass  # detection must never break check
+
+
+def cmd_check(root, strict=False, hybrid=False):
+    print("===== validate =====")
+    rc_v = cmd_validate(root, strict=strict, hybrid=hybrid)
+    print("\n===== stale =====")
+    rc_s = cmd_stale(root, hybrid=hybrid)
+    print(f"\ncheck: {'CLEAN' if not (rc_v or rc_s) else 'NOT CLEAN'} "
+          f"(validate rc={rc_v}, stale rc={rc_s})")
+    print_orient_hook_note(root)
+    return 1 if (rc_v or rc_s) else 0
+
+
+# --------------------------------------------------------------------- gate
+
+# --- UserPromptSubmit reminder hook (F-046) --------------------------------
+# `orient` fires once per session and decays; a session that never invokes the
+# skill never had the protocol at all. Measured 2026-09-06: a release ran in
+# this repo against a `GUIDE_release.md` the session never consulted, because
+# SKILL.md -- where the duty is written -- had not been read.
+#
+# The carrier is kb's (F-041 item B), lifted here so all three lenses share one
+# machine instead of two that do the same thing. Its contract is kept: the line
+# is CONSTANT and reads NOTHING -- nothing repo- or session-controlled may ride
+# text injected every turn, and zero reads is what keeps the per-turn cost flat.
+# What changed is the payload's first duty and the wiring. First duty: decide
+# whether the skill governs this work and, if it does, read it once -- an
+# unread protocol cannot be applied, which is the failure above. Wiring: a
+# default instead of opt-in, on the owner's explicit acceptance of the per-turn
+# cost (`vision/rulings.md` r19; the "no ceremony ratchet" Non-Goal admits a
+# never-zero cost by that acceptance, and a trivial turn pays a yes/no
+# judgement, never a load).
+
+REMIND_FALLBACK = (
+    "decide whether the {skill} skill governs this work; if it does, load it "
+    "once before acting -- an unread protocol cannot be applied."
+)
+
+
+def cmd_remind(args):
+    """UserPromptSubmit hook: print the lens's constant per-turn line. Always 0.
+
+    argv is ignored whole and nothing is read: a hook surface must not fail, and
+    a flag typo must not cost a turn's context."""
+    try:
+        prof = profile()
+        line = prof.get("remind_line") or REMIND_FALLBACK.format(skill=prof["skill_name"])
+        print(f"{prof['skill_name']}: {line}")
+    except Exception:
+        pass
+    return 0
+
+def cmd_gate(args):
+    file_path = args.file or ""
+    if args.hook:
+        try:
+            # bytes -> utf-8-sig: the hook payload is UTF-8 JSON regardless of the
+            # console code page; '-sig' strips the BOM (PowerShell pipes)
+            raw = sys.stdin.buffer.read().decode("utf-8-sig", errors="replace")
+            payload = json.loads(raw)
+            file_path = (payload.get("tool_input") or {}).get("file_path") or ""
+        except Exception:
+            return 0  # unparseable input: do not block
+    if not file_path:
+        return 0
+    root = Path(args.root).resolve() if args.root else find_project_root()
+    try:
+        rel = str(Path(file_path).resolve().relative_to(root)).replace("\\", "/")
+    except ValueError:
+        return 0  # outside the project: not this gate's concern
+    if rel.startswith((docs_dir() + "/", "tests/", "test/")):
+        return 0
+    protected = [p.strip().replace("\\", "/").rstrip("/")
+                 for p in (args.protected or "").split(";") if p.strip()]
+    if not protected:
+        return 0
+    if not any(rel == p or rel.startswith(p + "/") for p in protected):
+        return 0
+    for _, meta, _ in list_analyses(root):
+        if meta.get("status") == "IN_PROGRESS":
+            return 0
+    if args.hybrid and has_etdd_shadow(root):
+        return 0  # Hybrid design gate: an approved E-TDD shadow authorizes the change
+    if args.hybrid:
+        sys.stderr.write(
+            f"[sdlc gate] '{rel}' is on a protected path but no E-TDD shadow "
+            "(solutions/SHADOW_*tdd*.md) exists and no ANALYSIS_*.md is IN_PROGRESS. "
+            "In Hybrid mode, export the approved E-TDD shadow from devPNT before implementing.\n")
+        return 2
+    sys.stderr.write(
+        f"[sdlc gate] '{rel}' is on a protected path but no ANALYSIS_*.md is IN_PROGRESS. "
+        "If your analysis already exists, set its frontmatter to 'status: IN_PROGRESS' "
+        "(that flip is what opens the gate); otherwise write it first (Phase 3).\n")
+    return 2
+
+
+# --------------------------------------------------------------------- plan
+# Subagent Execution (Feature A). Zero-execution surface: this section and
+# everything it calls MUST NOT spawn a process (no subprocess/os.system/eval/
+# exec, no git_* helper). It validates a PLAN_[feature].md and prints a task
+# brief as text; the orchestrator (dispatch.md) is the sole executor.
+
+_PLAN_JSON_RE = re.compile(r"```json\s*\n(.*?)```", re.DOTALL)
+
+
+def extract_plan_json(text):
+    """Extract the first fenced ```json block from a PLAN_[feature].md body.
+    Returns (data, "") on success, or (None, reason) on any failure. Never
+    raises: a malformed or missing block is a validation failure, not a crash."""
+    m = _PLAN_JSON_RE.search(text or "")
+    if not m:
+        return None, "no fenced ```json block found in the plan file"
+    try:
+        data = json.loads(m.group(1))
+    except (ValueError, TypeError) as e:
+        return None, f"malformed JSON in the plan block: {e}"
+    if not isinstance(data, dict):
+        return None, "plan JSON block must be a JSON object"
+    return data, ""
+
+
+def load_ledger(path):
+    """Read the sidecar ledger {"<task_id>": {"status", "verify_result",
+    "timestamp"}}. Absent file -> ({}, ""). Malformed/unreadable -> ({}, reason).
+    Never raises, never hangs: the ledger is untrusted state read on every call."""
+    if not path.is_file():
+        return {}, ""
+    try:
+        raw = read_text(path)
+        data = json.loads(raw)
+    except (ValueError, TypeError, OSError) as e:
+        return {}, f"ledger '{path}' unreadable/malformed, treating as empty: {e}"
+    if not isinstance(data, dict):
+        return {}, f"ledger '{path}' is not a JSON object, treating as empty"
+    return data, ""
+
+
+def _confine_or_reject(base, rel, label, rel_label, errors):
+    t = confine_under(base, rel)
+    if t is None:
+        errors.append(f"{rel_label}: {label} '{rel}' is absolute, contains '..', or escapes "
+                      f"'{base}' — rejected (fail closed)")
+    return t
+
+
+def _validate_plan_tasks(root, data, rel_label, errors, warnings):
+    """Shared core of `plan validate`/`plan brief`: schema + confinement checks.
+    Returns the task list (possibly empty) on success; errors/warnings are
+    appended in place. Callers decide the exit code."""
+    tasks = data.get("tasks")
+    if not isinstance(tasks, list) or not tasks:
+        errors.append(f"{rel_label}: 'tasks' must be a non-empty JSON array")
+        return []
+    ref_dir = ai_path(root, "reference")
+    kb_ref = DEFAULT_KB_ROOT / "ai_docs" / "reference"
+    seen_ids = set()
+    for i, task in enumerate(tasks):
+        loc = f"{rel_label}: task[{i}]"
+        if not isinstance(task, dict):
+            errors.append(f"{loc}: not a JSON object")
+            continue
+        missing = [k for k in PLAN_TASK_REQUIRED if not task.get(k)]
+        if missing:
+            errors.append(f"{loc}: missing required field(s): {', '.join(missing)}")
+        if not task.get("paths") and not task.get("produces"):
+            errors.append(f"{loc}: must declare at least one of 'paths'/'produces'")
+        tid = task.get("id")
+        if tid:
+            if tid in seen_ids:
+                errors.append(f"{loc}: duplicate task id '{tid}'")
+            seen_ids.add(tid)
+        for key in ("paths", "consumes", "produces"):
+            for p in (task.get(key) or []):
+                _confine_or_reject(root, p, key, loc, errors)
+        for g in (task.get("guides") or []):
+            in_project = confine_under(ref_dir, g)
+            in_kb = confine_under(kb_ref, g)
+            if in_project is None and in_kb is None:
+                errors.append(f"{loc}: guide '{g}' is not confined under the project reference "
+                              f"dir ({ref_dir}) or the agent KB reference dir ({kb_ref}) — rejected")
+    return tasks
+
+
+def cmd_plan(root, args):
+    """Zero-execution: validates/briefs a PLAN_[feature].md. Never spawns a
+    process, never calls a git_* helper, never runs the opaque `verify` text —
+    it is printed, not executed."""
+    plan_path = Path(args.file)
+    if not plan_path.is_absolute():
+        plan_path = root / plan_path
+    if not plan_path.is_file():
+        sys.stderr.write(f"[plan] plan file not found: {plan_path}\n")
+        return 2
+    rel_label = str(plan_path)
+    data, reason = extract_plan_json(read_text(plan_path))
+    if data is None:
+        sys.stderr.write(f"[plan] {rel_label}: {reason}\n")
+        return 2
+
+    errors, warnings = [], []
+    tasks = _validate_plan_tasks(root, data, rel_label, errors, warnings)
+
+    ledger_path = plan_path.with_name(plan_path.stem + ".ledger.json")
+    ledger, ledger_reason = load_ledger(ledger_path)
+    if ledger_reason:
+        warnings.append(ledger_reason)
+    if not errors:
+        task_ids = {t.get("id") for t in tasks if isinstance(t, dict)}
+        for lid in ledger:
+            if lid not in task_ids:
+                warnings.append(f"ledger id '{lid}' not found in {rel_label}: orphaned entry (not fatal)")
+
+    for w in warnings:
+        sys.stderr.write(f"[warn] {w}\n")
+    for e in errors:
+        sys.stderr.write(f"[ERROR] {e}\n")
+
+    if args.plan_cmd == "validate":
+        if errors:
+            sys.stderr.write(f"\n[plan] validate: {len(errors)} errors, {len(warnings)} warnings.\n")
+            return 2
+        print(f"[ok] {rel_label}: plan valid ({len(tasks)} task(s), {len(warnings)} warning(s)).")
+        return 0
+
+    # brief
+    if errors:
+        sys.stderr.write(f"\n[plan] brief: plan is invalid, refusing to brief ({len(errors)} errors).\n")
+        return 2
+    target = None
+    for t in tasks:
+        if isinstance(t, dict) and t.get("id") == args.task:
+            target = t
+            break
+    if target is None:
+        sys.stderr.write(f"[plan] brief: task id '{args.task}' not found in {rel_label}\n")
+        return 2
+
+    print(f"# Task: {target.get('id')} — {target.get('title', '')}")
+    print()
+    print("## Task block")
+    print(json.dumps(target, indent=2))
+    print()
+    print("## Produces of prior-order tasks (interfaces)")
+    prior_produces = []
+    for t in tasks:
+        if not isinstance(t, dict):
+            continue
+        if t.get("id") == target.get("id"):
+            break
+        prior_produces.extend(t.get("produces") or [])
+    if prior_produces:
+        for p in prior_produces:
+            print(f"- {p}")
+    else:
+        print("(none)")
+    print()
+    print("## Guide pointers (paths, not content)")
+    guides = target.get("guides") or []
+    if guides:
+        for g in guides:
+            print(f"- {g}")
+    else:
+        print("(none)")
+    print()
+    print("## Verify (opaque text — orchestrator runs this out of band, NOT executed here)")
+    print(target.get("verify", ""))
+    return 0
+
+
+# --- F-050: the benefit report -------------------------------------------
+# The process's central claim is that it makes divergence visible BEFORE
+# implementation. That claim lived in prose for four months while the evidence
+# for it sat unread in REVIEW_LOG. This reads it.
+#
+# Columns are resolved BY HEADER NAME, never by width. `templates.md` states
+# that contract ("extra or reordered columns are fine -- but the header must
+# say `tier`") and three widths are legal today: the original 8, Standalone's 9
+# (F-048 added `model`), and Hybrid's 10 (`instrument` + `notes`, and no
+# `reviewer` at all). A width whitelist reads none of the last, and silently
+# reports a devPNT-governed project as having no data at all.
+#
+# Two honesty rules, both learned from this unit's own review: whatever cannot
+# be read is COUNTED and NAMED, at the row level AND at the cell level. A ratio
+# over a silently shrunken denominator is worse than no ratio.
+REVIEW_CORE = ("date", "doc_key", "tier", "findings_real", "verdict")
+REVIEW_POSITIONAL = {
+    8: ("date", "doc_key", "tier", "reviewer", "findings_raised",
+        "findings_real", "verdict", "revise_rounds"),
+    9: ("date", "doc_key", "tier", "model", "reviewer", "findings_raised",
+        "findings_real", "verdict", "revise_rounds"),
+    10: ("date", "doc_key", "tier", "model", "instrument", "findings_raised",
+         "findings_real", "verdict", "revise_rounds", "notes"),
+}
+
+
+def _table_cells(line):
+    """Cells of a Markdown table row, or None when the line is not one.
+    Separator rows (---, :---:, any alignment colons) are not data."""
+    s = line.strip()
+    if not s.startswith("|"):
+        return None
+    if set(s) <= set("|-: "):
+        return None
+    return [c.strip() for c in s.strip("|").split("|")]
+
+
+def parse_review_log(text):
+    """-> (rows, unparsed). Columns come from the header when there is one.
+
+    Falls back to the positional maps only for a table with no header, so a
+    hand-kept log still reads. A row whose cell count does not match the
+    header's is unparsed and named -- never dropped."""
+    rows, unparsed, names = [], [], None
+    for n, line in enumerate(text.splitlines(), 1):
+        cells = _table_cells(line)
+        if cells is None:
+            continue
+        lowered = [c.lower() for c in cells]
+        if names is None and "tier" in lowered and "verdict" in lowered:
+            names = lowered                      # the header IS the column map
+            continue
+        # The header supplies the map -- that is what makes reordered and extra
+        # columns readable. But a log legitimately carries MIXED widths (F-048
+        # widened the schema and did not rewrite history), so a row that does
+        # not match the header is read by the positional map for its own width
+        # before it is given up on. Only a width no map knows is unparsed.
+        if names is not None and len(cells) == len(names):
+            row = dict(zip(names, cells))
+        else:
+            positional = REVIEW_POSITIONAL.get(len(cells))
+            if positional is None:
+                unparsed.append((n, "%d cells: %s" % (
+                    len(cells),
+                    "header declares %d and no positional map fits"
+                    % len(names) if names else "no header, and no map fits")))
+                continue
+            row = dict(zip(positional, cells))
+        missing = [c for c in REVIEW_CORE if c not in row]
+        if missing:
+            unparsed.append((n, "no %s column" % "/".join(missing)))
+            continue
+        if not re.match(r"^\d{4}-\d{2}-\d{2}$", row["date"]):
+            unparsed.append((n, "date cell %r is not a date" % row["date"][:24]))
+            continue
+        rows.append(row)
+    return rows, unparsed
+
+
+def review_findings(value):
+    """The count in a `findings_real` cell, or None when it states no number.
+
+    None is NOT zero. `all` and `VOID -- instrument error` appear in real logs,
+    and counting them as zero findings silently deflates the one ratio this
+    report exists to state. Anchored at the START of the cell so a prose cell
+    like `R1 4 BLOCK + 8 WARN` does not yield a confident 4."""
+    m = re.match(r"^(\d+)\b", (value or "").strip())
+    return int(m.group(1)) if m else None
+
+
+def _is_fail(verdict):
+    """FAIL as a WORD, so `PASS (no failures)` is not counted as a failure."""
+    return re.search(r"\bFAIL\b", (verdict or "").upper()) is not None
+
+
+def _is_pass(verdict):
+    return re.search(r"\bPASS\b", (verdict or "").upper()) is not None
+
+
+def _print_read_cost():
+    """The cost side, printed with the benefit and NEVER without it: a catch
+    rate with no cost term justifies unbounded doctrine, and a cost term with
+    no catch rate justifies deleting the process. When it cannot be measured
+    the line still prints, saying so -- silence here IS the catch rate quoted
+    alone, which is the thing this report exists to prevent."""
+    skill_dir = Path(__file__).resolve().parent.parent
+    contract = skill_dir / "SKILL.md"
+    print()
+    if not contract.is_file():
+        print("Read cost: unavailable -- SKILL.md not found beside this "
+              "validator (%s)" % skill_dir)
+        return
+    files = [p for p in sorted(skill_dir.glob("*.md")) if p.name != "SKILL.md"]
+    support = sum(p.stat().st_size for p in files)
+    head = contract.stat().st_size
+    # The TOTAL, and the files itemised. Printing only the two terms lets the
+    # one that fell be quoted while the one that grew stays lumped -- which is
+    # exactly how a -7.8% headline coexisted with a read surface that grew.
+    print("Read cost of %s: SKILL.md %d bytes (every session) + %d bytes "
+          "across %d support files (read on trigger) = %d bytes total"
+          % (skill_dir.name, head, support, len(files), head + support))
+    for p in files:
+        print("    %-24s %8d" % (p.name, p.stat().st_size))
+
+
+def cmd_benefit(root):
+    """Report what the process caught, beside what it costs to read.
+
+    ALWAYS exits 0 and emits no warning or advisory. This number is the
+    criterion future units are judged by; a measurement that can fail a build
+    becomes a target, and a targeted measurement stops measuring."""
+    log = root / review_log_rel()
+    print("=== benefit: what the process caught, and what it costs to read ===")
+    if not log.is_file():
+        print("[info] no %s yet: nothing to report. The number appears once "
+              "reviews are logged." % review_log_rel())
+        _print_read_cost()
+        return 0
+    rows, unparsed = parse_review_log(read_text(log))
+    # `tier` carries the MOMENT in Standalone (design / closure) and the
+    # reviewer WEIGHT in Hybrid (deep / light / code / guide / vision). A
+    # Hybrid row is a real review whose moment this column does not state, so
+    # it is counted and named, never folded into a moment by guesswork.
+    moments = {"design": [], "closure": []}
+    unstated = {}
+    unstated_found = unstated_code = unstated_uncounted = 0
+    for r in rows:
+        tier = r["tier"].lower()
+        if tier.startswith("design"):
+            moments["design"].append(r)
+        elif tier.startswith("closure"):
+            moments["closure"].append(r)
+        else:
+            unstated[tier] = unstated.get(tier, 0) + 1
+            n = review_findings(r["findings_real"])
+            if n is None:
+                unstated_uncounted += 1
+            else:
+                unstated_found += n
+                if tier.startswith("code"):
+                    unstated_code += n
+    classified = moments["design"] + moments["closure"]
+    print("rows parsed: %d   rows unparsed: %d%s"
+          % (len(rows), len(unparsed),
+             ("  -> " + "; ".join("line %d: %s" % u for u in unparsed[:5]))
+             if unparsed else ""))
+    print("reviews with a stated moment: %d   moment not stated by `tier`: %d%s"
+          % (len(classified), sum(unstated.values()),
+             ("  (" + ", ".join("%s x%d" % (t, n) for t, n
+                                in sorted(unstated.items())) + ")")
+             if unstated else ""))
+    if not classified:
+        _print_read_cost()
+        return 0
+    dates = sorted(r["date"] for r in classified)
+    print("span of the reviews counted below: %s -> %s" % (dates[0], dates[-1]))
+
+    print()
+    print("%-9s %6s %10s %11s %10s" % ("moment", "rows", "findings",
+                                       "FAIL verdict", "per review"))
+    totals, uncounted = {}, 0
+    for m in ("design", "closure"):
+        rs = moments[m]
+        counts = [review_findings(r["findings_real"]) for r in rs]
+        uncounted += sum(1 for c in counts if c is None)
+        found = sum(c for c in counts if c is not None)
+        failed = sum(1 for r in rs if _is_fail(r["verdict"]))
+        totals[m] = found
+        print("%-9s %6d %10d %11d %10.1f"
+              % (m, len(rs), found, failed, (found / len(rs)) if rs else 0.0))
+    total = sum(totals.values())
+    if uncounted:
+        print("findings cells stating no number: %d (counted as unknown, "
+              "never as zero)" % uncounted)
+    if total:
+        print()
+        print("Caught BEFORE the code existed: %d / %d findings = %.0f%%"
+              % (totals["design"], total, 100.0 * totals["design"] / total))
+        # The residue, stated as a BOUND rather than as a direction. The
+        # sentence this replaces claimed the share was "a floor, not a
+        # ceiling" because `code` rows are post-implementation -- which is
+        # backwards, since folding them LOWERS the design share. But the fact
+        # was right and only the direction wrong, so `code` findings sit on
+        # the closure side of the upper bound instead of being discarded with
+        # it. No direction is printed at all: the unstated set pushes both
+        # ways, and only an interval is true of all of it.
+        if unstated_found:
+            denom = total + unstated_found
+            print("Bounded by the %d findings in rows whose moment `tier` "
+                  "does not state: %.0f%%-%.0f%% (`code` rows are "
+                  "post-implementation by definition, so their findings sit "
+                  "on the closure side of the upper bound)"
+                  % (unstated_found, 100.0 * totals["design"] / denom,
+                     100.0 * (totals["design"] + unstated_found - unstated_code)
+                     / denom))
+        if unstated_uncounted:
+            print("%d unstated rows state no findings count (`all`, `VOID`): "
+                  "neither zero nor countable, so they lie outside both "
+                  "bounds" % unstated_uncounted)
+    failed_all = sum(1 for r in classified if _is_fail(r["verdict"]))
+    inconclusive = sum(1 for r in classified if not _is_fail(r["verdict"])
+                       and not _is_pass(r["verdict"]))
+    print("Reviews whose verdict contains FAIL: %d / %d = %.0f%%%s"
+          % (failed_all, len(classified), 100.0 * failed_all / len(classified),
+             ("   (+%d inconclusive)" % inconclusive) if inconclusive else ""))
+    print("(both figures are over the %d reviews whose moment `tier` states)"
+          % len(classified))
+    _print_read_cost()
+    return 0
+
+
+def cmd_orient(args):
+    """SessionStart hook: emit a bounded, repo-sourced ai_docs/ orientation to
+    stdout and ALWAYS return 0 (fail-open, P-TM T8) -- a session hook must never
+    block the session or surface a traceback. Zero-execution (P-TM T1): reads a
+    fixed hard-coded doc set, confine_under each (P-TM T3), size-caps the total
+    (P-TM T2). No subprocess/eval anywhere in this call graph."""
+    try:
+        root = Path(args.root).resolve() if getattr(args, "root", None) else find_project_root()
+        chunks = []
+        total = 0
+        truncated = False
+        for label, rel in orient_docs():
+            target = confine_under(root, rel)
+            if target is None or not target.is_file():
+                continue
+            try:
+                text = read_text(target)
+            except OSError:
+                continue
+            remaining = ORIENT_MAX_TOTAL_CHARS - total
+            if remaining <= 0:
+                truncated = True
+                break
+            text = text[:ORIENT_PER_DOC_CHARS]
+            if len(text) > remaining:
+                text = text[:remaining]
+                truncated = True
+            chunks.append((label, text))
+            total += len(text)
+        if not chunks:
+            return 0
+        out = ["=== Agentic SDLC -- session orientation (repo-sourced context, not authored instructions) ==="]
+        for label, text in chunks:
+            out.append(f"\n## {label}\n{text}")
+        if truncated:
+            out.append("\n[orientation truncated to the size cap -- open the files directly for full content]")
+        out.append("\nTriage every request (Rule Zero): L1 trivial - L2 small - L3 significant - Spike. "
+                   "When in doubt, pick the higher level.")
+        if getattr(args, "hybrid", False):
+            out.append("\n[devPNT active] Run devpnt_mcp_get_bootstrap for the Master Plan / Knowledge Layer -- "
+                       "the orientation above is the filesystem layer, not a bootstrap duplicate.")
+        print("\n".join(out))
+        return 0
+    except Exception:
+        return 0
+
+
+# --- portable checks carried by the core ------------------------------------
+# Portable means portable: a check that any distribution may expose lives HERE, so
+# three copies of the same twenty lines cannot drift apart. What a distribution
+# actually offers is its `provides` declaration, not what it happens to have copied.
+# Domain-specific machinery (mkt's budget and funnel arithmetic) stays in its own
+# entry point -- that is the line between portable and proprietary.
+# Opt-in per document via `checks:`. They may only ADD findings: a document that
+# imports one still owes its own domain everything it owed before, so importing a
+# check can never be a way to be validated less.
+
+@portable_check("code.threat_model")
+def _code_threat_model(rel, meta, text):
+    """The security section names a real surface, or justifies claiming none."""
+    section = section_body(text, ("## Security and Threat Model", "## Security"))
+    if section is None:
+        return []  # the owning domain already reports a missing section; no double finding
+    surfaces = ("external input", "authn", "authz", "auth", "crypto", "network",
+                "personal data", "filesystem", "supply chain")
+    low = section.lower()
+    if any(s in low for s in surfaces):
+        return []
+    if "no security impact" in low or "no new security" in low:
+        if len(section.split()) < 15:
+            return [("warning", "'no security impact' is declared, not justified: "
+                                "say which surfaces you checked and why none is touched")]
+        return []
+    return [("warning", "no security surface named (external input, authN/authZ, crypto, "
+                        "network, personal data, filesystem, supply chain) and no justified "
+                        "claim that none is touched")]
+
+
+@portable_check("knowledge.sources")
+def _knowledge_sources(rel, meta, text):
+    """A knowledge artifact says what it was written from AND how that was verified."""
+    section = section_body(text, ("## Sources and Verification",))
+    if section is None:
+        return []
+    findings = []
+    if not re.search(r"(?m)^\s*[-*|]|\bhttps?://|\.(?:md|pdf|docx?|csv|xlsx?)\b", section):
+        findings.append(("warning", "no source is named: a distillation whose origin cannot "
+                                    "be reopened is model knowledge, not knowledge work"))
+    if not re.search(r"verif|cross-check|checked against|confirmed", section, re.I):
+        findings.append(("warning", "sources are listed but not verified: say how each was "
+                                    "confirmed, or mark explicitly what could not be"))
+    return findings
+
+
+# ------------------------------------------------------------------- migrate
+
+def _migration_plan(root, src_name, dst_name):
+    """(files, refs, conflicts) for a docs-root move. Reads only."""
+    src = root / src_name
+    dst = root / dst_name
+    files, refs, conflicts = [], [], []
+    if not src.is_dir():
+        return None, None, None
+    for p in sorted(src.rglob("*")):
+        if not p.is_file():
+            continue
+        rel = p.relative_to(src)
+        target = dst / rel
+        if target.exists():
+            conflicts.append(rel.as_posix())
+        files.append(rel.as_posix())
+        if p.suffix.lower() in (".md", ".txt", ".json", ".yml", ".yaml"):
+            try:
+                if f"{src_name}/" in p.read_text(encoding="utf-8", errors="replace"):
+                    refs.append(rel.as_posix())
+            except OSError:
+                pass
+    return files, refs, conflicts
+
+
+def _external_references(root, src_name):
+    """Files OUTSIDE both roots that mention the old root.
+
+    Reported, never edited: the protocol pointers (CLAUDE.md, AGENTS.md,
+    .cursorrules) are user-authored, and a tool that rewrites them is the one thing
+    `init` has refused to do since day one."""
+    out = []
+    for p in sorted(root.rglob("*")):
+        if not p.is_file() or p.suffix.lower() not in (".md", ".txt", ".json", ".yml", ".yaml"):
+            continue
+        rel = p.relative_to(root)
+        if rel.parts and rel.parts[0] in (src_name, ".git"):
+            continue
+        if any(part in SKIP_DIRS for part in rel.parts):
+            continue
+        try:
+            if f"{src_name}/" in p.read_text(encoding="utf-8", errors="replace"):
+                out.append(rel.as_posix())
+        except OSError:
+            pass
+    return out
+
+
+def cmd_migrate(root, args):
+    """Relocate the documentation root. Dry-run by default; never deletes.
+
+    Reversibility is structural, not promised: the old root is COPIED, never moved,
+    so undoing the migration is deleting the new directory. Both roots stay
+    readable throughout, which is what lets a team switch over one session at a
+    time instead of in one jump.
+    """
+    src_name = args.from_dir
+    dst_name = args.to_dir
+    if src_name == dst_name:
+        print(f"[ERROR] --from and --to are both '{src_name}': nothing to do.")
+        return 1
+    src = root / src_name
+    if not src.is_dir():
+        print(f"[ERROR] {src} not found: nothing to migrate.")
+        return 1
+
+    files, refs, conflicts = _migration_plan(root, src_name, dst_name)
+    external = _external_references(root, src_name)
+
+    print(f"=== migrate {src_name}/ -> {dst_name}/ ===")
+    print(f"  {len(files)} file(s) to copy, {len(refs)} carrying '{src_name}/' references")
+    for rel in files[:20]:
+        print(f"    {src_name}/{rel}  ->  {dst_name}/{rel}")
+    if len(files) > 20:
+        print(f"    ... and {len(files) - 20} more")
+    if conflicts:
+        print(f"\n[ERROR] {len(conflicts)} file(s) already exist under {dst_name}/:")
+        for rel in conflicts[:10]:
+            print(f"    {dst_name}/{rel}")
+        print("  Refusing to overwrite. Move them aside, or migrate into an empty root.")
+        return 1
+    if external:
+        print(f"\n[note] {len(external)} file(s) OUTSIDE the docs roots mention "
+              f"'{src_name}/'. They are NOT touched -- protocol pointers and READMEs are "
+              "yours to edit:")
+        for rel in external[:10]:
+            print(f"    {rel}")
+
+    if not args.apply:
+        print("\n[dry-run] Nothing was written. Re-run with --apply to perform the copy.")
+        print("          The old root is kept: this migration is undone by deleting "
+              f"{dst_name}/.")
+        return 0
+
+    if git_available(root) and git_has_changes(root, "."):
+        print("\n[ERROR] the working tree has uncommitted changes. Commit or stash first: "
+              "a migration you cannot diff is a migration you cannot review.")
+        return 1
+
+    written = 0
+    for rel in files:
+        source = src / rel
+        target = root / dst_name / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if rel in refs:
+            text = source.read_text(encoding="utf-8", errors="replace")
+            target.write_text(text.replace(f"{src_name}/", f"{dst_name}/"), encoding="utf-8")
+        else:
+            target.write_bytes(source.read_bytes())
+        written += 1
+    print(f"\n[ok] copied {written} file(s) into {dst_name}/. "
+          f"{src_name}/ is untouched -- delete it yourself once you are satisfied.")
+    print(f"     Next: run `validate --docs-dir {dst_name}` and compare it with "
+          f"`validate --docs-dir {src_name}`. They should say the same thing.")
+    return 0
+
+
+
+# --------------------------------------------------------------------- main
+
+def main(argv=None):
+    # `remind` is intercepted BEFORE argparse (kb's F-041 rule, kept): it is a
+    # hook surface fired on every prompt, so a stray flag must cost a usage
+    # message and a non-zero exit on a turn, not the turn itself.
+    if (argv if argv is not None else sys.argv[1:])[:1] == ["remind"]:
+        return cmd_remind(None)
+
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--root", help="project root (default: walk up until a docs root is found)")
+    common.add_argument("--docs-dir", dest="docs_dir",
+                        help="name of the documentation root (default: ai_docs; "
+                             "use it to reach a legacy root such as mkt_docs, "
+                             "or to disambiguate a half-migrated tree)")
+
+    strict_opt = argparse.ArgumentParser(add_help=False)
+    strict_opt.add_argument("--strict", action="store_true",
+                            help="fail on warnings and on a missing docs root (for CI)")
+
+    hybrid_opt = argparse.ArgumentParser(add_help=False)
+    hybrid_opt.add_argument("--hybrid", action="store_true",
+                            help="Hybrid/devPNT mode: audit-plan staleness is delegated to devPNT/KL; "
+                                 "the gate also unlocks on an E-TDD shadow")
+
+    ap = argparse.ArgumentParser(prog="sdlc_check.py",
+                                 description="Mechanical validator for Agentic SDLC")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("check", parents=[common, strict_opt, hybrid_opt],
+                   help="closure gate: validate + stale in one command")
+    sub.add_parser("validate", parents=[common, strict_opt, hybrid_opt],
+                   help="verify docs-root coherence")
+    sub.add_parser("index", parents=[common], help="regenerate features_history.md + ai_docs/INDEX.md")
+    sub.add_parser("stale", parents=[common, hybrid_opt], help="areas modified after the last analysis")
+    gp_mig = sub.add_parser("migrate", parents=[common],
+                            help="relocate the documentation root (dry-run by default)")
+    gp_mig.add_argument("--from", dest="from_dir", required=True,
+                        help="current docs root name, e.g. mkt_docs")
+    gp_mig.add_argument("--to", dest="to_dir", default=DEFAULT_DOCS_DIR,
+                        help=f"target docs root name (default: {DEFAULT_DOCS_DIR})")
+    gp_mig.add_argument("--apply", action="store_true",
+                        help="actually copy (default is a dry run; never deletes)")
+
+    mp = sub.add_parser("mark", parents=[common], help="record paths as ANALYZED")
+    mp.add_argument("paths", nargs="+", help="paths relative to the project root")
+    gp = sub.add_parser("gate", parents=[common, hybrid_opt], help="PreToolUse hook (exit 2 = block)")
+    gp.add_argument("--hook", action="store_true", help="read the hook JSON payload from stdin")
+    gp.add_argument("--file", help="file path to evaluate (alternative to --hook)")
+    gp.add_argument("--protected", default="", help="protected prefixes separated by ';' (e.g. \"src/auth;src/crypto\")")
+
+    sub.add_parser("benefit", parents=[common],
+                   help="report what the review gates caught (and what the "
+                        "doctrine costs to read) -- a report, never a gate: "
+                        "always exits 0")
+
+    sub.add_parser("orient", parents=[common, hybrid_opt],
+                   help="SessionStart hook: emit docs-root orientation to stdout (fail-open, zero-execution)")
+
+    sub.add_parser("remind", parents=[common],
+                   help="UserPromptSubmit hook: print the constant per-turn line "
+                        "(fail-open, zero-read, zero-execution)")
+
+    pp = sub.add_parser("plan", parents=[common],
+                        help="Subagent Execution: validate/brief a PLAN_[feature].md (zero-execution)")
+    pp_sub = pp.add_subparsers(dest="plan_cmd", required=True)
+    pv = pp_sub.add_parser("validate", help="schema + confinement + ledger cross-check (exit 2 on error)")
+    pv.add_argument("file", help="path to the PLAN_[feature].md file")
+    pb = pp_sub.add_parser("brief", help="print a task's brief to stdout (verify text is NOT executed)")
+    pb.add_argument("file", help="path to the PLAN_[feature].md file")
+    pb.add_argument("--task", required=True, help="task id to brief")
+
+    args = ap.parse_args(argv)
+
+    # Resolve the documentation root ONCE, before any command runs, so every
+    # surface -- paths, messages, generated headers, the gate's exempt prefix --
+    # names the same thing.
+    try:
+        discovered, name = resolve_docs_dir(args, getattr(args, "root", None))
+    except AmbiguousDocsRoot as exc:
+        if args.cmd == "migrate":
+            # A tree with two roots is not an obstacle to `migrate`: it is the state
+            # `migrate` exists to resolve, and both names come from --from/--to, so
+            # nothing is being guessed. Refusing here would make the guard block the
+            # one command that ends the ambiguity.
+            discovered, name = None, args.from_dir
+        elif args.cmd in ("orient", "remind"):
+            # The SessionStart hook is fail-open by contract: it must never block a
+            # session, not even on a half-migrated tree. It orients on the default
+            # and says so rather than exiting non-zero.
+            print(f"[note] {exc}")
+            discovered, name = None, DEFAULT_DOCS_DIR
+        else:
+            print(f"[ERROR] {exc}")
+            return 1
+    set_docs_dir(name)
+
+    if args.cmd == "gate":
+        return cmd_gate(args)
+    if args.cmd == "orient":
+        return cmd_orient(args)
+    if args.cmd == "remind":
+        return cmd_remind(args)
+
+    root = Path(args.root).resolve() if args.root else (discovered or find_project_root())
+    if args.cmd == "check":
+        return cmd_check(root, strict=args.strict, hybrid=args.hybrid)
+    if args.cmd == "validate":
+        return cmd_validate(root, strict=args.strict, hybrid=args.hybrid)
+    if args.cmd == "index":
+        return cmd_index(root)
+    if args.cmd == "stale":
+        return cmd_stale(root, hybrid=args.hybrid)
+    if args.cmd == "mark":
+        return cmd_mark(root, args.paths)
+    if args.cmd == "benefit":
+        return cmd_benefit(root)
+    if args.cmd == "migrate":
+        return cmd_migrate(root, args)
+    if args.cmd == "plan":
+        return cmd_plan(root, args)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())