@antoneeo/mkt-agentic-sdlc-skill 0.23.0 → 0.27.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
@@ -259,6 +265,7 @@ REQUIRED_CAPABILITIES = frozenset({
 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)
+    "preservation_constraints",  # the Impact's P table, and validate's note on its absence (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
@@ -396,8 +403,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,12 +540,55 @@ 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 skip_dir(name):
+    """The one definition of a directory that holds no project files: VCS and
+    dependency/build directories, every dot-directory, and the docs root (by
+    name, at any depth). `iter_files` and the knowledge layer's inventory both
+    walk by it, so the two can never disagree about what the project is."""
+    return name in SKIP_DIRS or name == docs_dir() or name.startswith(".")
+
+
 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(".")]
+        dirnames[:] = [d for d in dirnames if not skip_dir(d)]
         for name in filenames:
             yield Path(dirpath) / name
 
@@ -870,10 +929,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 +1228,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 +1340,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 +1532,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 +1804,22 @@ 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)?")
+        # F-085 FS7: code lens only (R12: the lens, not merely the domain -- a kb
+        # install validating a code-domain unit sees no change), open L3 only, a
+        # note and never an error, so no `--strict` exit changes (P5).
+        impact = section_body(text, IMPACT_SECTION)
+        if (has_capability("preservation_constraints") and domain == "code"
+                and str(level or "").upper() == "L3"
+                and status in ("PLANNED", "IN_PROGRESS")
+                and impact is not None and not has_preservation_record(impact)):
+            advisories.append(f"{rel}: open L3 whose '## Impact' has neither the "
+                              f"'{PRESERVATION_HEADING}' table nor the line "
+                              f"'{NO_SYMBOL_LINE}' -- what existing code must keep "
+                              "doing is not extractable (templates.md)")
 
     # Generated index aligned
     hist = ai / "strategic" / "features_history.md"
@@ -2001,7 +2115,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 +2137,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 +2211,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 +2234,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 +2320,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 +2384,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 +2468,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,25 +2482,60 @@ 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 hook_project(target, root=None, docs_name=None):
+    """The project root an edit hook judges, with its docs root name set, or None
+    when two docs roots sit side by side. The hook runs in the session's current
+    directory, which a `cd` moves (live probe 2026-10-27): the project AND its docs
+    root name are the ones holding the edited file, never the ones around the
+    working directory. An explicit root (--root) is kept as given."""
+    start = Path(root) if root is not None else Path(target).resolve().parent
+    try:
+        found_root, name = resolve_docs_dir(argparse.Namespace(docs_dir=docs_name), start)
+    except AmbiguousDocsRoot:
+        return None
+    set_docs_dir(name)
+    if root is not None:
+        return Path(root)
+    if found_root is not None:
+        return found_root
+    found_root = find_project_root(start)  # an explicit name: discovery did not run
+    # No docs root above the edited file: the session's own project, as before the
+    # hook resolved from the file -- the file's folder would unprotect a gated path.
+    return found_root if ai_path(found_root).is_dir() else find_project_root()
+
+
 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:
+    if not isinstance(file_path, str) or not file_path:
         return 0
-    root = Path(args.root).resolve() if args.root else find_project_root()
+    root = hook_project(file_path, Path(args.root).resolve() if args.root else None,
+                        getattr(args, "docs_dir", None))
+    if root is None:
+        return 0  # two docs roots side by side: cannot tell which governs
     try:
         rel = str(Path(file_path).resolve().relative_to(root)).replace("\\", "/")
     except ValueError:
