@antoneeo/mkt-agentic-sdlc-skill 0.23.0 → 0.26.0

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

@@ -21,6 +21,8 @@ Commands:
   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)
+  verdict    PreToolUse hook: refuse an edit when the session declared no guide-router
+             verdict, or never read a guide it names (JSON deny on stdout; always exit 0)
 
 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
@@ -94,6 +96,10 @@ DESIGN_REVIEW_EPOCH = "2026-07-28"
 # like the two gates above: a fixed epoch cannot protect a late upgrader, so a
 # warning here would redden --strict CI on work written before the upgrade.
 CHRONOLOGY_EPOCH = "2026-10-18"
+# Guide check (F-078): an L3 code ANALYSIS started on/after this date owes a
+# filled '## Guide check'. The day AFTER the rule was written, so the analyses
+# opened that day by parallel units (which never saw the template) stay quiet.
+GUIDE_CHECK_EPOCH = "2026-10-24"
 NEXT_MAX_CHARS = 240        # this repository's longest `next:` was 214 at the epoch
 ID_SCAN_MAX_REFS = 300      # A3 is skipped above it (one advisory says so, T9)
 ID_SCAN_REFS_PER_CALL = 50  # keeps one git command line far below 32k chars
@@ -396,8 +402,17 @@ def orient_docs():
         ("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
+# F-075: the WHOLE output -- the knowledge layer's append included -- stays under
+# Claude Code's 10,000-character hook cap. Above it the client saves the output
+# to a file and injects a 2,000-character preview, and the agent never opens the
+# file: the router printed third, after README and INDEX, never reached a session.
+ORIENT_MAX_TOTAL_CHARS = 9500   # whole output (P-TM T2)
+ORIENT_APPEND_RESERVE = 2000    # left for the knowledge layer's append, which cuts itself to it
+ORIENT_ROUTER_CHARS = 3000      # ~20 guides; the full router stays one read away
+ORIENT_REGISTRY_CHARS = 2600    # registry rows + project-wide notes
+ORIENT_TRIAGE_LINE = ("Triage every request (Rule Zero): L1 trivial - L2 small - L3 significant "
+                      "- Spike. Declare the level with the guide-router verdict (a guide below, "
+                      "or \"no match\"). When in doubt, pick the higher level.")
 
 
 # ----------------------------------------------------------------- utilities
@@ -524,6 +539,41 @@ def has_etdd_shadow(root):
     return any("tdd" in p.name.lower() for p in sol.glob("SHADOW_*.md"))
 
 
+def newest_shadow(solutions_dir, doc_key):
+    """The newest devPNT shadow of `doc_key` in `solutions_dir`, or None.
+    Only `SHADOW_<doc_key>_v<N>[.<N>...].md` counts -- the exact key, so
+    `<doc_key>_extra` is another key -- and versions compare number by number
+    (v1.10 above v1.9, v1.0 above v1). Names outside that rule are ignored.
+    F-081: the Hybrid target of a claim marker; reusable by any consumer."""
+    if not Path(solutions_dir).is_dir():
+        return None
+    best = None
+    for p in Path(solutions_dir).iterdir():
+        v = _shadow_version(p.name, doc_key)
+        if v is not None and p.is_file():
+            if best is None or v > best[0]:
+                best = (v, p)
+    return best[1] if best else None
+
+
+def _shadow_version(name, doc_key):
+    """The version tuple of `SHADOW_<doc_key>_v<N>[.<N>...].md`, else None."""
+    m = re.match(r"^SHADOW_%s_v(\d+(?:\.\d+)*)\.md$" % re.escape(doc_key), name)
+    return tuple(int(x) for x in m.group(1).split(".")) if m else None
+
+
+def stray_shadow(solutions_dir, doc_key):
+    """A file of the same exact key that `newest_shadow` does not read
+    (`SHADOW_<doc_key>.md`, `..._v1.2a.md`), or None -- the name a user needs
+    to see when no shadow resolves. A longer key is never a stray."""
+    if not Path(solutions_dir).is_dir():
+        return None
+    rx = re.compile(r"^SHADOW_%s(?:_v[^_]*)?\.md$" % re.escape(doc_key))
+    return next((p.name for p in sorted(Path(solutions_dir).iterdir())
+                 if rx.match(p.name) and _shadow_version(p.name, doc_key) is None),
+                None)
+
+
 def iter_files(target):
     if target.is_file():
         yield target
@@ -870,10 +920,10 @@ 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) <= {"|", "-", " ", ":"}:
+        cells = _table_cells(line)
+        if not cells:
             continue
