@antoneeo/kb-agentic-skill 1.5.1 → 1.7.0

package/CHANGELOG.md

@@ -2,6 +2,92 @@
 
 Every significant change to this skill is recorded here.
 
+## [1.7.0] - 2026-08-28
+
+F-040 — the capture moment (second-brain unit 2): the day's decisions reach the
+ledger before they evaporate.
+
+### Added
+- **`SKILL.md` §The Capture Moment.** At a user-signed closing (phase 5 of a governed
+  unit, or any closing signal in an un-governed session), ONE sweep question carrying
+  its own inline search result: "today I recorded [...] — any other decisions from
+  today?". Scoped to TODAY, so it reaches decisions taken outside the session — facts
+  only the practitioner owns. A scheduled elicitation (the phase-3 round's family),
+  not a blocking question. The sweep is idempotent: a decision already noted at
+  phase 4 is verified, never re-captured. Channeling with explicit provenance
+  (elicited → ELICITED, synthesis → DERIVED, RULING only when resolving a contested
+  set per reconciliation §2); capture never creates topics (`unplaced.md` is never a
+  decision park); a no-topic decision is noted NOW with the placement declared as the
+  next kb unit. Declared residual: an unsignaled end captures nothing — the phase-4
+  note-when-said duty is the protection for sessions that never close.
+- **Notes recency in the kb `orient`.** Whenever `corpus/notes/` exists: `newest
+  note: N days old` (or `no notes yet`), dated from note frontmatter `date:` with
+  mtime as fallback — named limit: mtime lies after clone/worktree, and the line
+  measures notes recency, not full ledger freshness. A missed capture is visible at
+  the next session's start.
+- **`test_kb_capture.py`** — kb-only battery module (doctrine anchors + the five
+  recency states), outside the shared x3 manifest.
+- Eval scenarios `capture_channels_the_days_decisions.md` and
+  `capture_stays_silent_with_nothing_to_record.md` (the negative branch: "niente"
+  writes nothing).
+
+F-039 — the recall reflex (second-brain unit 1): the graph is read when answering,
+not only written when distilling.
+
+### Added
+- **`SKILL.md` §Topic Recall — the answer-side consult.** Whenever a reply would
+  assert facts about the project's domain, the topic index is scanned and the descent
+  (`taxonomy.md` §6, new) runs in answer mode — plausibility of coverage is judged ON
+  the scanned index, never before it. Four declared verdicts (claims cited / node
+  matched no claims, surfacing `gaps:` / no coverage / index absent + regenerate),
+  emitted only when the recall ran; never faked. Once per topic per session.
+- **The anti-echo re-touch rule.** A DERIVED claim that grounds a decision has its
+  chain walked to non-DERIVED ground (GIVEN artifact, ELICITED or RULING note) and
+  that ground cited; an unresolvable ground marks the claim unverified for
+  decision-grounding — surfaced, never silently cited. IMPORTED grounding a decision
+  is named as un-re-ratified foreign authority.
+- **By construction: kb `orient` appends the topic router.** The overlay special-cases
+  `orient` (raw argv forwarded to the spine, never re-parsed) and appends the top of
+  `topics/INDEX.md` — or `index absent (N node files)` with the regenerate command —
+  so every session opens with the graph in sight. Fails open; spine untouched.
+- **`test_kb_recall.py`** — new kb-only battery module (doctrine anchors + orient
+  interception), deliberately outside the shared x3 manifest.
+- **`run_behavioral.py` fenced-block seeding** — a scenario setup entry ending in `|`
+  takes its file body from the following fenced block (common-dedented), so claims
+  tables and frontmatter'd nodes can be seeded; one-line entries unchanged.
+- Eval scenario `recall_descends_before_answering.md`.
+
+## [1.6.0] - 2026-08-26
+
+F-038 — the gated rung: truthful log vocabulary and a mandated ask, no grant memory.
+
+### Fixed
+- **A review rung that exists behind a permission policy is no longer logged as
+  "unavailable".** The ladder knew two states (the client supports the rung, or not)
+  and hard-coded rung 3's reason as "no subagent facility on this client" — so a gated
+  facility produced false log rows, and the ladder's own prohibition ("rung 3 is
+  illegitimate wherever rung 1 or 2 exists") was unsatisfiable on a gated client: the
+  agent could not obey it without asking, and no rule said to ask.
+
+### Added
+- **The gated-rung stop.** At a due review gate (design; closure), when the best rung is
+  permission-gated (a standing policy — an interactive per-call prompt is NOT this) and
+  no ungated rung works (a working one-shot CLI pre-empts the stop; a gated rung 2 joins
+  the question instead), the gate stops and asks ONE question in the five-bullet blocking
+  form: the gated rung(s) vs the fallback, each higher rung's status, the quoted policy,
+  the cost (~130-175k subagent tokens per deep review, measured 2026-08) AND what
+  independence last bought, and what stays blocked. **No grant memory**: the answer holds
+  while the conversation does; an agent that cannot recall a grant asks again. Unattended
+  runs never emit the question — rung 2 is still owed a try, then rung 3 with its reason.
+  (Successor to a design CANCELLED at the review cap after grant memory failed three
+  ways; rulings r18/r19.)
+- **The reason words.** A below-rung-1 row says why the rung(s) above did not run:
+  `absent` (the client has no such facility — a claim about the client, never a policy),
+  `gated, declined`, `gated, unattended`, `gated, pre-empted` (nothing asked — an
+  ungated lower rung ran the review). A rung-1 row owes nothing. For rung 3 this
+  re-words an existing duty; for rung 2 it is a new one-word duty, disclosed and
+  accepted with the rest.
+
 ## [1.5.1] - 2026-08-25
 
 ### Fixed

package/README.md

@@ -20,6 +20,10 @@ Two axes are kept apart on purpose — **abstraction** (a topic made of topics:
 
 5. **Escalation in one batch at the end of the run**, in legal form (the claims, the reopenable sources, the dates, why the machine cannot decide). Ingestion never stops to interrogate you.
 
+6. **Recall — the graph is read when answering, not only written when distilling.** Whenever a reply would assert facts about the project's domain, the agent scans the topic index and descends before answering from model memory — plausibility of coverage is judged ON the scanned index, never before it. Answers cite claim ids; a superseded claim is never cited without its successor; the verdict is declared only when the recall ran (`kb: <slug> → N claims cited`, a matched node with no claims surfaces its `gaps:`, and a missing index is reported as index-absent — not as a missing graph — with the regenerate command). When a DERIVED claim grounds a decision, its chain is walked to non-DERIVED ground (the given artifact or the elicited/ruled note) and that ground is cited — re-reading the agent's own synthesis is the echo chamber this rule exists to break. By construction, not exhortation: the kb `orient` opens every session with the topic router in sight.
+
+7. **Capture — the day's decisions reach the ledger before they evaporate.** At a user-signed closing ("chiudiamo"), one sweep question — carrying its own inline result: "today I recorded X and Y — any other decisions from today?" — reaches even the decisions taken outside the session, which no transcript search could find. What surfaces lands on the existing rails (an elicited dated note, an L1 claim row) with explicit provenance; the sweep is idempotent (nothing captured twice), never creates topics, and stays silent when no one signed off. The kb `orient` shows notes recency at every session start — dated from note frontmatter, because file mtimes lie after a clone or worktree — so a missed capture is visible the next morning.
+
 Deliberately absent: any per-node coverage or completion state. `gaps:` says what a node lacks; nothing collects it into a dashboard. A **source** does record how far it has been read, but on its own sidecar and nowhere else — the corpus index prints that fact for every artifact, including the finished ones, because a list of only what is behind is the dashboard this method refuses.
 
 ## Key features

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "kb-agentic-skill",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "description": "Knowledge-Base & Document-First protocol with risk triage, Vision governance, signal distillation and optional devPNT integration.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/kb-agentic-skill",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "description": "Knowledge-Base & Document-First protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, signal distillation and optional devPNT integration.",
   "keywords": [
     "claude-code",

package/skills/kb-agentic-skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: kb-agentic
-version: 1.5.1
-description: Knowledge-Base & Document-First protocol with risk-proportional triage, Vision as a guide, Signal Distillation, a complete Standalone mode and optional symbiosis with devPNT. Use for user documentation, knowledge extraction, SOPs, research notes, decision logs and knowledge management.
+version: 1.7.0
+description: Knowledge-Base & Document-First protocol with risk-proportional triage, Vision as a guide, Signal Distillation, a complete Standalone mode and optional symbiosis with devPNT. Use for user documentation, knowledge extraction, SOPs, research notes, decision logs, knowledge management — and for answering project questions from the claim ledger and topic graph.
 author: Antonio Pinto (https://github.com/Antoneeo)
 copyright: (c) 2026 Antonio Pinto
 ---
@@ -15,7 +15,7 @@ This skill guides knowledge management and documentation with a Document-First p
 Support files in the skill directory:
 - `templates.md`: templates for Vision, Knowledge ANALYSIS, Research SPIKE, SOP GUIDE, audit plan, and handoff.
 - `portability.md`: carrying knowledge between projects — what a bundle is, why export is a closure rather than a selection, and the rule that knowledge crosses a project boundary while authority does not (`prov: IMPORTED`). Read before `export`/`import`.
-- `taxonomy.md`: placing a claim in the topic graph — descent over the generated index, the five verdicts (EXISTS / INADEQUATE / MISSING / GENERALIZES / UNPLACED), the sibling rule, guarded re-parenting, canonicalization. Run at L3 before drafting.
+- `taxonomy.md`: placing a claim in the topic graph — descent over the generated index, the five verdicts (EXISTS / INADEQUATE / MISSING / GENERALIZES / UNPLACED), the sibling rule, guarded re-parenting, canonicalization — and the answer-mode descent (`§6`). Run at L3 before drafting.
 - `guides.md`: pipeline for distilling user-provided indications into `ai_docs/reference/GUIDE_[topic].md`.
 - `vision.md`: how to write a Vision a cold reviewer can actually apply — the properties that make a rule hold, the minimum operable sections, and the blind check.
 - `distillation.md`: from a source to claim rows — intake (content-addressed originals, stored canonical extraction, every provenance a real file), the claim table, extraction discipline, signal rules (symbiosis with `distill`).
@@ -35,7 +35,7 @@ Read these files only when needed. `SKILL.md` is the operating contract; the sup
 - **Signal & Distillation:** eliminate fluff, filler, and speculative statements; keep deterministic facts, constraints, decisions, and clear SOP steps (symbiosis with `distill`).
 - **Lifecycle & Freshness:** mark superseded knowledge (`status: SUPERSEDED` or `DEPRECATED`) so outdated information does not cause hallucination.
 - **Protect the Vision & User Style:** align all knowledge work with user strategic goals, operational preferences, and expected outcomes.
-- **Map-First Navigation:** rely on `ai_docs/README.md`, `INDEX.md`, and `reference/INDEX.md` router for targeted retrieval before creating new documents.
+- **Map-First Navigation:** rely on `ai_docs/README.md`, `INDEX.md`, and `reference/INDEX.md` router for targeted retrieval before creating new documents — and before *answering from model memory* on the project's domain (`## Topic Recall`).
 
 ## Rule Zero: Triage
 
@@ -90,6 +90,7 @@ Triage decides IF documentation is due; this table decides WHICH document each e
 | a KB bundle (`export`) | Knowledge must leave this project. Export is L1 — it writes nothing into the corpus. **Importing one is L3**: a source enters the corpus and nodes are created, and a bundle is external input, so never L1 whatever its size (`portability.md`). | — |
 | `corpus/given/*` + sidecar | A source arrives: it becomes a content-addressed artifact with a sidecar carrying digest/date/`supersedes:`. A text source is copied verbatim. A non-text source yields its stored canonical extraction — copied **beside** the original when that is small enough to keep, or **instead of it** on a large binary corpus, where the original stays where it lives and is recorded as `original_path:`/`original_sha256:` (`distillation.md` §1, which owns this rule). Never edited after ingest — the digest check on whatever `given/` holds is what enforces it. | 4 |
 | `corpus/notes/*` | Something is said (`origin: elicited`), synthesised (`derived_from:`), or ruled (`basis:`). A note with none of the three is refused by the validator. | 4 / 5 |
+| the day's decisions, at a user-signed closing (the Capture Moment sweep) | Verification that the phase-4 notes/claims exist; NEW `corpus/notes/*` + claim rows only for what the sweep surfaces un-captured. The event is the CLOSING, disjoint from the row above (which fires when something is SAID). | 5 / session end |
 | `solutions/PLAN_[topic].md` + its ledger | A source too long for one context is ingested: **one task per reading window** (30 pages by default; the plan states the window used), each ending at a declared `extracted_through:`. That ledger is the register the ingestion resumes from across sessions — ingestion never builds a second one (`distillation.md` §3, `templates.md`). | 4 |
 | `corpus/given/*.meta.md` — `extracted_through:` | Every reading window closes by advancing it (`p=<n>`, `L<n>`, `complete`). Required once any claim cites the artifact: unstated, "I am finished" cannot be falsified, which is how a sampled 200-page manual passes for an ingested one. | 4 |
 | `INDEX.md`, `reference/INDEX.md`, `topics/INDEX.md`, `corpus/INDEX.md` | Regenerated by `sdlc_check.py index` at closure — never by hand; `validate` fails on a hand-edited one. | 5 |
@@ -120,7 +121,7 @@ Use this mode when `devpnt_*` tools are available and point at the current proje
 - Run spec elicitation round (`elicitation.md`) before drafting analysis.
 - Run taxonomy pass (`taxonomy.md`): verify whether topics, categories, or SOPs already exist in `ai_docs/`. Avoid duplication.
 - Create or update `ai_docs/solutions/ANALYSIS_[topic].md`.
-- **Design review gate (end of Phase 3, before any drafting):** the analysis is reviewed by somebody other than its author — a subagent with fresh context, or a declared self-pass when none is available. Follow `review.md`; log the outcome in `audit/reviews/REVIEW_LOG.md`. A knowledge structure reviewed only by the person who chose it is not reviewed.
+- **Design review gate (end of Phase 3, before any drafting):** the analysis is reviewed by somebody other than its author — a subagent with fresh context, or a declared self-pass when no higher rung is usable — a permission-gated rung is asked about, never silently skipped (`review.md`). Follow `review.md`; log the outcome in `audit/reviews/REVIEW_LOG.md`. A knowledge structure reviewed only by the person who chose it is not reviewed.
 
 ### 4. Knowledge Processing & Distillation
 - **Isolate the work (Branch/worktree hygiene).** Distillation rewrites existing notes: do it on a branch or a worktree, never directly on the shared corpus, so a half-finished reconciliation is never what the next reader finds.
@@ -142,6 +143,106 @@ Guides are consulted, created, and distilled per `guides.md`.
 - **Propose proactively**: when the user hands over indications that will govern future work, propose distilling them into a guide. A proposal, never a silent write, and never from model knowledge — a guide's whole value is that every claim traces to what the user actually provided.
 - Distill from user instructions into `ai_docs/reference/GUIDE_[topic].md`.
 
+## Topic Recall — the answer-side consult
+
+The graph is only a second brain if it is READ when answering, not only written when
+distilling. The descent (`taxonomy.md`) fires here with a new trigger — the answer-side
+twin of the guide consult above.
+
+- **Trigger — unconditional scan on domain assertions.** Whenever the reply would assert
+  facts about the PROJECT'S domain (its topics, decisions, sources, constraints), scan
+  `topics/INDEX.md`. Plausibility of coverage is judged ON the scanned top rows, never
+  before them — "the KB probably doesn't have this" is model memory talking, the exact
+  judgement this reflex removes. Exempt: pure mechanics (running a command, editing per
+  explicit instruction), general knowledge outside the project's domain, L1 gestures.
+- **Once per topic per SESSION.** The dedup key is the matched slug (known ex post); a
+  question plainly within an already-descended branch reuses that consult, and a
+  placement descent already run this session counts. A compaction starts a new session.
+- **The act.** Descend per `taxonomy.md` §6 (same doctrine, answer mode). On claims,
+  answer FROM them citing claim ids; a claim whose `state` is `SUPERSEDED <id>` is never
+  cited without naming its successor.
+- **The declared verdict — only when the recall ran**, never a per-turn ritual. Four
+  legal values:
+  - `kb: <slug> → N claims cited`
+  - `kb: <slug> → node matched, no claims` — surface the node's `gaps:` when it answers
+    the question: "the KB knows it doesn't know" is a first-class answer.
+  - `kb: no coverage` — index read, nothing fits.
+  - `kb: index absent — regenerate (sdlc_check.py index)` — the INDEX is missing, not
+    necessarily the graph (nodes routinely exist while the index lags); regenerate and
+    rescan.
+  Never fake the verdict: an always-"no coverage" verdict certifies a lookup that did
+  not happen. The `router:` and `kb:` verdicts are independent and may co-occur, one
+  line each — a how-to question can match a guide AND carry claims.
+- **Anti-echo — the re-touch rule.** When a DERIVED claim grounds a decision the user is
+  about to take, walk its chain to non-DERIVED ground — a GIVEN artifact, an ELICITED or
+  RULING note — and cite that ground beside the claim id; re-opening only the immediate
+  target may re-read the agent's own synthesis, which is the echo chamber itself. If the
+  ground does not resolve (imported bundle without originals, external `original_path:`,
+  tombstone): say so beside the claim id and treat the claim as **unverified for
+  decision-grounding** — surfaced, never silently cited. Per-provenance stance: GIVEN's
+  source column is already the direct citation; ELICITED/RULING carry the practitioner's
+  own authority; an IMPORTED claim grounding a decision is named as un-re-ratified
+  foreign authority.
+- **The trace persists.** When the decision is recorded (a ruling note, a diary entry),
+  that record cites the claim id AND the re-touched ground — the trace survives in the
+  corpus, not in ephemeral chat.
+- **Under dispatch**, recall is an orchestrator concern: the orchestrator runs the
+  descent itself; a context-free subagent never runs its own. The task schema has no
+  claims field today, so until a dispatch-focused unit adds one, the orchestrator
+  inlines the cited claim rows in the task's free text — an explicit interim.
+
+## The Capture Moment — the day's decisions reach the ledger
+
+Capture today is what makes recall honest tomorrow: a captured elicited or ruled note
+is exactly the non-DERIVED ground the re-touch rule above walks to. The rails all
+exist — this section adds only the MOMENT.
+
+- **When — user-signed closings, once per session.** Phase 5 of a governed unit, or
+  any closing signal from the user in an un-governed session ("chiudiamo", "we're
+  done"); the session-end pass that updates `handoff.md`/`project_notes.md` then runs
+  at that same closing. Never per-turn, never a standing interruption. **Declared
+  residual**: an unsignaled end (the user simply stops writing) captures nothing —
+  the phase-4 duty (a decision stated mid-session owes its note WHEN SAID) is the
+  protection for sessions that never close, and the orient's recency line makes the
+  miss visible next time. That line measures NOTES recency, not full ledger
+  freshness, and trusts frontmatter `date:` over file mtimes — mtimes lie after a
+  clone or worktree.
+- **The sweep question.** At the closing, ONE question, carrying its own search
+  result inline: "today I recorded: [what the sweep found already on the rails] —
+  any other decisions from today to record?". Scoped to TODAY, so it reaches
+  decisions taken outside the session (a meeting, a call) that no transcript search
+  could find — facts only the practitioner owns. This is a **scheduled elicitation**
+  in the same family as the phase-3 round, not a blocking question (nothing stalls;
+  the session is ending), so the blocking form does not attach; the inline result
+  satisfies the search-first duty. "Niente" ends it.
+- **The sweep is idempotent.** It verifies the day's decisions are on the rails; a
+  decision already noted at phase 4 is verified, never re-captured — no second note,
+  no duplicate claim row. The moment closes gaps; the phase-4 row stays the primary
+  channel.
+- **What counts as a decision**: domain choices made or confirmed today — a value, a
+  threshold, a rule, a stated preference, a rejected alternative with its reason.
+  NOT mechanics (commands run, files edited), NOT process state (the handoff's job).
+- **The channeling — existing rails, explicit provenance.**
+  - The user's words → `corpus/notes/*` with `origin: elicited` and a `date:`; a
+    claim row distilled from it carries `prov: ELICITED`, source = that note with a
+    legal `L<a>-<b>` locator.
+  - A synthesis of the day's discussion → a note with `derived_from:` → claim
+    `prov: DERIVED`.
+  - **RULING only when the decision resolves an existing contested set** — then
+    `reconciliation.md` §2 applies in full (mandatory `basis:`, supersession of the
+    whole prior set). A fresh conflict-free decision is captured elicited: a preference
+    is not a fact, and `basis:` is reserved for the fact the corpus lacks.
+  - A fact on an existing topic → claim row, L1 (`id` empty; `claim-id --fill`).
+  - No owning topic → the note is written NOW and the placement is declared as the
+    next kb unit. Capture never smuggles an L3 hierarchy change, and
+    `topics/unplaced.md` is never a decision park — UNPLACED is for topic-less
+    scraps and is invisible to recall.
+- **Reconciliation is wired.** A captured claim meeting an existing claim on the
+  node classifies per `reconciliation.md` — capture can confirm, refine, coexist or
+  CONTEST, never silently overwrite.
+- **Silence stays legal where no one signed off**: no closing signal → no question,
+  no ritual line.
+
 ## Mechanical Enforcement
 - `scripts/sdlc_check.py index`: updates `ai_docs/INDEX.md` and `ai_docs/reference/INDEX.md`.
 - `scripts/sdlc_check.py validate`: validates YAML frontmatter (`status`, `description`).

package/skills/kb-agentic-skill/dispatch.md

@@ -1,96 +1,98 @@
-# Subagent Execution Discipline
-
-Opt-in orchestration for L3 work with an approved design: the orchestrator
-drives a `PLAN_[feature].md` through subagents instead of implementing every
-task in the same session. Default stays same-session; this is an escalation,
-never a requirement.
-
-## Trigger
-
-Only for L3 (an approved E-TDD in Hybrid, or an ANALYSIS Action Plan in
-Standalone). Never for L1/L2 — the plan/ledger machinery is overhead a small
-change does not need. The plan is always `derived-from` the accepted design:
-it is never independently authored, exactly like an E-TDD is never authored
-without an E-ISP.
-
-## The loop
-
-1. `sdlc_check.py plan validate PLAN_[feature].md` — zero-execution schema +
-   confinement + ledger cross-check. Non-zero exit = **no dispatch**. This is
-   the hard gate: "no valid plan, no dispatch."
-2. For each task, in plan order:
-   - Read the task's status from the sidecar ledger
-     (`PLAN_[feature].ledger.json`). `status: done` (exact sentinel) → skip,
-     never re-dispatch. Anything else (pending, failed, missing, or a
-     corrupt-but-parseable entry) → treat as pending and dispatch.
-   - `sdlc_check.py plan brief PLAN_[feature].md --task <id>` — prints the
-     task block, the `produces` of prior-order tasks (interfaces), and
-     `guides` pointers (paths, never pasted content) to stdout.
-   - Spawn the subagent with that brief as its entire context window.
-   - Run `task.verify` out of band (the orchestrator executes it — the
-     validator only ever prints it, never runs it) plus the one-shot review
-     below.
-   - Write `{status, verify_result, timestamp}` back to the ledger. The
-     validator never writes the ledger — single-writer, orchestrator-owned.
-
-**Guide consumption under dispatch.** Selecting each task's `guides` field IS the
-consult trigger (`guides.md` §0) applied at plan-authoring time: the orchestrator
-runs the router lookup (project router `ai_docs/reference/INDEX.md` + the agent-KB
-router) when populating `guides`. A dispatched context-free subagent does **NOT**
-run its own router consult — it reads the guide pointers handed to it in the
-brief. The router verdict (Rule Zero) is therefore declared ONCE, by the
-orchestrator, when it authors the plan; a dispatched subagent does not declare
-one. (Proactive guide-creation stays at closure — the same broad final pass
-below — so it needs no separate dispatch hook.)
-
-## Model tiers (client-relative, no provider names)
-
-- Default dispatch: **economy** implementer tier.
-- After **two** consecutive `verify_result: fail` on the same task: escalate
-  to the **deep** tier for the retry (ADR 2026-07-02). Do not escalate on the
-  first failure — a single fail is often a brief or environment issue, not a
-  capability gap.
-
-## Review slots — one-shot, not iterative
-
-Exactly three review touches per task, never a loop:
-
-1. Inline self-review by the implementer subagent before it reports done
-   (the standard critical-review pass, not a separate call).
-2. One reviewer pass per task (Hybrid: reuse the devPNT code-review gate;
-   Standalone: the `review.md` discipline).
-3. One broad final pass over the whole plan at closure, after all tasks are
-   DONE — catches cross-task drift a per-task review cannot see.
-
-If a review FAILs, fix and re-run `verify` — that is a normal loop iteration
-via the ledger's fail path, not an extra review slot.
-
-**The scoped re-review is a round INSIDE slot 2 or 3, never a fourth slot.**
-`review.md` §Receiving requires every review-driven correction to be
-re-reviewed against the correction alone — that round belongs to the slot whose
-findings caused it, and is bounded by the same cap of 3 rounds. "Never a loop"
-bounds the SLOTS (no unbounded re-reviewing of a task), not the rounds inside
-one slot: a fix nobody looked at is the defect the round exists to catch. Slot 1
-is the implementer's own pass, not an independent review, so its fixes carry no
-re-review round. The ledger records the round on the task's fail path as usual.
-
-## Ledger protocol summary
-
-Read → skip-if-done → dispatch-if-pending → write. The ledger is the only
-memory the loop needs across sessions or context compaction: a resumed
-orchestrator re-reads it and picks up exactly where it left off, never
-re-running a DONE task.
-
-## Degradation
-
-No subagent-spawning tool available → the orchestrator runs each task in the
-same session, against the same plan and ledger, with the same one-shot review
-slots. No capability is lost, only the parallelism/isolation subagents would
-have added.
-
-## Hybrid note
-
-The plan's `derived-from` points at the accepted E-TDD document key. Per-task
-review reuses the devPNT independent reviewers (§4.6 code review gate) rather
-than restating review doctrine — see `review.md` for the single definition
-both modes share.
+# Subagent Execution Discipline
+
+Opt-in orchestration for L3 work with an approved design: the orchestrator
+drives a `PLAN_[feature].md` through subagents instead of implementing every
+task in the same session. Default stays same-session; this is an escalation,
+never a requirement.
+
+## Trigger
+
+Only for L3 (an approved E-TDD in Hybrid, or an ANALYSIS Action Plan in
+Standalone). Never for L1/L2 — the plan/ledger machinery is overhead a small
+change does not need. The plan is always `derived-from` the accepted design:
+it is never independently authored, exactly like an E-TDD is never authored
+without an E-ISP.
+
+## The loop
+
+1. `sdlc_check.py plan validate PLAN_[feature].md` — zero-execution schema +
+   confinement + ledger cross-check. Non-zero exit = **no dispatch**. This is
+   the hard gate: "no valid plan, no dispatch."
+2. For each task, in plan order:
+   - Read the task's status from the sidecar ledger
+     (`PLAN_[feature].ledger.json`). `status: done` (exact sentinel) → skip,
+     never re-dispatch. Anything else (pending, failed, missing, or a
+     corrupt-but-parseable entry) → treat as pending and dispatch.
+   - `sdlc_check.py plan brief PLAN_[feature].md --task <id>` — prints the
+     task block, the `produces` of prior-order tasks (interfaces), and
+     `guides` pointers (paths, never pasted content) to stdout.
+   - Spawn the subagent with that brief as its entire context window.
+   - Run `task.verify` out of band (the orchestrator executes it — the
+     validator only ever prints it, never runs it) plus the one-shot review
+     below.
+   - Write `{status, verify_result, timestamp}` back to the ledger. The
+     validator never writes the ledger — single-writer, orchestrator-owned.
+
+**Guide consumption under dispatch.** Selecting each task's `guides` field IS the
+consult trigger (`guides.md` §0) applied at plan-authoring time: the orchestrator
+runs the router lookup (project router `ai_docs/reference/INDEX.md` + the agent-KB
+router) when populating `guides`. A dispatched context-free subagent does **NOT**
+run its own router consult — it reads the guide pointers handed to it in the
+brief. The router verdict (Rule Zero) is therefore declared ONCE, by the
+orchestrator, when it authors the plan; a dispatched subagent does not declare
+one. (Proactive guide-creation stays at closure — the same broad final pass
+below — so it needs no separate dispatch hook.)
+
+## Model tiers (client-relative, no provider names)
+
+- Default dispatch: **economy** implementer tier.
+- After **two** consecutive `verify_result: fail` on the same task: escalate
+  to the **deep** tier for the retry (ADR 2026-07-02). Do not escalate on the
+  first failure — a single fail is often a brief or environment issue, not a
+  capability gap.
+
+## Review slots — one-shot, not iterative
+
+Exactly three review touches per task, never a loop:
+
+1. Inline self-review by the implementer subagent before it reports done
+   (the standard critical-review pass, not a separate call).
+2. One reviewer pass per task (Hybrid: reuse the devPNT code-review gate;
+   Standalone: the `review.md` discipline).
+3. One broad final pass over the whole plan at closure, after all tasks are
+   DONE — catches cross-task drift a per-task review cannot see.
+
+If a review FAILs, fix and re-run `verify` — that is a normal loop iteration
+via the ledger's fail path, not an extra review slot.
+
+**The scoped re-review is a round INSIDE slot 2 or 3, never a fourth slot.**
+`review.md` §Receiving requires every review-driven correction to be
+re-reviewed against the correction alone — that round belongs to the slot whose
+findings caused it, and is bounded by the same cap of 3 rounds. "Never a loop"
+bounds the SLOTS (no unbounded re-reviewing of a task), not the rounds inside
+one slot: a fix nobody looked at is the defect the round exists to catch. Slot 1
+is the implementer's own pass, not an independent review, so its fixes carry no
+re-review round. The ledger records the round on the task's fail path as usual.
+
+## Ledger protocol summary
+
+Read → skip-if-done → dispatch-if-pending → write. The ledger is the only
+memory the loop needs across sessions or context compaction: a resumed
+orchestrator re-reads it and picks up exactly where it left off, never
+re-running a DONE task.
+
+## Degradation
+
+No subagent-spawning tool available — absent, or permission-gated with no grant
+in context (`review.md`'s gated-rung stop owns the asking; task dispatch never
+asks; the broad final pass IS `review.md` moment 2 and asks there) → the
+orchestrator runs each task in the same session, against the same plan and ledger,
+with the same one-shot review slots. No capability is lost, only the parallelism/isolation subagents would
+have added.
+
+## Hybrid note
+
+The plan's `derived-from` points at the accepted E-TDD document key. Per-task
+review reuses the devPNT independent reviewers (§4.6 code review gate) rather
+than restating review doctrine — see `review.md` for the single definition
+both modes share.

package/skills/kb-agentic-skill/elicitation.md

@@ -21,8 +21,10 @@ record is reviewable; a guess folded silently into a design is not.
 ## The question discipline
 
 A question to the practitioner spends their attention and stalls the work; the
-round below is the only place the process *plans* that cost. Everywhere, a
-question is legal only when BOTH hold:
+process *plans* that cost in exactly two places — the round below, and the
+Capture Moment sweep at a user-signed closing (`SKILL.md`), a scheduled
+elicitation in the same family that carries its search result inline and stalls
+nothing. Everywhere, a question is legal only when BOTH hold:
 
 1. **Searched first, and the search is named — with its result.** The answer is
    not on record and not derivable from the corpus, the topic graph, `ai_docs/`,

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

@@ -12,7 +12,7 @@ Two moments, and they review different things:
 |---|---|---|---|
 | **1. Design review** | End of Phase 3 — **before any implementation** | the ANALYSIS (Standalone) / the `E-ISP`+`E-TDD` (Hybrid) | L3 |
 | **1b. Late arrival** | Work that became L3 *after* code existed — an L1/L2 reclassified mid-flight, or a design increment on a feature already implemented — runs moment 1 **now**, before any further implementation, logged `design (late)` | same | L3 |
-| **2. Closure review** | Phase 5, before DONE | the actual diff, against that approved design | L2 / L3 — the L2 row is optional |
+| **2. Closure review** | Phase 5, before DONE | the actual diff, against that approved design | L2 / L3 — the L2 closure review is optional; every review that runs logs its row |
 
 **Why the design review is its own moment, and not a nicety.** The closure review
 can only tell you the code matches the design; it cannot tell you the design was
@@ -30,17 +30,56 @@ blind to it, which is why independence, not effort, is what this gate buys.
    a SELF-CONTAINED prompt — the reviewer session has no other context, which is
    exactly what makes it independent.
 3. **A declared self-pass** — a separate, explicitly adversarial pass by you,
-   against the same checklist. **Rung 3 is illegitimate wherever rung 1 or 2
-   exists**: on a client with a subagent facility or a one-shot CLI, descending to
-   it is choosing zero independence, which is the one thing this gate buys. When
-   you do use it, the log row must carry *why* — `self-pass (declared; no subagent
-   facility on this client)` — not merely that you did. A rung named without its
+   against the same checklist. **Rung 3 is illegitimate wherever a higher rung
+   is usable**: on a client with a working subagent facility or one-shot CLI,
+   descending to it is choosing zero independence, which is the one thing this
+   gate buys. A gated rung the user DECLINED is not usable — see *The gated
+   rung* below; a gated rung nobody asked about is not declined (unattended is
+   its own case below). When
+   you do use it, the log row must carry *why*, in the reason words below —
+   `self-pass (declared; absent — the client has no such facility)` — not merely
+   that you did. A rung named without its
    reason is indistinguishable from a rung chosen for convenience.
 
 Rung 3 stays in the ladder deliberately: it is what keeps the methodology
 completable with no network, no account and no subagent facility. It is a floor,
 never a default.
 
+**The gated rung — present is not absent (F-038).** A rung that exists behind a
+standing policy or instruction forbidding its use absent a user request is
+**permission-gated**, not unavailable. An interactive per-call approval prompt is
+NOT this: answering the prompt IS the grant. With an ungated rung usable — rung 1
+free, or a one-shot CLI that works (try it, or show it failed) — the prohibition
+above is already satisfiable and no stop fires (the row still carries
+`gated, pre-empted` when a gated rung sat above the one that ran); a gated
+rung 2 is not "usable" for this clause, it joins the question instead. When the best rung is gated and no
+ungated rung works, the gate STOPS and asks: descending to rung 3 on silence is
+illegal while a user is reachable. The stop is doctrine-mandated (legal by mandate,
+`elicitation.md` §Blocking is reserved) and carries that file's five-bullet
+blocking form — its closed-list exemption covers this file's round-cap hand-over
+only, not this stop. The question offers the gated rung(s) against the fallback, with what each
+buys; states each higher rung's status (tried / unusable / gated) with the
+standing instruction quoted and "no grant visible in my current context"; says
+why no assumption survives (assuming either way writes a false log row); says
+why it is the USER'S call — their tokens (~130-175k per deep review, measured
+2026-08) against a benefit only they can price, stated with what independence
+last bought; and names what stays blocked — which reviewer runs, nothing else.
+**No grant memory exists**: the answer holds while the conversation does, and an
+agent that cannot recall a grant asks again — one question per gate per intact
+context; re-asking is a smaller defect than a false row. Unattended
+(`elicitation.md`'s Unattended path — the user is not reachable), no question is
+emitted: rung 2 is still owed a try, then rung 3 runs with its reason logged.
+
+**The reason words.** A below-rung-1 row carries why the rung(s) above did not
+run; a rung-1 row owes nothing. `absent` — the client has no such facility (a
+claim about the client, never about a policy); `gated, declined` — usable only
+with the user's assent at this gate, and the user withheld it (a standing policy
+answered no, or a per-call prompt denied); `gated, unattended` — a standing policy
+gates it and no user is reachable to ask; `gated, pre-empted` — gated, nothing
+asked: an ungated lower rung ran the review instead. `gated` always appears with
+its outcome. The trigger term "permission-gated" scopes the STOP; the row word
+`gated` additionally covers a denied per-call prompt, which never triggers one.
+
 Use a different model from the author's where the client allows it.
 
 **Rounds are capped at 3.** FAIL → revise → re-review. If findings still stand

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

@@ -1491,6 +1491,113 @@ def kb_cmd_import(args):
     return 0
 
 
+def kb_cmd_orient(argv):
+    """Forward `orient` to the spine untouched, then append the topic router.
+
+    The recall reflex (SKILL.md section "Topic Recall") needs the graph in
+    sight at session start -- by construction, not exhortation (F-039). The
+    spine's orient is never re-implemented here: the raw argv goes through
+    (the --help pattern below), and orient's flags are never mirrored into an
+    overlay argparse -- the drift class the forward-by-default comment warns
+    about. parse_known_args reads ONLY the two root flags the overlay itself
+    needs to locate topics/, and ignores everything else.
+
+    The append fails open: a broken graph read must never break orient itself.
+    """
+    try:
+        rc = sdlc_core.main(argv)
+    except SystemExit as e:
+        rc = e.code if isinstance(e.code, int) else 1
+    # Pre-bind so a throw INSIDE the router print (after root was validly
+    # bound) does not erase it -- the recency block below must survive a
+    # router failure with the bound root intact (closure R2 finding).
+    root = name = None
+    try:
+        probe = argparse.ArgumentParser(add_help=False)
+        probe.add_argument("--root")
+        probe.add_argument("--docs-dir")
+        known, _ = probe.parse_known_args(argv[1:])
+        try:
+            discovered, name = sdlc_core.resolve_docs_dir(known, known.root)
+        except sdlc_core.AmbiguousDocsRoot:
+            # Mirror the spine's degraded orient: fall back to the default
+            # docs dir rather than losing the router on a half-migrated tree.
+            discovered, name = None, sdlc_core.DEFAULT_DOCS_DIR
+        root = (Path(known.root).resolve() if known.root
+                else (discovered or sdlc_core.find_project_root()))
+        topics = root / name / "topics"
+        index = topics / "INDEX.md"
+        if index.is_file():
+            lines = sdlc_core.read_text(index).splitlines()
+            print("\n## Topic router")
+            cap = 30
+            for line in lines[:cap]:
+                print(line)
+            if len(lines) > cap:
+                print("(+%d more lines -- read topics/INDEX.md)" % (len(lines) - cap))
+        elif topics.is_dir():
+            nodes = [p for p in topics.glob("*.md") if p.name != "INDEX.md"]
+            if nodes:
+                print("\n## Topic router")
+                print("index absent (%d node files) -- regenerate: sdlc_check.py index"
+                      % len(nodes))
+        # no topics/ at all: the project has no graph; print nothing.
+    except (Exception, SystemExit):
+        # SystemExit included: the probe parser raises it on a dangling flag
+        # value -- the spine already reported that usage error; the append must
+        # never turn it into an escape. root/name keep whatever binding they
+        # reached: pre-binding throws leave them None (recency skips), a throw
+        # inside the router print leaves them valid (recency still runs).
+        pass
+    try:
+        # Notes recency (F-040) -- its OWN try, genuinely independent of the
+        # router: a router throw must not kill this line. It measures NOTES
+        # recency, not full ledger freshness (an ingest feeding claims from
+        # given/ leaves it unmoved). Date source: frontmatter `date:` first;
+        # per-note mtime as fallback -- mtime LIES after clone/worktree (the
+        # skill's own worktree hygiene makes that routine), which is why the
+        # frontmatter date is primary.
+        if root is None:
+            return rc
+        notes_dir = root / name / "corpus" / "notes"
+        if notes_dir.is_dir():
+            import datetime as _dt
+            newest = None
+            for p in notes_dir.glob("*.md"):
+                stamp = None
+                try:
+                    head = sdlc_core.read_text(p)[:600]
+                    # `date:` counts only INSIDE the frontmatter block: a
+                    # column-0 date: in a note's body must not misdate it.
+                    if head.startswith("---"):
+                        end = head.find("\n---", 3)
+                        if end != -1:
+                            m = re.search(r"^date:\s*(\d{4}-\d{2}-\d{2})",
+                                          head[:end], re.M)
+                            if m:
+                                stamp = _dt.date.fromisoformat(m.group(1))
+                except Exception:
+                    pass
+                if stamp is None:
+                    try:
+                        stamp = _dt.date.fromtimestamp(p.stat().st_mtime)
+                    except Exception:
+                        continue
+                if newest is None or stamp > newest:
+                    newest = stamp
+            if newest is None:
+                print("\nno notes yet (corpus/notes)")
+            else:
+                days = (_dt.date.today() - newest).days
+                print("\nnewest note: %d days old (corpus/notes)" % max(days, 0))
+    except (Exception, SystemExit):
+        # Fail-open: nothing in the recency append may break orient. (The
+        # probe parser lives in the router try above; this guard covers the
+        # date/mtime walk and the print itself.)
+        pass
+    return rc
+
+
 def kb_cmd_help():
     """The spine's usage, then the overlay's own commands.
 
@@ -1525,6 +1632,10 @@ def main(argv=None):
     # 2026-08-02). Intercepted at argv[0] ONLY.
     if argv and argv[0] in ("-h", "--help"):
         return kb_cmd_help()
+    # `orient` is special-cased BEFORE the overlay argparse, like --help: the
+    # spine runs it on the raw argv, the overlay only appends the topic router.
+    if argv and argv[0] == "orient":
+        return kb_cmd_orient(argv)
     # Forward-by-default: anything not intercepted goes to the spine untouched.
     # Never a hand-copied command tuple - that is how a spine command gets
     # silently dropped (mkt_check.py ships that exact defect with `migrate`).

package/skills/kb-agentic-skill/taxonomy.md

@@ -78,3 +78,12 @@ unreachable nodes as errors, but the refusal at write time is what prevents them
 A merged or renamed topic keeps its file: `status: SUPERSEDED`, `redirect_to: <slug>`,
 body emptied. Inbound references resolve through it; a claim re-placed from an old
 source lands on the survivor instead of resurrecting the dead slug.
+
+## 6. The same descent, answer mode
+
+The descent above also serves ANSWERING (`SKILL.md` §Topic Recall): when a reply would
+assert facts about the project's domain, descend before answering from model memory.
+Differences only — no placement verdicts, no writes; the descent stops at reading the
+matched node's claims; coverage (found / not found) replaces the five verdicts; UNPLACED
+does not exist when reading. Everything else applies unchanged: descend don't scan,
+follow every parent, synonyms, tombstone redirects resolve to the survivor.

package/skills/kb-agentic-skill/templates.md

@@ -448,7 +448,7 @@ adds values to the existing columns rather than a second table.
 | date | doc_key | tier | reviewer | findings_raised | findings_real | verdict | revise_rounds |
 |---|---|---|---|---|---|---|---|
 | 2026-06-11 | ANALYSIS_login_sso.md | design | subagent (opus, fresh ctx) | 4 | 3 | FAIL → PASS | 2 |
-| 2026-06-12 | diff feature/sso-login | closure | self-pass (declared; no subagent facility) | 2 | 2 | PASS with findings → corrections re-reviewed, PASS | 2 |
+| 2026-06-12 | diff feature/sso-login | closure | self-pass (declared; absent) | 2 | 2 | PASS with findings → corrections re-reviewed, PASS | 2 |
 
 ## Notes
 <!-- One short paragraph per review that found something worth remembering: what
@@ -463,9 +463,17 @@ and `closure` (Standalone); `deep`, `light`, `code`, `guide`, `vision` (devPNT g
 and the Vision blind check). The validator reads this column by its header name, so
 extra or reordered columns are fine — but the header must say `tier`. `reviewer`
 records the realization actually used — fresh subagent, one-shot client run, or a
-**declared** self-pass. Writing `self-pass` where independence was unavailable is
-honest; writing nothing, or implying independence you did not have, is the failure
-this column exists to prevent. `findings_real` is how many raised findings survived
+**declared** self-pass — and, for any rung below rung 1, WHY the rung(s) above did
+not run, in the ladder's reason words (`review.md`): `absent` — the client has no
+such facility (a claim about the client, never about a policy); `gated, declined` —
+usable only with the user's assent at this gate, withheld (a standing policy
+answered no, or a per-call prompt denied); `gated, unattended` — a standing policy
+gates it, no user reachable; `gated, pre-empted` — gated, nothing asked, an ungated
+lower rung ran the review. A rung-1 row owes nothing. `gated` here is the ROW
+word — it also covers a denied per-call prompt, which never triggers `review.md`'s
+stop. Writing `self-pass` with its
+true reason is honest; writing nothing, or implying independence you did not have,
+is the failure this column exists to prevent. `findings_real` is how many raised findings survived
 triage: over time it is the only evidence of whether the gate earns its cost.
 `revise_rounds` counts **review rounds**, not fix cycles: the first review is round 1
 and every scoped re-review adds one. A review that produced findings which were then