@@ -2326,6 +2566,607 @@ 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.
+_VERDICT_ROUTER_RE = re.compile(r"router(?:[\s*_`]+verdict)?[\s*_`]*:(.*)", re.IGNORECASE)
+# A declaration line may open with markdown: emphasis, quote, heading, bullet or a
+# numbered item ("## Level: L1", "1. Level: L1", "• router: no match").
+_LINE_OPEN = r"^[ \t>*_`#+•-]*(?:\d+[.)][ \t*_`]*)?"
+_LEVEL_WORD = r"(?:level|livello|niveau|nivel|stufe)\b[ \t*_`:·—–-]*(?:è[ \t]+)?"
+# ...and only on a line that opens with `router` or with a level (`L2`, `Spike`): a
+# verdict quoted inside a sentence is not one.
+_VERDICT_LINE_RE = re.compile(
+    _LINE_OPEN + r"(?:router\b|" + _LEVEL_WORD + r"(?:(?:research[ \t]+)?spike|[A-Z][123])\b)", re.IGNORECASE)
+_VERDICT_NONE_RE = re.compile(r"[\s`*_\"'(]*(no match|absent)", re.IGNORECASE)
+# A level is DECLARED by a line that opens with the level word, in the form Rule
+# Zero prescribes -- level 1 alone, 2/3 with `router` on the same line -- so a level
+# quoted inside a sentence is not one. The letter is the lens's own (`L1`, `E1`):
+# groups are (letter, "1" or "", "2"/"3" or "").
+_DECLARATION_RE = re.compile(
+    _LINE_OPEN + _LEVEL_WORD +
+    r"([A-Z])(?:(1)\b|([23])\b(?=[^\n]*\brouter\b))", re.IGNORECASE | re.MULTILINE)
+_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-1 declaration seen (`Level: L1`, `E1`), "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():
+                            d = _DECLARATION_RE.match(line)
+                            if d and d.group(2):
+                                facts["trivial"] = True
+                            m = _VERDICT_ROUTER_RE.search(line)
+                            if m and (d or _VERDICT_LINE_RE.match(line)):
+                                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=None, docs_name=None):
+    """The refusal line for this edit event, or None when the edit may proceed.
+    Without a root, the project is the one holding the edited file (hook_project)."""
+    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 isinstance(target, str) or not target or not transcript:
+        return None
+    root = hook_project(target, root, docs_name)
+    if root is None:
+        return None  # two docs roots side by side: cannot tell which governs
+    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 None
+        reason = verdict_reason(payload, root, getattr(args, "docs_dir", None))
+        if reason:
+            print(json.dumps({"hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": reason}}, ensure_ascii=False))
+    except Exception:
+        pass
+    return 0
+
+
+# -------------------------------------------------------------- constraints
+# F-085: the constraint reader. It reads what an ANALYSIS already states in
+# extractable form -- id'd use cases, spec items and threats, and the rows of
+# the `### Preservation constraints` table -- and binds each to the files it
+# names. It names no feature and computes nothing: no count, rank or marker
+# reaches the output, and every view ends with CONSTRAINTS_SENTENCE naming what
+# it could not extract, so a short view never reads as a complete one.
+
+CONSTRAINT_SECTIONS = (("## Use Cases",), ("## Functional Spec",), SECURITY_SECTION)
+INTERFACE_SECTION = ("## Interface Contract",)
+IMPACT_SECTION = ANALYSIS_SECTIONS[2]
+PRESERVATION_HEADING = "### Preservation constraints"
+NO_SYMBOL_LINE = "No existing symbol changed."
+CONSTRAINTS_SENTENCE = ("This view shows only the constraints written in extractable "
+                        "form and never replaces the ANALYSIS")
+CONSTRAINT_LINE_MAX = 300
+
+_ITEM_RE = re.compile(r"^\s*([-*+]\s+|#{3,4}\s+|\|\s*)(?:\*\*|__)?(?:UC|FS|T)\d+\b")
+_P_ROW_RE = re.compile(r"^\|\s*(?:\*\*)?(P\d+)\b")
+_ITEM_ID_RE = re.compile(r"(UC|FS|T)\d+")
+_CITE_RE = re.compile(r"\b(UC|FS|T)(\d+)(?:\s*[–-]\s*(?:UC|FS|T)?(\d+))?\b")
+_BACKTICK_RE = re.compile(r"`([^`\n]+)`")
+_PATH_TOKEN_RE = re.compile(r"^[A-Za-z0-9_.\-/]+(?:::[A-Za-z0-9_.]+)?$")
+_PATH_EXT_RE = re.compile(r"[^./]\.[A-Za-z0-9]+$")
+_SENTENCE_END_RE = re.compile(r"[.!?](?=\s|$)")
+_CELL_SPLIT_RE = re.compile(r"(?<!\\)\|")
+_CONTROL_RE = re.compile(r"[\x00-\x08\x0b-\x1f\x7f]")
+
+
+def _norm_rel(path):
+    """Repository-relative, forward slashes, case-folded where the filesystem is."""
+    p = path.replace("\\", "/")
+    while p.startswith("./"):
+        p = p[2:]
+    return p.casefold() if os.name == "nt" else p
+
+
+def _path_tokens(text, need_slash):
+    """The backticked file paths in `text`; `path::symbol` yields its path. An elided
+    (`...`), globbed, placeholder or parent-relative path binds nothing; in prose
+    (`need_slash`) a bare file name is a mention, not a binding."""
+    out = set()
+    for token in _BACKTICK_RE.findall(text or ""):
+        t = token.strip()
+        if "..." in t or "*" in t or t.startswith("/") or not _PATH_TOKEN_RE.match(t):
+            continue
+        path = t.split("::", 1)[0]
+        while path.startswith("./"):
+            path = path[2:]
+        if ".." in path.split("/") or not _PATH_EXT_RE.search(path):
+            continue
+        if need_slash and "/" not in path:
+            continue
+        out.add(_norm_rel(path))
+    return out
+
+
+def _first_sentence(text):
+    """Up to the first sentence end outside a backticked span (so `a.py` never ends
+    one); a bold title such as `**FS1 Ids.**` ends nothing either."""
+    masked = _BACKTICK_RE.sub(lambda m: "`" + "x" * len(m.group(1)) + "`", text)
+    m = _SENTENCE_END_RE.search(masked)
+    return text[:m.end()] if m else text
+
+
+def _cells(row):
+    return [c.strip() for c in _CELL_SPLIT_RE.split(row.strip().strip("|"))]
+
+
+def _cited_ids(text):
+    """Ids cited in `text`, a range such as `FS3–FS7` expanded."""
+    out = set()
+    for prefix, start, end in _CITE_RE.findall(text or ""):
+        a = int(start)
+        b = int(end) if end else a
+        if b < a or b - a > 50:
+            b = a
+        out.update(f"{prefix}{n}" for n in range(a, b + 1))
+    return out
+
+
+def parse_constraints(text):
+    """Every constraint `text` states in extractable form, in document order: a dict
+    with `id`, `kind` (`item` or `P`), `section` (its `## ` heading), `line`
+    (1-based), `statement`, `bindings` (normalized paths), `evidence` and
+    `released` (a P row's release reference, or None)."""
+    lines = (text or "").splitlines()
+    items, impact_rows = [], []
+    section, extracted, impact, preservation = None, False, False, False
+    for n, line in enumerate(lines):
+        if line.startswith("## "):
+            section = line.strip()
+            extracted = any(line.startswith(a) for s in CONSTRAINT_SECTIONS for a in s)
+            impact = any(line.startswith(a) for a in IMPACT_SECTION)
+            preservation = False
+            continue
+        if impact:
+            if line.startswith("### "):
+                preservation = line.strip().lower() == PRESERVATION_HEADING.lower()
+                continue
+            if not line.lstrip().startswith("|"):
+                continue
+            cells = _cells(line)
+            if preservation:
+                m = _P_ROW_RE.match(line.strip())
+                if m and len(cells) >= 5:
+                    must = cells[3]
+                    released = None
+                    if must.startswith("RELEASED (") and ")" in must:
+                        released = must[len("RELEASED ("):must.index(")")]
+                    items.append({"id": m.group(1), "kind": "P", "section": section,
+                                  "line": n + 1, "statement": must,
+                                  "bindings": _path_tokens(cells[1], False),
+                                  "evidence": cells[4], "released": released})
+            elif cells:
+                paths = _path_tokens(cells[0], False)
+                if paths:
+                    impact_rows.append((paths, _cited_ids(" | ".join(cells[1:]))))
+            continue
+        if not extracted:
+            continue
+        m = _ITEM_RE.match(line)
+        if not m:
+            continue
+        marker = m.group(1).strip()
+        body = []
+        if not marker.startswith("|"):
+            for nxt in lines[n + 1:]:
+                if nxt.startswith("#") or _ITEM_RE.match(nxt):
+                    break
+                if marker.startswith("#"):
+                    if nxt.strip():
+                        body.append(nxt.strip())
+                elif nxt.strip() and nxt[:1].isspace():
+                    body.append(nxt.strip())
+                else:
+                    break
+        if marker.startswith("|"):
+            statement = _first_sentence(" | ".join(_cells(line)))
+            whole = line
+        elif marker.startswith("#"):
+            title = line.lstrip("#").strip()
+            rest = " ".join(body)
+            statement = title + (" — " + _first_sentence(rest) if rest else "")
+            whole = " ".join([line] + body)
+        else:
+            joined = " ".join([line.strip()[len(marker):].strip()] + body)
+            statement = _first_sentence(joined)
+            whole = joined
+        items.append({"id": _ITEM_ID_RE.search(line).group(0), "kind": "item",
+                      "section": section, "line": n + 1, "statement": statement,
+                      "bindings": _path_tokens(whole, True), "evidence": None,
+                      "released": None})
+    for paths, ids in impact_rows:
+        for c in items:
+            if c["kind"] == "item" and c["id"] in ids:
+                c["bindings"] |= paths
+    return items
+
+
+def has_preservation_record(impact_body):
+    """True when an Impact body holds the preservation table or the no-symbol line."""
+    return any(b.strip().lower() == PRESERVATION_HEADING.lower() or b.strip() == NO_SYMBOL_LINE
+               for b in (impact_body or "").splitlines())
+
+
+def unread_sections(text, items=None):
+    """The `## ` headings the view could not extract, in document order: the
+    Interface Contract (its items carry no id), an extracted section holding prose
+    but no id'd item, and an Impact with neither the preservation table nor the
+    no-symbol line."""
+    items = parse_constraints(text) if items is None else items
+    homes = {c["section"] for c in items if c["kind"] == "item"}
+    lines = (text or "").splitlines()
+    names = []
+    for i, line in enumerate(lines):
+        if not line.startswith("## "):
+            continue
+        body = []
+        for nxt in lines[i + 1:]:
+            if nxt.startswith("## "):
+                break
+            body.append(nxt)
+        heading = line.strip()
+        if any(line.startswith(a) for a in INTERFACE_SECTION):
+            names.append(heading)
+        elif any(line.startswith(a) for s in CONSTRAINT_SECTIONS for a in s):
+            if any(b.strip() for b in body) and heading not in homes:
+                names.append(heading)
+        elif any(line.startswith(a) for a in IMPACT_SECTION):
+            if not has_preservation_record("\n".join(body)):
+                names.append(heading)
+    return names
+
+
+def constraints_sentence(names):
+    if not names:
+        return CONSTRAINTS_SENTENCE + "."
+    return CONSTRAINTS_SENTENCE + "; read in full: " + ", ".join(f"`{n}`" for n in names) + "."
+
+
+def _clip(line):
+    line = _CONTROL_RE.sub("", line)
+    return line if len(line) <= CONSTRAINT_LINE_MAX else line[:CONSTRAINT_LINE_MAX - 1] + "…"
+
+
+def constraint_lines(home, items, grouped):
+    """FS4's lines: `ID — statement — home:line`, a P row followed by its evidence;
+    `grouped` puts each home heading before its first item."""
+    out, current = [], None
+    for c in items:
+        if grouped and c["section"] != current:
+            current = c["section"]
+            out.append(_clip(current))
+        out.append(_clip(f"{c['id']} — {c['statement']} — {home}:{c['line']}"))
+        if c["kind"] == "P" and c["evidence"]:
+            out.append(_clip(f"    evidence: {c['evidence']}"))
+    return out
+
+
+def unit_constraints(root, unit):
+    """[(path, meta, items, unread)] for the ANALYSIS files of `unit` -- an id such
+    as F-001, or a file name with or without `.md`; [] when none matches."""
+    key = str(unit or "").strip()
+    name = key if key.endswith(".md") else key + ".md"
+    out = []
+    for p, meta, text in list_analyses(root):
+        m = UNIT_ID_RE.search(str(meta.get("id") or ""))
+        if p.name == name or (m and m.group(1) == key):
+            items = parse_constraints(text)
+            out.append((p, meta, items, unread_sections(text, items)))
+    return out
+
+
+def project_relative(root, path):
+    """`path` relative to `root`, normalized as bindings are, or None outside it."""
+    raw = str(path or "").replace("\\", "/")
+    if not raw:
+        return None
+    p = Path(raw)
+    if not p.is_absolute():
+        p = Path.cwd() / p
+    try:
+        rel = p.resolve().relative_to(Path(root).resolve())
+    except (ValueError, OSError):
+        return None
+    return _norm_rel(rel.as_posix())
+
+
+def open_code_units(root):
+    """[(path, meta, text)] for the tree's open L3 units of the code domain. Open
+    units come from `_open_units`, unchanged (P1)."""
+    if not ai_path(root).is_dir():
+        return []
+    open_names = {n for names in _open_units(root).values() for n in names}
+    if not open_names:
+        return []
+    default = project_default_domain(root)
+    return [(p, meta, text) for p, meta, text in list_analyses(root)
+            if p.name in open_names
+            and str(meta.get("level", "")).upper() == "L3"
+            and meta.get("status") in ("PLANNED", "IN_PROGRESS")
+            and resolve_domain(meta, default)[0] == "code"]
+
+
+def file_constraints(root, path):
+    """[(path, meta, bound items, unread)] for each open L3 unit of the code domain
+    with an unreleased constraint bound to `path`."""
+    rel = project_relative(root, path)
+    if rel is None:
+        return []
+    out = []
+    for p, meta, text in open_code_units(root):
+        items = parse_constraints(text)
+        bound = [c for c in items if not c["released"] and rel in c["bindings"]]
+        if bound:
+            out.append((p, meta, bound, unread_sections(text, items)))
+    return out
+
+
+# The recall hook (FS6). It informs, never decides: its JSON carries no
+# `permissionDecision`, so the user's permission flow is the one without it
+# (P6). A level is read with the verdict hook's `_DECLARATION_RE`; only the code
+# lens's `L` levels count here.
+CONSTRAINTS_HOOK_LINES = 15
+_WORK_TOOLS = VERDICT_EDIT_TOOLS + ("Read",)
+
+
+def transcript_work(path):
+    """What the session transcript shows about the work, or None when it cannot be
+    read within the verdict hook's bounds: {"assistant": entries parsed,
+    "sidechain": a subagent's transcript, "level": the last declared level ("1",
+    "2", "3") or None, "touched": normalized absolute paths this session read or
+    wrote}."""
+    work = {"assistant": 0, "sidechain": False, "level": None, "touched": 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
+                work["assistant"] += 1
+                if entry.get("isSidechain") is True:
+                    work["sidechain"] = True
+                for block in content:
+                    if not isinstance(block, dict):
+                        continue
+                    if block.get("type") == "text":
+                        for letter, one, other in _DECLARATION_RE.findall(
+                                str(block.get("text") or "")):
+                            if letter.upper() == "L":
+                                work["level"] = one or other
+                    elif block.get("type") == "tool_use" and block.get("name") in _WORK_TOOLS:
+                        inp = block.get("input") or {}
+                        target = inp.get("file_path") or inp.get("notebook_path")
+                        if isinstance(target, str) and target:
+                            try:
+                                work["touched"].add(_norm_rel(Path(target).resolve().as_posix()))
+                            except (OSError, ValueError):
+                                pass
+    except (OSError, ValueError, TypeError, AttributeError):
+        return None
+    return work
+
+
+def _hook_new_text(tool_input):
+    """The text an edit is about to write: Edit, Write, MultiEdit, NotebookEdit."""
+    parts = [tool_input.get(k) for k in ("new_string", "content", "new_source")]
+    for e in tool_input.get("edits") or []:
+        if isinstance(e, dict):
+            parts.append(e.get("new_string"))
+    return "\n".join(x for x in parts if isinstance(x, str))
+
+
+def _unit_documents(root, p):
+    """Normalized absolute paths of a unit's ANALYSIS, request records and handoff:
+    reading or writing any of them is working on the unit."""
+    slug = p.stem[len("ANALYSIS_"):]
+    docs = {p, ai_path(root, "audit", f"HANDOFF_{slug}.md")}
+    req = ai_path(root, "audit", "requests")
+    if req.is_dir():
+        for r in req.glob("REQUEST_*.md"):
+            meta = load_frontmatter(read_text(r).splitlines())
+            if str(meta.get("analysis") or "").strip().strip("'\"`") == p.name:
+                docs.add(r)
+                docs.add(ai_path(root, "audit", f"HANDOFF_{r.stem[len('REQUEST_'):]}.md"))
+    return {_norm_rel(d.resolve().as_posix()) for d in docs}
+
+
+def constraints_hook_context(payload, root=None, docs_name=None):
+    """The context to recall before this edit, or None (FS6): an edit tool, outside
+    a subagent, on a file of a project whose open L3 code unit binds it (or the
+    unit's own ANALYSIS, about to name a path a P row binds -- UC6), by a session
+    that worked on that unit and last declared L3."""
+    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 isinstance(target, str) or not target or not transcript:
+        return None
+    root = hook_project(target, root, docs_name)
+    if root is None or not ai_path(root, "solutions").is_dir():
+        return None
+    found = file_constraints(root, target)
+    rel = project_relative(root, target)
+    named = _path_tokens(_hook_new_text(tool_input), False)
+    if named and rel and rel.startswith(_norm_rel(f"{docs_dir()}/solutions/ANALYSIS_")):
+        for p, meta, text in open_code_units(root):
+            if _norm_rel(f"{docs_dir()}/solutions/{p.name}") != rel:
+                continue
+            items = parse_constraints(text)
+            bound = [c for c in items if c["kind"] == "P"
+                     and not c["released"] and c["bindings"] & named]
+            if bound and not any(f[0] == p for f in found):
+                found.append((p, meta, bound, unread_sections(text, items)))
+    if not found:
+        return None
+    work = transcript_work(transcript)
+    if not work or not work["assistant"] or work["sidechain"] or work["level"] != "3":
+        return None
+    # One budget for the whole recall, whatever the number of units; a P line and
+    # its evidence line are kept together or left out together.
+    out, budget = [], CONSTRAINTS_HOOK_LINES
+    for p, meta, items, unread in found:
+        if not (_unit_documents(root, p) & work["touched"]):
+            continue
+        home = f"solutions/{p.name}"
+        unit = meta.get("id") or p.stem
+        out.append(_clip(f"[sdlc constraints] {unit} — {home}"))
+        shown = 0
+        for c in items:
+            chunk = constraint_lines(home, [c], False)
+            if len(chunk) > budget:
+                break
+            out.extend(chunk)
+            budget -= len(chunk)
+            shown += 1
+        if shown < len(items):
+            out.append(_clip(f"More: sdlc_check.py constraints --unit {unit}"))
+        out.append(_clip(constraints_sentence(unread)))
+    return "\n".join(out) if out else None
+
+
+def cmd_constraints_hook(args):
+    """PreToolUse hook: print a context-only JSON or nothing. Always 0 -- exit 2
+    would block the edit, and the wired command adds `; exit 0` for validators
+    that cannot run this at all (T2)."""
+    try:
+        payload = read_hook_payload()
+        if payload is None:
+            return 0
+        root = Path(args.root).resolve() if args.root else None
+        context = constraints_hook_context(payload, root, getattr(args, "docs_dir", None))
+        if context:
+            print(json.dumps({"hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "additionalContext": context}}, ensure_ascii=False))
+    except Exception:
+        pass
+    return 0
+
+
+def cmd_constraints(root, args):
+    if args.unit:
+        found = unit_constraints(root, args.unit)
+        if not found:
+            print(f"[ERROR] unknown unit '{args.unit}': give an id such as F-001 "
+                  "or an ANALYSIS file name")
+            return 1
+        groups = [(p, meta, items, unread, True) for p, meta, items, unread in found]
+    else:
+        groups = [(p, meta, items, unread, False)
+                  for p, meta, items, unread in file_constraints(root, args.file)]
+    for p, meta, items, unread, grouped in groups:
+        home = f"solutions/{p.name}"
+        print(_clip(f"{meta.get('id') or p.stem} — {home}"))
+        for line in constraint_lines(home, items, grouped):
+            print(line)
+        print(_clip(constraints_sentence(unread)))
+    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 +3366,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):
@@ -2647,6 +3496,10 @@ def cmd_benefit(root):
     rows, unparsed = parse_review_log(read_text(log))
     not_due = [r for r in rows if _is_not_due(r["verdict"])]
     rows = [r for r in rows if not _is_not_due(r["verdict"])]
+    # F-085 FS10: a `post-merge` row is the owner's report of a defect that got
+    # past every review -- not a review, so it stays out of every review figure.
+    post_merge = [r for r in rows if r["tier"].lower().startswith("post-merge")]
+    rows = [r for r in rows if not r["tier"].lower().startswith("post-merge")]
     # `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
@@ -2671,11 +3524,14 @@ def cmd_benefit(root):
                     unstated_code += n
     classified = moments["design"] + moments["closure"]
     print("rows parsed: %d   rows unparsed: %d%s"
-          % (len(rows) + len(not_due), len(unparsed),
+          % (len(rows) + len(not_due) + len(post_merge), len(unparsed),
              ("  -> " + "; ".join("line %d: %s" % u for u in unparsed[:5]))
              if unparsed else ""))
     print("reviews ruled not due (logged, counted in no figure below): %d"
           % len(not_due))
+    if post_merge:
+        print("defects reported after merge (tier post-merge, not reviews, "
+              "counted in no figure below): %d" % len(post_merge))
     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
@@ -2741,48 +3597,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 +4012,28 @@ 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")
+
+    cp = sub.add_parser("constraints", parents=[common],
+                        help="print the constraints an ANALYSIS states in extractable "
+                             "form: a unit's view, or those bound to a file")
+    cg = cp.add_mutually_exclusive_group(required=True)
+    cg.add_argument("--unit", help="unit id (e.g. F-001) or ANALYSIS file name")
+    cg.add_argument("--file", help="file path: constraints of the open L3 code units bound to it")
+    cg.add_argument("--hook", action="store_true",
+                    help="PreToolUse hook: read the payload from stdin, print context only "
+                         "(fail-open, always exit 0)")
+
     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: "
@@ -3027,6 +4057,16 @@ def main(argv=None):
 
     args = ap.parse_args(argv)
 
+    # F-085: the edit hooks resolve their root and docs root from the edited file
+    # (the hook runs in whatever directory the session moved to), so they are
+    # dispatched before the working-directory resolution below.
+    if args.cmd == "constraints" and args.hook:
+        return cmd_constraints_hook(args)
+    if args.cmd == "verdict":
+        return cmd_verdict(args)
+    if args.cmd == "gate":
+        return cmd_gate(args)
+
     # 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.
@@ -3050,8 +4090,6 @@ def main(argv=None):
             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":
@@ -3067,9 +4105,11 @@ 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 == "constraints":
+        return cmd_constraints(root, args)
     if args.cmd == "migrate":
         return cmd_migrate(root, args)
     if args.cmd == "plan":