-        first = s.strip("|").split("|")[0].strip()
+        first = cells[0]
         if first and first.lower() != "workstream":
             ids.append(first)
     return ids
@@ -1169,6 +1219,20 @@ def _opener_at(lines, i):
     return None
 
 
+def malformed_openers(body):
+    """[(line, text)] -- dated openers whose bold does not pair: `**DATE …` with no
+    closing `**` on the line, or a bare `DATE …` that closes one. Either way the
+    chronology shows a label running into the entry's body (field case 2026-10-19:
+    two release notes in project_notes.md)."""
+    lines = _blank_comments(body).splitlines()
+    out = []
+    for i in range(len(lines)):
+        m = _opener_at(lines, i)
+        if m and bool(m.group(3)) != ("**" in m.group(5)):
+            out.append((i + 1, lines[i]))
+    return out
+
+
 def entry_openers(body):
     """[(date, label, line)] -- one per dated entry opener; line is 1-based
     within `body`. An undated paragraph belongs to the entry above it. Comments
@@ -1267,6 +1331,11 @@ def chronology_advisories(root):
         if len(nxt) > NEXT_MAX_CHARS:
             out.append(f"audit/{p.name}: next: is {len(nxt)} chars (> {NEXT_MAX_CHARS}): one "
                        "next step here, the state goes to the Diary as a dated entry")
+    notes = ai_path(root, "audit", PROJECT_NOTES)
+    if notes.is_file():
+        for n, t in malformed_openers(read_text(notes)):
+            out.append(f"audit/{PROJECT_NOTES}: line {n}: dated entry '{t[:60]}' has unpaired "
+                       "bold -- open entries with **YYYY-MM-DD — label.**")
     return out
 
 
@@ -1454,10 +1523,30 @@ def has_ledger_heading(text):
     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."""
+    return bool(re.search(r"^##[ \t]+Capability Ledger[ \t]*$", strip_non_prose(text), re.M))
+
+
+def strip_non_prose(text):
+    """Text without fenced code blocks and HTML comments (see has_ledger_heading)."""
     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))
+    return re.sub(r"^[ \t]*<!--(?!.*?-->).*\Z", "", stripped, flags=re.M | re.S)
+
+
+def has_guide_check(text):
+    """True when a real '## Guide check' heading carries an answer: the template's
+    comment alone answers nothing, so a copied-but-unfilled section still owes it."""
+    m = re.search(r"^##[ \t]+Guide check[ \t]*$(.*?)(?=^#{1,2}[ \t]|\Z)",
+                  strip_non_prose(text), re.M | re.S)
+    return bool(m and m.group(1).strip())
+
+
+def guide_check_due(meta, domain):
+    """True when an ANALYSIS owes the Phase-3 guide question (SKILL.md): a code-lens
+    L3 started on/after GUIDE_CHECK_EPOCH. Same grandfathering as ledger_due."""
+    return domain == "code" and ledger_due(meta) and (
+        parse_iso((meta.get("start_date") or "").strip().strip("'\""))
+        >= parse_iso(GUIDE_CHECK_EPOCH))
 
 
 def ledger_due(meta):
@@ -1706,6 +1795,10 @@ def cmd_validate(root, strict=False, hybrid=False):
         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")
+        if guide_check_due(meta, domain) and not has_guide_check(text):
+            advisories.append(f"{rel}: L3 without a filled '## Guide check' -- does a CURRENT "
+                              "guide cover what this touches, and did understanding it force "
+                              "a model of a complex component no guide covers (guides.md, section 1)?")
 
     # Generated index aligned
     hist = ai / "strategic" / "features_history.md"
@@ -2001,7 +2094,8 @@ def cmd_stale(root, hybrid=False):
                     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]
