@antoneeo/course-creator 0.1.0-beta.1 → 0.1.0-beta.13

package/skills/course-creator/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
@@ -89,6 +91,18 @@ ARCHITECT_PASS_EPOCH = "2026-07-28"
 # row. Same grandfathering discipline as the pass above -- never nag work that
 # predates the rule.
 DESIGN_REVIEW_EPOCH = "2026-07-28"
+# Chronology (F-073): an L3 ANALYSIS started, or an L3 HANDOFF updated, on/after
+# this date is read for undated Diary text and a multi-step `next:`. Advisories,
+# 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
 def review_log_rel():
     return f"{docs_dir()}/audit/reviews/REVIEW_LOG.md"
 # Component Map 'Where' refs: a dotted token counts as a path only with one of
@@ -388,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
@@ -516,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
@@ -834,6 +892,10 @@ def build_registry(root):
         return ""
     stamp = max(str(m.get("updated") or m.get("since") or "").strip() or "0000-00-00"
                 for _p, m in rows)
+    return _render_registry(root, rows, stamp)
+
+
+def _render_registry(root, rows, stamp):
     lines = ["# Handoff — workstream registry",
              f"Date: {stamp} (UTC)",
              "",
@@ -858,15 +920,44 @@ 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
 
 
+def is_generated_registry(text):
+    # "Ours" = written by ANY family entry point: the header is WRITTEN with
+    # entry_script(), so recognition must not hard-code one distribution's
+    # script name (a registry generated by mkt_check.py is just as generated).
+    return bool(re.search(r"GENERATED by \S+ index - do not edit by hand", text))
+
+
+def generated_registry_rows(text):
+    """Workstream rows of a generated registry, ignoring the project notes
+    (free text that may carry tables of its own)."""
+    return parse_registry_rows(text.split("\n## Project-wide notes", 1)[0])
+
+
+def build_empty_registry(root, existing):
+    """The generated registry once the last source is gone (F1, found by F-068).
+
+    Only for a registry that is already ours: a hand-written handoff with no
+    sources is a project that never converted, and stays untouched. The Date is
+    kept while the view is already empty -- re-running index on a clean tree
+    must not change it -- and becomes today's when rows are being dropped:
+    there is no source left whose `updated:` could date the closure."""
+    m = re.search(r"Date:\s*(\d{4}-\d{2}-\d{2})", existing)
+    if m and not generated_registry_rows(existing):
+        stamp = m.group(1)
+    else:
+        stamp = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    return _render_registry(root, [], stamp)
+
+
 def registry_conversion_blockers(root):
     """What stops `index` from writing over a hand-written handoff.md.
 
@@ -879,10 +970,7 @@ def registry_conversion_blockers(root):
     if not hand.is_file():
         return []
     text = read_text(hand)
-    # "Already ours" = written by ANY family entry point: the header is WRITTEN
-    # with entry_script(), so recognition must not hard-code one distribution's
-    # script name (a registry generated by mkt_check.py is just as generated).
-    if re.search(r"GENERATED by \S+ index - do not edit by hand", text):
+    if is_generated_registry(text):
         return []
     blockers = []
     known = {str(m.get("workstream")).strip() for _p, m in list_workstreams(root)}
@@ -1015,10 +1103,21 @@ def cmd_index(root):
 def rc_registry(root):
     """Write the generated workstream registry, or refuse and say why (F-028)."""
     ws = list_workstreams(root)
+    hand = ai_path(root, "audit", "handoff.md")
     if not ws:
-        return 0                # no sources: a hand-written handoff is untouched
+        # No sources: a hand-written handoff is untouched; a generated one is
+        # emptied, or the last closed workstream would stay listed forever.
+        if not hand.is_file():
+            return 0
+        existing = read_text(hand)
+        if not is_generated_registry(existing):
+            return 0
+        empty = build_empty_registry(root, existing)
+        if norm_text(existing) != norm_text(empty):
+            hand.write_text(empty, encoding="utf-8")
+            print(f"[ok] workstream registry emptied (no open workstreams): {hand}")
+        return 0
     blockers = registry_conversion_blockers(root)
-    hand = ai_path(root, "audit", "handoff.md")
     if blockers:
         print(f"[ERROR] {docs_dir()}/audit/handoff.md NOT regenerated -- it still holds "
               "state no source accounts for:")
@@ -1060,6 +1159,317 @@ def section_body(text, aliases):
     return None
 
 
+def section_lines(text, aliases):
+    """(heading_line, body) for the first matching `## ` section, or None: the
+    body NOT stripped, so body line n is file line heading_line + n, and an
+    indented first line keeps its indentation. The readers below use it; a
+    stripped body would shift every line number and move `  - DATE` to column 0."""
+    lines = (text or "").splitlines()
+    for i, line in enumerate(lines):
+        if any(line.startswith(a) for a in aliases):
+            body = []
+            for nxt in lines[i + 1:]:
+                if nxt.startswith("## "):
+                    break
+                body.append(nxt)
+            return i + 1, "\n".join(body)
+    return None
+
+
+# ---------------------------------------------------------------- chronology
+# One grammar for a dated entry (F-073), read by the validator and by any
+# consumer that lists events (F-072's chronology): both call these readers, so
+# they cannot disagree on what an event is. The readers return openers only --
+# date, label, line -- and format nothing for display.
+
+DIARY_SECTION = next(s for s in ANALYSIS_SECTIONS if s[0] == "## Diary")
+_ISO = r"\d{4}-\d{2}-\d{2}"
+# At column 0: optional list marker, optional `###`/`####`, optional bold, then
+# the ISO date and a word boundary. The date FIRST is the rule; markup is
+# tolerated so the dated forms already written stay readable with no migration.
+ENTRY_OPENER = re.compile(r"^(?:([-*]) |(#{3,4}) )?(\*\*)?(" + _ISO + r")\b(.*)$")
+_LABEL_SEP = re.compile(r"^(?:\*\*)?\s*(?:[—–:-])?\s*")
+_REQUEST_HEADING = re.compile(r"^### (R\d+) [—–-] (" + _ISO + r") [—–-] (.+)$")
+_ADR_BODY_DATE = re.compile(r"^\**Date:\**\s*(" + _ISO + r")\b", re.M)
+_ADR_NAME_DATE = re.compile(r"^ADR_(" + _ISO + r")_", re.I)
+UNIT_ID_RE = re.compile(r"\b([A-Z]-\d{3,})\b")
+
+
+def _entry_label(bold, rest):
+    rest = _LABEL_SEP.sub("", rest, count=1)
+    if bold and "**" in rest:
+        rest = rest.split("**", 1)[0]
+    else:
+        rest = re.split(r"(?<=[.!?])\s", rest, maxsplit=1)[0]
+    return rest.strip(" .:—–-*")[:120]
+
+
+def _opener_at(lines, i):
+    """The match when lines[i] opens an entry. It must also START A BLOCK -- the
+    line above is blank, absent or a heading, or the line is itself a list item
+    or a heading -- so a hard-wrapped prose line that happens to begin with a
+    date is never an event. (A separator after the date is NOT required: real
+    openers read `DATE (qualifier)` and `DATE word`.)"""
+    m = ENTRY_OPENER.match(lines[i])
+    if not m:
+        return None
+    prev = lines[i - 1] if i else ""
+    if not prev.strip() or prev.startswith("#") or m.group(1) or m.group(2):
+        return m
+    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
+    are blanked first, exactly as `undated_diary_lines` does, so an entry
+    written under the template's comment is an event to both."""
+    lines = _blank_comments(body).splitlines()
+    out = []
+    for i in range(len(lines)):
+        m = _opener_at(lines, i)
+        if m:
+            out.append((m.group(4), _entry_label(m.group(3), m.group(5)), i + 1))
+    return out
+
+
+def _blank_comments(text):
+    # comments become blank lines, so line numbers still point at the file's lines
+    return re.sub(r"<!--.*?-->", lambda m: "\n" * m.group(0).count("\n"), text or "",
+                  flags=re.S)
+
+
+def undated_diary_lines(body):
+    """[(line, text)] a Diary body cannot date: text before the first opener,
+    and any `### ` heading that is not an opener. `####` and deeper headings are
+    sub-structure of an entry and stay legal. Comments are ignored."""
+    lines = _blank_comments(body).splitlines()
+    out, seen_opener = [], False
+    for i, line in enumerate(lines):
+        if _opener_at(lines, i):
+            seen_opener = True
+        elif line.startswith("### "):
+            out.append((i + 1, line.strip()))
+        elif not seen_opener and line.strip():
+            out.append((i + 1, line.strip()))
+    return out
+
+
+def request_entries(text):
+    """(entries, unparsed) for a request record: entries are
+    [(rid, date, label, line)]; a `### ` heading that does not match
+    `### R<n> — YYYY-MM-DD — <label>` is returned in unparsed as (line, text),
+    never dropped."""
+    entries, unparsed = [], []
+    for i, line in enumerate((text or "").splitlines()):
+        if not line.startswith("### "):
+            continue
+        m = _REQUEST_HEADING.match(line.rstrip())
+        if m:
+            entries.append((m.group(1), m.group(2), m.group(3).strip(), i + 1))
+        else:
+            unparsed.append((i + 1, line.rstrip()))
+    return entries, unparsed
+
+
+def adr_date(name, text):
+    """An ADR's date: `**Date:** YYYY-MM-DD` in the body, else the
+    `ADR_YYYY-MM-DD_*` file name, else None."""
+    m = _ADR_BODY_DATE.search(text or "") or _ADR_NAME_DATE.match(name or "")
+    return m.group(1) if m else None
+
+
+def _meta_date(meta, key):
+    return parse_iso(str(meta.get(key) or "").strip().strip("'\"")[:10])
+
+
+def chronology_advisories(root):
+    """A1 (undated Diary text) and A2 (`next:` is not one step), as advisory
+    strings. Gated on `level: L3` and on a date the file carries -- never an
+    mtime -- so L1/L2 work and anything written before the epoch see nothing."""
+    epoch = parse_iso(CHRONOLOGY_EPOCH)
+    out = []
+    for p, meta, text in list_analyses(root):
+        started = _meta_date(meta, "start_date")
+        if str(meta.get("level", "")).upper() != "L3" or not started or started < epoch:
+            continue
+        section = section_lines(text, DIARY_SECTION)
+        if section is None:
+            continue
+        head, body = section
+        rel = "solutions/" + p.name
+        lines = undated_diary_lines(body)
+        preface = [(n, t) for n, t in lines if not t.startswith("### ")]
+        if preface:
+            out.append(f"{rel}: line {head + preface[0][0]}: Diary text '{preface[0][1][:60]}' "
+                       "comes before the first dated entry -- open entries with "
+                       "**YYYY-MM-DD — label.**, and write the current state as the latest "
+                       "dated entry")
+        for n, t in lines:
+            if t.startswith("### "):
+                out.append(f"{rel}: line {head + n}: Diary heading '{t[:60]}' is not a dated "
+                           "entry -- open entries with **YYYY-MM-DD — label.**")
+    for p, meta in list_workstreams(root):
+        updated = _meta_date(meta, "updated")
+        if str(meta.get("level", "")).upper() != "L3" or not updated or updated < epoch:
+            continue
+        nxt = str(meta.get("next") or "").strip()
+        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
+
+
+def _open_units(root):
+    """{id: {analysis name}} for the tree's open L3 units: an L3 ANALYSIS that is
+    PLANNED or IN_PROGRESS, or a request record (L3 only, r26) whose `analysis:`
+    is absent from the tree or names such an open ANALYSIS. A closed unit's
+    record, kept forever, does not count."""
+    units, present, open_names = {}, set(), set()
+    for p, meta, _ in list_analyses(root):
+        present.add(p.name)
+        if (str(meta.get("level", "")).upper() == "L3"
+                and meta.get("status") in ("PLANNED", "IN_PROGRESS")):
+            m = UNIT_ID_RE.search(str(meta.get("id") or ""))
+            if m:
+                open_names.add(p.name)
+                units.setdefault(m.group(1), set()).add(p.name)
+    req = ai_path(root, "audit", "requests")
+    if req.is_dir():
+        for p in sorted(req.glob("REQUEST_*.md")):
+            meta = load_frontmatter(read_text(p).splitlines())
+            name = str(meta.get("analysis") or "").strip().strip("'\"`")
+            m = UNIT_ID_RE.search(str(meta.get("unit") or meta.get("id") or ""))
+            if m and name and (name not in present or name in open_names):
+                units.setdefault(m.group(1), set()).add(name)
+    return units
+
+
+def _git_out(root, *args, timeout=30):
+    r = subprocess.run(["git", *args], cwd=str(root), capture_output=True, text=True,
+                       encoding="utf-8", errors="replace", timeout=timeout)
+    return r.stdout if r.returncode == 0 else None
+
+
+def ids_on_other_refs(root, max_refs=ID_SCAN_MAX_REFS):
+    """[(id, mine, theirs, [refs])] -- an open unit's id that another ref (heads,
+    remotes, tags) uses for a DIFFERENT analysis. Identity is the ANALYSIS file
+    name, declared by the ANALYSIS or announced by a request record's
+    `analysis:`. One `git grep` over local refs, fixed arguments only (T8);
+    as fresh as the last fetch. [] with no open L3 unit or no git; None when
+    skipped -- above `max_refs` refs, or git failed or timed out -- so the
+    caller can say the check did not run instead of reporting it clean."""
+    mine = _open_units(root)
+    if not mine or not git_available(root):
+        return []
+    try:
+        head = (_git_out(root, "rev-parse", "HEAD") or "").strip()
+        listing = _git_out(root, "for-each-ref",
+                           "--format=%(objectname) %(objecttype) %(*objecttype) %(refname)",
+                           "refs/heads", "refs/remotes", "refs/tags")
+        if listing is None:
+            return None
+        refs = []
+        for line in listing.split("\n"):
+            parts = line.split(" ")
+            if len(parts) == 3:                     # %(*objecttype) empty: not a tag
+                parts.insert(2, "")
+            if len(parts) != 4:
+                continue
+            sha, kind, peeled, ref = parts
+            # only refs that resolve to a commit can be grepped (a tag on a blob
+            # would fail the whole batch); the tree's own commit is not "another
+            # ref"; symbolic HEADs repeat a branch
+            if "commit" not in (kind, peeled) or ref.endswith("/HEAD") or sha == head:
+                continue
+            refs.append(ref)
+        if not refs:
+            return []
+        if len(refs) > max_refs:
+            return None
+        # Pathspecs are relative to cwd=root, so a docs root inside a monorepo
+        # subdirectory is found. -z keeps a path with ':' or non-ASCII intact
+        # (quotePath off); -n plus the fence lines confine hits to frontmatter.
+        docs = docs_dir()
+        chunks = []
+        for i in range(0, len(refs), ID_SCAN_REFS_PER_CALL):   # command-line length
+            r = subprocess.run(
+                ["git", "-c", "core.quotePath=false", "grep", "-z", "-n", "-I", "-E",
+                 r"^(id|unit|analysis):|^---\s*$", *refs[i:i + ID_SCAN_REFS_PER_CALL],
+                 "--", f"{docs}/solutions/ANALYSIS_*.md", f"{docs}/audit/requests/REQUEST_*.md"],
+                cwd=str(root), capture_output=True, text=True, encoding="utf-8",
+                errors="replace", timeout=60)
+            if r.returncode not in (0, 1):                     # 1 = no match
+                return None
+            chunks.append(r.stdout)
+    except Exception:
+        return None
+    per = {}
+    for line in "".join(chunks).split("\n"):     # not splitlines: \x1c.. are content
+        parts = line.split("\0")
+        if len(parts) != 3 or ":" not in parts[0] or not parts[1].isdigit():
+            continue
+        ref, path = parts[0].split(":", 1)          # a ref name cannot hold ':'
+        content = parts[2].rstrip("\r")
+        st = per.setdefault((ref, path), {"fences": 0, "kv": {}})
+        if int(parts[1]) == 1 and content.strip() == "---":
+            st["fences"] = 1                        # frontmatter opens on line 1
+        elif st["fences"] == 1 and content.strip() == "---":
+            st["fences"] = 2                        # ...and closes here
+        elif st["fences"] == 1:
+            key, _, val = content.partition(":")
+            st["kv"].setdefault(key, val.strip())
+    found = {}
+    for (ref, path), st in per.items():
+        kv = st["kv"]
+        fname = path.replace("\\", "/").rsplit("/", 1)[-1]
+        name = fname if fname.startswith("ANALYSIS_") else kv.get("analysis", "").strip("'\"`")
+        m = UNIT_ID_RE.search(kv.get("id") or kv.get("unit") or "")
+        if not (m and name) or m.group(1) not in mine or name in mine[m.group(1)]:
+            continue
+        short = re.sub(r"^refs/(heads|remotes|tags)/", "", ref)
+        found.setdefault((m.group(1), name), [])
+        if short not in found[(m.group(1), name)]:
+            found[(m.group(1), name)].append(short)
+    return sorted((fid, ", ".join(sorted(mine[fid])), theirs, sorted(refs_))
+                  for (fid, theirs), refs_ in found.items())
+
+
+def id_advisories(root):
+    """A3 as advisory strings, for every entry point's `check`."""
+    hits = ids_on_other_refs(root)
+    if hits is None:
+        return [f"id check skipped (more than {ID_SCAN_MAX_REFS} refs, or git grep failed "
+                "or timed out) -- choose a new unit's id after fetching, as the first id "
+                "free on every ref"]
+    out = []
+    for fid, mine, theirs, refs in hits:
+        more = f" (+{len(refs) - 1} more)" if len(refs) > 1 else ""
+        out.append(f"id {fid} ({mine}) is also used by {theirs} on {refs[0]}{more}: choose "
+                   "the first id free on every ref -- if this is the same unit under its "
+                   "old name, ignore it")
+    return out
+
+
 def design_review_due(meta):
     """True when an L3 ANALYSIS owes a design-review row (review.md moment 1):
     implementation has started or finished, and it began on/after the gate
@@ -1113,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):
@@ -1354,10 +1784,10 @@ def cmd_validate(root, strict=False, hybrid=False):
                               "doing the work it triggers")
         # comment-stripped, anchored: a '<!-- TODO: the ## Capability Ledger -->'
         # must not read as the section being present
-        # Hybrid: the design lives in devPNT and its §4.5 gate owns this slot
-        # (the Hybrid ownership matrix: "run ONE of them, never both"), and its log
-        # rows are keyed on e_isp_/e_tdd_ doc_keys, not on this filename -- so
-        # firing here would be a permanent, unfixable false positive.
+        # Hybrid: the design lives in devPNT, and the agent review of it (the
+        # same review.md review, run before the proposal) logs a row keyed on
+        # its e_isp_/e_tdd_ doc_key, not on this filename -- so firing here
+        # would be a permanent, unfixable false positive.
         if not hybrid and design_review_due(meta) and not review_logged(root, p.name):
             advisories.append(f"{rel}: L3 in implementation with no design-review row in "
                               f"{review_log_rel()} -- the design was reviewed by nobody but its "
@@ -1365,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"
@@ -1496,6 +1930,12 @@ def cmd_validate(root, strict=False, hybrid=False):
                                 "workstream — decide which file owns it")
             else:
                 seen[wid] = p.name
+    elif hand.is_file():
+        text = read_text(hand)
+        if is_generated_registry(text) and generated_registry_rows(text):
+            errors.append(f"{docs_dir()}/audit/handoff.md lists workstreams no HANDOFF_*.md "
+                          "source exists for any more: run 'sdlc_check.py index' to drop "
+                          "the closed rows")
     if hand.is_file():
         m = re.search(r"(?:Date|Data):\s*(\d{4}-\d{2}-\d{2})", read_text(hand))
         if not m:
@@ -1509,6 +1949,7 @@ def cmd_validate(root, strict=False, hybrid=False):
             except ValueError:
                 warnings.append("audit/handoff.md: date not parseable")
 
+    advisories.extend(chronology_advisories(root))   # A1, A2 (F-073)
     for a in advisories:
         print(f"[note]  {a}")
     for w in warnings:
@@ -1653,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))
 
@@ -1674,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
@@ -1703,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 = []
@@ -1722,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.
@@ -1801,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):
@@ -1824,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"
 
@@ -1869,15 +2395,30 @@ def print_orient_hook_note(root):
         pass  # detection must never break check
 
 
-def cmd_check(root, strict=False, hybrid=False):
+def cmd_check(root, strict=False, hybrid=False, extra_validate=None, extra_sections=()):
+    """An overlay adds its checks through the two hooks, never after the call:
+    the summary line is the verdict, so every check that can fail runs before
+    it. `extra_validate()` folds into the validate stage; each
+    (title, fn) in `extra_sections` gets its own banner and summary rc."""
     print("===== validate =====")
     rc_v = cmd_validate(root, strict=strict, hybrid=hybrid)
+    if extra_validate is not None:
+        rc_v = max(rc_v, extra_validate())
+    # A3 (F-073): check only -- it reads git refs, and validate stays file-local.
+    # Advisory: printed, never part of any rc.
+    for a in id_advisories(root):
+        print(f"[note]  {a}")
     print("\n===== stale =====")
     rc_s = cmd_stale(root, hybrid=hybrid)
-    print(f"\ncheck: {'CLEAN' if not (rc_v or rc_s) else 'NOT CLEAN'} "
-          f"(validate rc={rc_v}, stale rc={rc_s})")
+    rcs = [("validate", rc_v), ("stale", rc_s)]
+    for title, fn in extra_sections:
+        print(f"\n===== {title} =====")
+        rcs.append((title, fn()))
+    failed = any(rc for _, rc in rcs)
+    print(f"\ncheck: {'NOT CLEAN' if failed else 'CLEAN'} "
+          f"({', '.join(f'{title} rc={rc}' for title, rc in rcs)})")
     print_orient_hook_note(root)
-    return 1 if (rc_v or rc_s) else 0
+    return 1 if failed else 0
 
 
 # --------------------------------------------------------------------- gate
@@ -1906,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.
 
@@ -1914,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
@@ -1963,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/
@@ -2162,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):
@@ -2235,6 +2928,13 @@ def _is_pass(verdict):
     return re.search(r"\bPASS\b", (verdict or "").upper()) is not None
 
 
+def _is_not_due(verdict):
+    """A review ruled not due (review.md, a delta that only restates judged
+    work): logged so a skip stays visible, but it is neither a review nor a
+    finding, so it stays out of every count below (F-071)."""
+    return (verdict or "").strip().upper().startswith("NOT DUE")
+
+
 def _print_read_cost():
     """The cost side, printed with the benefit and NEVER without it: a catch
     rate with no cost term justifies unbounded doctrine, and a cost term with
@@ -2275,6 +2975,8 @@ def cmd_benefit(root):
         _print_read_cost()
         return 0
     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"])]
     # `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
@@ -2299,9 +3001,11 @@ def cmd_benefit(root):
                     unstated_code += n
     classified = moments["design"] + moments["closure"]
     print("rows parsed: %d   rows unparsed: %d%s"
-          % (len(rows), len(unparsed),
+          % (len(rows) + len(not_due), 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))
     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
@@ -2367,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
@@ -2625,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: "
@@ -2671,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
@@ -2678,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":
@@ -2693,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":