@antoneeo/agentic-sdlc-skill 1.17.0 → 1.19.0

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

@@ -1,10 +1,62 @@
-# Code Review Discipline
+# Review Discipline
 
-Applies at closure of L2/L3 work, and to any independent review slot in this
-skill or in a connected governance layer — devPNT's §4.5/§4.6 review gates,
-and any future review step added to the workflow. This is the single
-definition of how to request, receive, and perform a review; other places
-that need review behavior point here instead of restating it (DRY).
+The single definition of how to request, receive, and perform a review. Other
+places that need review behavior point here instead of restating it (DRY) —
+including devPNT's §4.5/§4.6 gates and any future review step.
+
+## When a review is due
+
+Two moments, and they review different things:
+
+| # | Moment | Object | Level |
+|---|---|---|---|
+| **1. Design review** | End of Phase 3 — **before any implementation** | the ANALYSIS (Standalone) / the `E-ISP`+`E-TDD` (Hybrid) | L3 |
+| **1b. Late arrival** | Work that became L3 *after* code existed — an L1/L2 reclassified mid-flight, or a design increment on a feature already implemented — runs moment 1 **now**, before any further implementation, logged `design (late)` | same | L3 |
+| **2. Closure review** | Phase 5, before DONE | the actual diff, against that approved design | L2 / L3 — the L2 row is optional |
+
+**Why the design review is its own moment, and not a nicety.** The closure review
+can only tell you the code matches the design; it cannot tell you the design was
+wrong. An omission in the design — an impacted file nobody listed, a threat with no
+answering requirement, a capability ruled EXISTS on an assumption — is *cheapest*
+to fix before code exists and most expensive after. And the author cannot catch it:
+a self-review runs in the context that produced the omission and is structurally
+blind to it, which is why independence, not effort, is what this gate buys.
+
+**Independence, best realization the client supports** — declare which one you used:
+
+1. **A fresh subagent** (Claude Code's Task tool, or the equivalent facility) with
+   its own context, given the artifacts below and nothing from this conversation.
+2. **A one-shot run of the client itself** (`gemini -p "…"`, `codex exec "…"`) with
+   a SELF-CONTAINED prompt — the reviewer session has no other context, which is
+   exactly what makes it independent.
+3. **A declared self-pass** — a separate, explicitly adversarial pass by you,
+   against the same checklist. **Rung 3 is illegitimate wherever rung 1 or 2
+   exists**: on a client with a subagent facility or a one-shot CLI, descending to
+   it is choosing zero independence, which is the one thing this gate buys. When
+   you do use it, the log row must carry *why* — `self-pass (declared; no subagent
+   facility on this client)` — not merely that you did. A rung named without its
+   reason is indistinguishable from a rung chosen for convenience.
+
+Rung 3 stays in the ladder deliberately: it is what keeps the methodology
+completable with no network, no account and no subagent facility. It is a floor,
+never a default.
+
+Use a different model from the author's where the client allows it.
+
+**Rounds are capped at 3.** FAIL → revise → re-review. If findings still stand
+after the third, stop and surface them to the user with the artifact — a gate that
+can block forever gets removed. **Log one row per completed review, PASS or FAIL**
+— a FAIL surfaced to the user is the highest-value outcome the gate produces, and
+logging only passes would erase exactly that evidence. The row goes in
+`ai_docs/audit/reviews/REVIEW_LOG.md` (create it if absent — `templates.md`):
+`| date | doc_key | tier | reviewer | findings_raised | findings_real | verdict | revise_rounds |`,
+with `tier` = `design` or `closure` in Standalone. One schema for both modes: a
+Hybrid project's devPNT gates write to the same file.
+The log is how the gate's value is measured over time; skipping it makes the gate
+unfalsifiable, the same defect as an unnamed EXISTS or a faked router verdict.
+
+**The reviewer is read-only and advisory.** It never edits, never commits, never
+marks anything DONE, and a PASS is not an approval to merge — the human owns that.
 
 ## Requesting
 
@@ -13,7 +65,9 @@ When you hand work to a reviewer (human or agent), give them:
 - **Scope**: what changed and why, in one or two lines.
 - **The authoritative design artifact**: the ANALYSIS, E-TDD, or equivalent
   the change was built against — not a paraphrase of it.
-- **The actual diff**: the real changed files, not a description of them.
+- **The actual diff**: the real changed files, not a description of them. (For a
+  **design** review there is no diff yet — that is the point; hand the artifact
+  plus the constraints below, and say the object under review is the design.)
 - **For an impact/solution-analysis review, the constraints it derives from**:
   the **Vision**, including its `## Actors` (Hybrid: the `M-VISION`; Standalone:
   `project_vision.md`/`roadmap.md` + the ANALYSIS Vision-Alignment), the
@@ -71,6 +125,27 @@ When you are the reviewer:
   statement is the proof the check ran; an unfalsifiable "I checked" is the review
   theater this discipline exists to prevent (the reviewer-side twin of §Receiving's
   silent-drop rule). Plain code reviews stay findings-only.
+- **Capability Ledger (same reviews).** **An L3 impact/solution analysis or design
+  that carries NO Capability Ledger is itself a finding** — the architect pass left
+  no record, and "the artifact does not have one" is what a skipped pass looks like,
+  not a reason to skip the check. (This half is load-bearing in Hybrid, where the
+  validator backstop reads Standalone ANALYSIS files only and this clause is the
+  sole check that the pass ran.) When the ledger is there, map each
+  ledger row to where the design or diff realizes it. Three findings live here and
+  nowhere else (`architect.md`): a capability ruled MISSING but implemented inside
+  the feature's code path, with no component owning it; a component whose contract
+  names the feature (a second consumer would force it open); and a capability ruled
+  MISSING, not built, and absorbed by quietly reshaping the feature — that is a
+  scope change owed to the user, not a design detail. An EXISTS row with no named
+  path or symbol is itself a finding. A capability built in this change and absent
+  from the `## Component Map` (`strategic/architecture.md`) is a finding too — and
+  so is **a component the pass merely DISCOVERED and did not write**, especially
+  when the change marks that area ANALYZED: the area now looks read, the map is
+  still silent, and the next feature may lawfully rule the capability MISSING and
+  build it twice. And a **MISSING row in an area `audit/audit_plan.md` does not
+  mark ANALYZED, with no searches named**, is the finding that matters most on a
+  project the methodology arrived in recently — an unread map reported as an empty
+  one is how a duplicate of the existing codebase gets designed.
 
 ## Anti-patterns
 

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

@@ -67,6 +67,24 @@ PLAN_TASK_REQUIRED = ("id", "title", "verify")
 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"
+REVIEW_LOG_REL = "ai_docs/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 = (
@@ -350,9 +368,33 @@ def extract_doc_meta(path):
 
     desc = meta.get("description", "")
     if not desc:
+        in_comment = False
         for line in body:
             s = line.strip()
-            if not s or s.startswith("#") or s.startswith("<!--") or _META_LINE.match(s):
+            # 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()
@@ -491,8 +533,21 @@ def cmd_index(root):
     if guides:
         gidx.write_text(build_guide_index(root), encoding="utf-8")
         print(f"[ok] guide router regenerated: {gidx}")
-    elif gidx.is_file():
-        print(f"[warn]  {gidx} exists but no GUIDE_*.md found: stale router, remove or add guides")
+    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 0
 
 
@@ -502,8 +557,221 @@ def has_section(text, aliases):
     return any(a in text for a in aliases)
 
 
-def cmd_validate(root, strict=False):
-    errors, warnings = [], []
+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 = root / "ai_docs"
     if not ai.is_dir():
         if strict:
@@ -524,7 +792,12 @@ def cmd_validate(root, strict=False):
         if not m:
             errors.append(f"vision/{name}: missing 'Status: DRAFT|APPROVED' in the first lines")
         elif m.group(1) == "DRAFT":
-            warnings.append(f"vision/{name} is DRAFT: not a gating authority, have the user validate it")
+            # 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
     seen_ids = {}
@@ -556,6 +829,28 @@ def cmd_validate(root, strict=False):
         for en, it in ANALYSIS_SECTIONS:
             if not has_section(text, (en, it)):
                 warnings.append(f"{rel}: section '{en}' missing")
+        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
+        # (SKILL.md 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"
@@ -588,6 +883,40 @@ def cmd_validate(root, strict=False):
                         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:
@@ -609,9 +938,20 @@ def cmd_validate(root, strict=False):
     check_kb_collisions(root, guides, errors, warnings)
     # guide-router alignment (mirror of the root-manifest check)
     gidx = root / "ai_docs" / "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("ai_docs/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():
-            errors.append("ai_docs/reference/INDEX.md missing: run 'sdlc_check.py index'")
+            # 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("ai_docs/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("ai_docs/reference/INDEX.md not aligned with the guides: run 'sdlc_check.py index'")
 
@@ -630,11 +970,16 @@ def cmd_validate(root, strict=False):
             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.")
+    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
@@ -699,7 +1044,15 @@ def cmd_stale(root, hybrid=False):
         if row["status"] != "ANALYZED":
             continue
         rel, ref = row["path"], row["ref"]
-        target = root / rel
+        # 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
@@ -718,7 +1071,11 @@ def cmd_stale(root, hybrid=False):
             for fp in iter_files(target):
                 mtime = datetime.fromtimestamp(fp.stat().st_mtime, tz=timezone.utc)
                 if mtime > ts + MTIME_GRACE:
-                    changed.append(str(fp.relative_to(root)).replace("\\", "/"))
+                    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)
         if changed:
             stale.append((rel, changed))
 