+        docs_rel = docs_root_rel(root)
+        changed = [c for c in changed if c != plan_rel and not _in_docs_root(c, docs_rel)]
         if changed:
             stale.append((rel, changed))
 
@@ -2022,9 +2116,54 @@ def cmd_stale(root, hybrid=False):
     return 1                                       # stale areas dominate: rc already implied
 
 
-def cmd_mark(root, paths):
+def add_dated_note(root, note, day=None):
+    """Write `**DAY — note.**` into audit/project_notes.md, above the newest dated
+    entry (below any undated preface), so the note opens with the shared grammar and
+    the chronology reads it. The day defaults to today (local)."""
+    import datetime as _dt
+    day = day or _dt.date.today().isoformat()
+    entry = "**%s — %s.**" % (day, note.strip().rstrip("."))
+    f = ai_path(root, "audit", PROJECT_NOTES)
+    if not f.is_file():
+        f.parent.mkdir(parents=True, exist_ok=True)
+        f.write_text(entry + "\n", encoding="utf-8")
+        return entry
+    raw = f.read_bytes()
+    crlf = b"\r\n" in raw
+    lines = raw.decode("utf-8", errors="replace").replace("\r\n", "\n").split("\n")
+    at = next((i for i in range(len(lines)) if _opener_at(lines, i)), None)
+    if at is None:
+        while lines and not lines[-1].strip():
+            lines.pop()
+        lines += ["", entry, ""] if lines else [entry, ""]
+    else:
+        lines[at:at] = [entry, ""]
+    text = "\n".join(lines)
+    f.write_bytes((text.replace("\n", "\r\n") if crlf else text).encode("utf-8"))
+    return entry
+
+
+def docs_root_rel(root):
+    """The docs root (ai_docs/, mkt_docs/ ...) relative to the project root, or None.
+    It is governance, not an analyzable area: `validate` checks it directly, so `stale`
+    never counts its files and `mark` never records it."""
+    try:
+        return ai_path(root).resolve().relative_to(Path(root).resolve()).as_posix()
+    except ValueError:
+        return None
+
+
+def _in_docs_root(rel, docs_rel):
+    rel = rel.replace("\\", "/").rstrip("/")
+    return bool(docs_rel) and (rel == docs_rel or rel.startswith(docs_rel + "/"))
+
+
+def cmd_mark(root, paths, note=None):
     if not require_ai_docs(root, "mark"):
         return 1
+    if note is not None and (not note.strip() or "**" in note or "\n" in note):
+        print("[ERROR] --note must be one line of text without '**'. Nothing was written.")
+        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
@@ -2051,6 +2190,10 @@ def cmd_mark(root, paths):
                   "refusing to mark (use a project-relative path, '.' for the root). "
                   "Nothing was written.")
             return 1
+        if _in_docs_root(key, docs_root_rel(root)):
+            print(f"[note] {raw}: the docs root is not an area to mark -- `validate` checks it "
+                  "directly. Skipped.")
+            continue
         keys.append(key)
 
     appended = []
@@ -2070,6 +2213,13 @@ def cmd_mark(root, paths):
 
     f.parent.mkdir(parents=True, exist_ok=True)
     f.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    if note is not None:
+        print(f"[ok] dated entry added to audit/{PROJECT_NOTES}: {add_dated_note(root, note)}")
+    elif not _open_units(root):
+        # no open unit's Diary covers this work: a release, a fix after closure
+        print(f"[note] no open unit records this work. If it is a release or a change worth "
+              f"finding later, re-run with --note \"<what was done>\": mark writes the "
+              f"dated entry in audit/{PROJECT_NOTES} for you.")
     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.
@@ -2149,15 +2299,56 @@ def _orient_user_settings_path():
 
 
 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 --
+    """Yield (command, at_user_level, place) 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."""
+    projects would read as unwired forever. `place` is a display label, never a
+    home path (F-075 prints it)."""
     for rel in ORIENT_HOOK_CONFIG_FILES:
         for cmd in _orient_entries_in(Path(root) / rel):
-            yield cmd, False
+            yield cmd, False, rel
     for cmd in _orient_entries_in(_orient_user_settings_path()):
-        yield cmd, True
+        yield cmd, True, "user settings"
+
+
+def _orient_entry_live(root, cmd, at_user_level):
+    """True unless the entry names a validator that does not resolve.
+
+    A matching entry whose tokens name no validator is "cannot tell" and counts
+    as live (the lib.js contract: never report broken on cannot-tell). 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."""
+    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 True
+    tp = Path(token)
+    if not tp.is_absolute():
+        if at_user_level:
+            return True
+        tp = Path(root) / tp
+    return tp.exists()
+
+
+def orient_wiring(root):
+    """{client: {command: place}} for the LIVE orient entries, per client.
+
+    Per client because two clients never read each other's settings: a Codex
+    entry beside a Claude Code one is two clients oriented once each, not one
+    session oriented twice. Identical command strings count once. A dead entry
+    delivers no copy and is left out (F-075 FS3)."""
+    out = {}
+    for cmd, at_user_level, place in _orient_hook_commands(root):
+        if not _orient_entry_live(root, cmd, at_user_level):
+            continue
+        client = "codex" if place.startswith(".codex") else "claude"
+        out.setdefault(client, {}).setdefault(cmd.strip(), place)
+    return out
 
 
 def orient_hook_state(root):
@@ -2172,22 +2363,9 @@ def orient_hook_state(root):
     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):
+    for cmd, at_user_level, _place 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():
+        if _orient_entry_live(root, cmd, at_user_level):
             return "wired"
     return "dead" if matched else "unwired"
 
@@ -2269,6 +2447,12 @@ REMIND_FALLBACK = (
 )
 
 
+# F-075: constant, for every lens -- with sibling lenses installed nothing per
+# turn said to choose the lens. r19's bound rose to 600 for it (r32, owner).
+REMIND_LENS_SUFFIX = (" Above L1, with sibling lenses installed: choose the lens with "
+                      "routing.md and declare it.")
+
+
 def cmd_remind(args):
     """UserPromptSubmit hook: print the lens's constant per-turn line. Always 0.
 
@@ -2277,21 +2461,31 @@ def cmd_remind(args):
     try:
         prof = profile()
         line = prof.get("remind_line") or REMIND_FALLBACK.format(skill=prof["skill_name"])
-        print(f"{prof['skill_name']}: {line}")
+        print(f"{prof['skill_name']}: {line}{REMIND_LENS_SUFFIX}")
     except Exception:
         pass
     return 0
 
+def read_hook_payload():
+    """The hook event JSON on stdin as a dict, or None when it cannot be read.
+
+    bytes -> utf-8-sig: the payload is UTF-8 JSON regardless of the console code
+    page; '-sig' strips the BOM (PowerShell pipes)."""
+    try:
+        raw = sys.stdin.buffer.read().decode("utf-8-sig", errors="replace")
+        payload = json.loads(raw)
+    except Exception:
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
 def cmd_gate(args):
     file_path = args.file or ""
     if args.hook:
+        payload = read_hook_payload()
         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:
+        except AttributeError:
             return 0  # unparseable input: do not block
     if not file_path:
         return 0
@@ -2326,6 +2520,134 @@ def cmd_gate(args):
     return 2
 
 