@@ -755,10 +1112,21 @@ def cmd_mark(root, paths):
     def row_text(path, note):
         return f"| {path} | ANALYZED | {ref} | {note} |"
 
-    appended = []
+    # 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("/")
-        display = key + ("/" if (root / key).is_dir() else "")
+        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"])
@@ -778,7 +1146,7 @@ def cmd_mark(root, paths):
 
 def cmd_check(root, strict=False, hybrid=False):
     print("===== validate =====")
-    rc_v = cmd_validate(root, strict=strict)
+    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'} "
@@ -827,7 +1195,8 @@ def cmd_gate(args):
         return 2
     sys.stderr.write(
         f"[sdlc gate] '{rel}' is on a protected path but no ANALYSIS_*.md is IN_PROGRESS. "
-        "Create or reactivate the analysis (agentic-sdlc Phase 3) before modifying this file.\n")
+        "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
 
 
@@ -1071,7 +1440,8 @@ def main(argv=None):
     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], help="verify ai_docs/ coherence")
+    sub.add_parser("validate", parents=[common, strict_opt, hybrid_opt],
+                   help="verify ai_docs/ 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")
     mp = sub.add_parser("mark", parents=[common], help="record paths as ANALYZED")
@@ -1103,7 +1473,7 @@ def main(argv=None):
     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)
+        return cmd_validate(root, strict=args.strict, hybrid=args.hybrid)
     if args.cmd == "index":
         return cmd_index(root)
     if args.cmd == "stale":