+# ------------------------------------------------------------------ verdict
+# F-076: Rule Zero's router verdict, checked at the edit. A field agent edited
+# without declaring one and said nothing stopped it. This reads the session
+# transcript the client hands every hook and refuses the edit (JSON deny, exit
+# 0) only on certainty; whatever it cannot tell resolves to silence. It never
+# prints `allow` -- that would skip the user's permission prompt. Owner: block
+# (REQUEST_guide_verdict_check.md R3), wired by default (R4, rulings.md r34).
+
+VERDICT_EDIT_TOOLS = ("Edit", "Write", "MultiEdit", "NotebookEdit")
+VERDICT_MAX_BYTES = 256 * 1024 * 1024  # a larger transcript: cannot afford to tell
+VERDICT_LINE_MAX = 1024 * 1024         # assistant lines are small; skip the rest unparsed
+# Markdown emphasis between the word and the colon ("**router**: no match") and
+# "Router verdict:" are the same declaration: format drift resolves to silence.
+_VERDICT_ROUTER_RE = re.compile(r"router(?:[\s*_`]+verdict)?[\s*_`]*:(.*)", re.IGNORECASE)
+_VERDICT_NONE_RE = re.compile(r"[\s`*_\"'(]*(no match|absent)", re.IGNORECASE)
+_VERDICT_TRIVIAL_RE = re.compile(r"\blevel[\s*_`]*:[\s`*_]*[A-Z]1\b", re.IGNORECASE)
+_GUIDE_NAME_RE = re.compile(r"GUIDE_[A-Za-z0-9_-]+\.md")
+
+
+def transcript_facts(path):
+    """What the session transcript shows about the verdict duty, or None when it
+    cannot be read within the bounds.
+
+    Returns {"assistant": entries parsed, "sidechain": a subagent's own transcript
+    (Claude Code marks every entry of one `isSidechain`), "declared": a router verdict seen,
+    "trivial": a `Level: X1` seen, "named": guides the verdicts name,
+    "read": guide names that appeared in a non-edit tool's input}."""
+    facts = {"assistant": 0, "sidechain": False, "declared": False, "trivial": False,
+             "named": set(), "read": set()}
+    try:
+        p = Path(path)
+        if not p.is_file() or p.stat().st_size > VERDICT_MAX_BYTES:
+            return None
+        with p.open("rb") as fh:
+            for raw in fh:
+                if len(raw) > VERDICT_LINE_MAX or b'"assistant"' not in raw:
+                    continue
+                try:
+                    entry = json.loads(raw.decode("utf-8", errors="replace"))
+                except ValueError:
+                    continue
+                if not isinstance(entry, dict) or entry.get("type") != "assistant":
+                    continue
+                content = (entry.get("message") or {}).get("content")
+                if not isinstance(content, list):
+                    continue
+                facts["assistant"] += 1
+                if entry.get("isSidechain") is True:
+                    facts["sidechain"] = True
+                for block in content:
+                    if not isinstance(block, dict):
+                        continue
+                    if block.get("type") == "text":
+                        for line in str(block.get("text") or "").splitlines():
+                            if _VERDICT_TRIVIAL_RE.search(line):
+                                facts["trivial"] = True
+                            m = _VERDICT_ROUTER_RE.search(line)
+                            if m:
+                                facts["declared"] = True
+                                if not _VERDICT_NONE_RE.match(m.group(1)):
+                                    facts["named"].update(_GUIDE_NAME_RE.findall(m.group(1)))
+                    elif (block.get("type") == "tool_use"
+                          and block.get("name") not in VERDICT_EDIT_TOOLS):
+                        facts["read"].update(_GUIDE_NAME_RE.findall(
+                            json.dumps(block.get("input"), ensure_ascii=False)))
+    except (OSError, ValueError, TypeError, AttributeError):
+        return None
+    return facts
+
+
+def verdict_reason(payload, root):
+    """The refusal line for this edit event, or None when the edit may proceed."""
+    if payload.get("tool_name") not in VERDICT_EDIT_TOOLS or payload.get("agent_id"):
+        return None
+    tool_input = payload.get("tool_input") or {}
+    target = tool_input.get("file_path") or tool_input.get("notebook_path")
+    transcript = payload.get("transcript_path")
+    if not target or not transcript:
+        return None
+    try:
+        Path(target).resolve().relative_to(root)
+    except (ValueError, OSError):
+        return None  # outside the project: not this check's concern
+    ref = ai_path(root, "reference")
+    if not ref.is_dir():
+        return None
+    guides = {g.name for g in ref.glob("GUIDE_*.md") if g.is_file()}
+    if not guides:
+        return None
+    facts = transcript_facts(transcript)
+    if not facts or not facts["assistant"]:
+        return None  # unreadable, oversized or an unknown format: cannot tell
+    if facts["sidechain"]:
+        return None  # a subagent works under its orchestrator's verdict
+    if not (facts["declared"] or facts["trivial"]):
+        return ("[sdlc verdict] No guide-router verdict in this session; this project has "
+                f"guides ({docs_dir()}/reference/INDEX.md). Declare it with the level, e.g. "
+                "\"Level: L2 · router: no match\" or \"router: GUIDE_x.md -> read\" "
+                "(L1: \"Level: L1\"), then retry.")
+    unread = sorted((facts["named"] & guides) - facts["read"])
+    if unread:
+        return (f"[sdlc verdict] The router verdict names {', '.join(unread)}, not read in "
+                "this session. Read it, then retry.")
+    return None
+
+
+def cmd_verdict(args):
+    """PreToolUse hook: print a JSON refusal or nothing. Always 0 -- exit 2 would
+    block blind, and the wired command adds `; exit 0` for validators that cannot
+    run this at all (missing, or older than it)."""
+    if not args.hook:
+        return 0
+    try:
+        payload = read_hook_payload()
+        if payload is None:
+            return 0
+        root = Path(args.root).resolve() if args.root else find_project_root()
+        reason = verdict_reason(payload, root)
+        if reason:
+            print(json.dumps({"hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": reason}}, ensure_ascii=False))
+    except Exception:
+        pass
+    return 0
+
+
 # --------------------------------------------------------------------- plan
 # Subagent Execution (Feature A). Zero-execution surface: this section and
 # everything it calls MUST NOT spawn a process (no subprocess/os.system/eval/
@@ -2525,15 +2847,23 @@ REVIEW_POSITIONAL = {
 }
 
 
+_UNESCAPED_PIPE_RE = re.compile(r"(?<!\\)\|")
+
+
 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."""
+    Separator rows (---, :---:, any alignment colons) are not data. A cell may
+    carry an escaped pipe (`\\|`, as `index` writes them): it does not split the
+    row, and it reads back as `|` (F-075)."""
     s = line.strip()
     if not s.startswith("|"):
         return None
     if set(s) <= set("|-: "):
         return None
-    return [c.strip() for c in s.strip("|").split("|")]
+    body = s[1:]
+    if body.endswith("|") and not body.endswith("\\|"):
+        body = body[:-1]
+    return [c.strip().replace("\\|", "|") for c in _UNESCAPED_PIPE_RE.split(body)]
 
 
 def parse_review_log(text):
@@ -2741,48 +3071,205 @@ def cmd_benefit(root):
     return 0
 
 
+# --- orient helpers (F-075) ---------------------------------------------------
+SKILL_MD_CAP = 64 * 1024        # a SKILL.md is read for its name only
+
+
+def orient_fit(lines, budget, rel):
+    """The lines that fit `budget` characters (one newline each), cut at a line
+    boundary and closed by a pointer to the file holding the rest. A single line
+    wider than the room left shows its head. Never raises."""
+    out, used = [], 0
+    for i, line in enumerate(lines):
+        if used + len(line) + 1 <= budget:
+            out.append(line)
+            used += len(line) + 1
+            continue
+        rest = len(lines) - i
+
+        def ptr(n):
+            return f"(+{n} more lines -- read {rel})"
+        room = budget - used - len(ptr(rest)) - 1
+        if room > 40:
+            head = line[:room - 4] + "..."
+            out.append(head)
+            used += len(head) + 1
+        while out and used + len(ptr(rest)) + 1 > budget:
+            used -= len(out.pop()) + 1
+            rest += 1
+        out.append(ptr(rest))
+        return out
+    return out
+
+
+def lens_table(skill_dir=None):
+    """{skill_name: lens} from the running skill's own `routing.md` par.0 table.
+
+    The Python twin of lib.js `lensTable()`, same parse: a row whose lens cell is
+    `[a-z]+` and whose skill cell is a backticked `[a-z0-9-]+`. `routing.md` is a
+    byte-identical shared file, so the family list cannot drift between
+    distributions -- a literal list here is how kb and mkt once announced
+    themselves as the code lens. Fail-open: {} on any failure."""
+    try:
+        base = Path(skill_dir) if skill_dir else Path(__file__).resolve().parent.parent
+        table = {}
+        for line in read_text(base / "routing.md").splitlines():
+            cells = [c.strip() for c in line.split("|")]
+            if len(cells) < 4:
+                continue
+            lens, skill = cells[1], cells[2]
+            if re.fullmatch(r"[a-z]+", lens) and re.fullmatch(r"`[a-z0-9-]+`", skill):
+                table.setdefault(skill[1:-1], lens)
+        return table
+    except Exception:
+        return {}
+
+
+def _skills_dirs():
+    """The two places a sibling lens is installed: beside the running skill, and
+    the user's Claude skills directory. AGENTIC_SDLC_SKILLS_DIRS (os.pathsep
+    list; empty = none) is the test seam, like AGENTIC_SDLC_USER_SETTINGS."""
+    seam = os.environ.get("AGENTIC_SDLC_SKILLS_DIRS")
+    if seam is not None:
+        return [Path(s) for s in seam.split(os.pathsep) if s]
+    cfg = os.environ.get("CLAUDE_CONFIG_DIR")
+    return [Path(__file__).resolve().parents[2],
+            (Path(cfg) if cfg else Path.home() / ".claude") / "skills"]
+
+
+def installed_sibling_lenses():
+    """Names of the family's other lenses installed on this machine (sorted).
+
+    Only a name that appears in `lens_table()` AND equals a `SKILL.md` `name:`
+    exactly can come out -- no text of a sibling's files reaches the output
+    (P-TM T3). Fail-open: [] on any failure."""
+    try:
+        own = profile()["skill_name"]
+        family = lens_table()
+        found = set()
+        for base in _skills_dirs():
+            if not base.is_dir():
+                continue
+            for sub in base.iterdir():
+                f = sub / "SKILL.md"
+                try:
+                    if not f.is_file() or f.stat().st_size > SKILL_MD_CAP:
+                        continue
+                    m = re.search(r"^name:\s*(\S+)", read_text(f), re.M)
+                except OSError:
+                    continue
+                if m and m.group(1) in family and m.group(1) != own:
+                    found.add(m.group(1))
+        return sorted(found)
+    except Exception:
+        return []
+
+
+def _orient_router_lines(text):
+    """One line per guide from the generated router; a hand-written one as written."""
+    if not re.search(r"GENERATED by \S+ index - do not edit by hand", text):
+        return text.splitlines()
+    rows = []
+    for line in text.splitlines():
+        cells = _table_cells(line)
+        if not cells or len(cells) < 3 or cells[0] == "Guide":
+            continue
+        rows.append(f"- {cells[0]} ({cells[1]}) -- {cells[2]}")
+    return rows or ['no guides yet -- the router verdict is "no match"']
+
+
+def _orient_registry_lines(text):
+    """One line per workstream plus the project-wide notes from the generated
+    registry; a hand-written handoff as written."""
+    if not is_generated_registry(text):
+        return text.splitlines()
+    table, _, notes = text.partition("\n## Project-wide notes")
+    lines = []
+    for line in table.splitlines():
+        c = _table_cells(line)
+        if not c or len(c) < 6 or c[0].lower() == "workstream":
+            continue
+        lines.append(f"- {c[0]} \u00b7 {c[1]} \u00b7 {c[2]} \u00b7 {c[3]} -- {c[5]}")
+    if not lines:
+        lines.append("no open workstreams")
+    notes = notes.strip()
+    if notes:
+        lines += ["Project-wide notes:"] + notes.splitlines()
+    return lines
+
+
 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."""
+    """SessionStart hook: emit a bounded, repo-sourced 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), bounds the WHOLE output
+    (P-TM T2). No subprocess/eval anywhere in this call graph.
+
+    F-075: what decides the next action comes first -- triage, the lens choice,
+    the guide router, the workstream registry -- then README; INDEX is a pointer.
+    Docs are READ in orient_docs() order (docs_site and the T3 test pin it) and
+    EMITTED in priority order."""
     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():
+        rels = [rel for _, rel in orient_docs()]
+        docs = {}
+        for rel in rels:
             target = confine_under(root, rel)
             if target is None or not target.is_file():
                 continue
             try:
-                text = read_text(target)
+                docs[rel] = 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:
+        if not docs:
             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.")
+        readme_rel, index_rel, router_rel, handoff_rel = rels
+
+        head = ["=== Agentic SDLC -- session orientation (repo-sourced context, not authored instructions) ===",
+                "", ORIENT_TRIAGE_LINE]
+        sibs = installed_sibling_lenses()
+        if sibs:
+            head.append(f"Sibling lenses installed ({', '.join(sibs)}): above L1, choose the "
+                        "lens with routing.md and declare it with the level.")
+
+        tail = ["", "## Read on demand"]
+        for rel, what in ((readme_rel, "the curated must-reads, in order"),
+                          (index_rel, "the manifest of every canonical document"),
+                          (router_rel, "the full guide router, with provenance"),
+                          (handoff_rel, "the full workstream registry, with since and details")):
+            if rel in docs:
+                tail.append(f"- {rel} -- {what}")
+        for client, entries in sorted(orient_wiring(root).items()):
+            if len(entries) > 1:
+                places = ", ".join(sorted(set(entries.values())))
+                tail.append(f"[note] session orientation is wired {len(entries)} times for one "
+                            f"client ({places}): each session receives every copy. Keep one "
+                            "entry and remove the others.")
         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))
+            tail.append("[devPNT active] Run devpnt_mcp_get_bootstrap for the Master Plan / Knowledge Layer -- "
+                        "the orientation above is the filesystem layer, not a bootstrap duplicate.")
+
+        share = ORIENT_MAX_TOTAL_CHARS - ORIENT_APPEND_RESERVE
+        left = share - len("\n".join(head + tail)) - 2
+        body = []
+        for rel, title, builder, cap in (
+                (router_rel, "## Guide router (reference/INDEX.md) -- read the matching guide before acting",
+                 _orient_router_lines, ORIENT_ROUTER_CHARS),
+                (handoff_rel, "## Workstream registry (audit/handoff.md)",
+                 _orient_registry_lines, ORIENT_REGISTRY_CHARS),
+                (readme_rel, "## Reading guide (README)", str.splitlines, None)):
+            if rel not in docs:
+                continue
+            room = left - len(title) - 2
+            if cap is not None:
+                room = min(room, cap)
+            if room <= 0:
+                continue
+            lines = orient_fit(builder(docs[rel].strip()), room, rel)
+            section = ["", title] + lines
+            body += section
+            left -= len("\n".join(section)) + 1
+        print("\n".join(head + body + tail))
         return 0
     except Exception:
         return 0
@@ -2999,11 +3486,18 @@ def main(argv=None):
 
     mp = sub.add_parser("mark", parents=[common], help="record paths as ANALYZED")
     mp.add_argument("paths", nargs="+", help="paths relative to the project root")
+    mp.add_argument("--note", help="also write a dated entry in audit/project_notes.md "
+                                   "(a release, work outside an open unit)")
     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\")")
 
+    vp = sub.add_parser("verdict", parents=[common],
+                        help="PreToolUse hook: refuse an edit with no router verdict "
+                             "or an unread named guide (fail-open, always exit 0)")
+    vp.add_argument("--hook", action="store_true", help="read the hook JSON payload from stdin")
+
     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: "
@@ -3045,6 +3539,10 @@ def main(argv=None):
             # and says so rather than exiting non-zero.
             print(f"[note] {exc}")
             discovered, name = None, DEFAULT_DOCS_DIR
+        elif args.cmd == "verdict":
+            # F-076: a PreToolUse check that cannot tell which root governs refuses
+            # nothing and says nothing -- its stdout is read as the hook's decision.
+            return 0
         else:
             print(f"[ERROR] {exc}")
             return 1
@@ -3052,6 +3550,8 @@ def main(argv=None):
 
     if args.cmd == "gate":
         return cmd_gate(args)
+    if args.cmd == "verdict":
+        return cmd_verdict(args)
     if args.cmd == "orient":
         return cmd_orient(args)
     if args.cmd == "remind":
@@ -3067,7 +3567,7 @@ def main(argv=None):
     if args.cmd == "stale":
         return cmd_stale(root, hybrid=args.hybrid)
     if args.cmd == "mark":
-        return cmd_mark(root, args.paths)
+        return cmd_mark(root, args.paths, args.note)
     if args.cmd == "benefit":
         return cmd_benefit(root)
     if args.cmd == "migrate":