@antoneeo/course-creator 0.1.0-beta.1

package/skills/course-creator/dispatch.md

@@ -0,0 +1,140 @@
+# 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 plus the return-doubts line as its
+     entire context window. The line: "An open point whose answer changes the
+     work is not yours to decide: return it in your final output with what you
+     searched." The orchestrator treats them as its own candidate doubts
+     (`elicitation.md` §When a doubt emerges).
+   - 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. This is legal precisely
+  because a dispatched task carries `task.verify` — the threshold signal that
+  makes a wrong cheap answer visible. **The floor that governs every role, and
+  the rule that a tier may be lowered only where such a signal exists, is
+  `review.md` §The capability floor** — cited, never restated here.
+- 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.
+
+## What may be delegated at all
+
+The sections above govern the opt-in PLAN loop; **this one is family-wide** and
+applies to any pass, at any level, dispatch or no dispatch. Delegation is not a
+token-saving technique — a second context re-reads, re-briefs and reports back,
+so the total spend goes UP. What it buys is a main context that stays clean, and
+independence where independence is the point. Judge a pass on two axes:
+
+| | output falsifiable cheaply (`file:line`, an assertion result, a diff) | output is judgement |
+|---|---|---|
+| **reads ≫ report** | **delegate** — the whole win lives here | **never**: the biggest apparent win is where plausible-but-wrong enters |
+| **reads ≈ report** | keep it: the brief costs more than the pass | keep it |
+
+- **Delegate**: locating and verifying (a pass that returns citable facts and
+  discards its exploration trace), executing a probe or battery and reporting
+  the assertion table, and every independent review — the last for correctness,
+  not economy, and it is mandatory regardless of what it costs.
+- **Never delegate**: authoring a governed artifact (Vision, ANALYSIS/E-ISP,
+  threat model, use cases, the Interface Contract), the triage level and router
+  verdict, a reconciliation or scope decision, and any pass whose result the
+  orchestrator must hold across many later turns — delegating that one just
+  moves the reading into the main context via the report.
+- **The delegability condition**: a task whose brief cannot be expressed as
+  **pointers** — paths, ids, a command — is **not delegable** yet; a brief that
+  must carry the content pays those tokens twice, once to write it and once to
+  read it. `plan brief` is this rule already realized for the PLAN loop (it
+  prints `guides` as paths, never pasted content); the condition generalizes it.
+
+**Declared residual**, so the silence is not read as prohibition: this section
+settles the CLASSIFICATION. *When* to reach for a delegated search or
+orientation pass — the trigger, its brief format and its output contract — is a
+separate unit and is not answered here; until it lands, reaching for one is the
+orchestrator's judgement against the table above, not a rule.
+
+## 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/course-creator/elicitation.md

@@ -0,0 +1,196 @@
+# Spec Elicitation
+
+`## The question discipline` below governs EVERY doubt and EVERY question to the
+practitioner — any phase, any level, inside or outside the round. The rest of the
+file is the spec elicitation round: it applies when an L3 request enters phase 3 (Request
+Analysis), BEFORE drafting the ANALYSIS document (Standalone) or the D-UC/E-ISP
+(Hybrid).
+
+Skip path: if the spec is already complete — an approved Vision or explicit
+user requirements already answer goal, scope, and constraints — skip the
+round and add a one-line note in the analysis stating why it was skipped.
+Do not run the round as a formality when the answers are already on record.
+
+Unattended path: when the user is not reachable (a scheduled or autonomous run,
+and a bootstrap Vision is `DRAFT` by mandate, so the skip path above cannot
+apply on a project's first L3) and a real doubt remains, do not stall and do not
+invent consensus. Write it as a **declared assumption** (§Ask before the write)
+in the artifact it touches. At L3, mark the ANALYSIS `BLOCKED on the user` and
+stop before implementation; below L3, proceed and list the assumption in the
+reply. An assumption on the record is reviewable; a guess folded silently into a
+design is not.
+
+## The question discipline
+
+A doubt kept silent is decided by the agent alone and reaches the documents
+looking settled; a useless question wastes the practitioner's attention. This
+section rules on both. The process *plans* questions in two places — the round
+below, and the Capture Moment sweep at a user-signed closing (`SKILL.md`) — each
+a planned occasion that keeps its own form.
+
+### When a doubt emerges
+
+A **candidate doubt** is an open point whose answer changes what you write or
+record. The usual signals — they illustrate, they do not close the definition:
+
+| Thought | What it means |
+|---|---|
+| "They probably mean…", "I'll assume…" | you are choosing between readings of the request |
+| "The request doesn't say, so I'll fill it in" | a gap in scope, a non-goal, an acceptance criterion or a priority |
+| "Either would work, I'll pick one" | equivalent in effect: yours, pick and do not ask; different in effect: weigh them below |
+| "I'll note it as an assumption and move on" | with the practitioner reachable, that note is where doubts go to be forgotten |
+| "It's reversible, it can be fixed later" | later is after the documents built on it exist |
+
+- **A fact, or information only the practitioner holds** (a date, a figure, a
+  constraint): settled only by evidence, cited — never settled by a weighing. Left
+  open by the corpus and changing the work, it is a real doubt.
+- **A choice** — a reading of intent, a structuring trade-off: cite the
+  practitioner's statement that settles it (the request, an APPROVED Vision, an
+  earlier reply); failing one, weigh the pros and cons of each option, stating each
+  rejected option at its strongest — the need it serves best; a weighing won against
+  a weak version of the alternative is not a weighing. One clearly outweighs: take
+  it and write the weighing with the choice — "I take X over Z: pro …, contro …".
+  Balanced, or turning on a priority of theirs not on record: a **real doubt** — and
+  it turns on one whenever the options serve different needs of the actor, each
+  better at one the actor would notice in using the result (a quick answer against
+  a complete record) and
+  none good enough at both, and nothing the practitioner wrote ranks those needs —
+  however clear your own ranking feels. "The more natural reading" with no pros and
+  cons written is not a weighing. Reserved approvals never enter this test
+  (§The form of a question).
+
+### Ask before the write
+
+A real doubt that passes the legality test below is **owed**, not merely allowed:
+the test separates a doubt from a search not yet run, it never licenses silence.
+Ask it before the first write that would embed its answer, grouped with every
+doubt open at that point, in one numbered set, with the client's
+structured-question facility where it has one. Never defer a doubt to the
+deliverable, where the practitioner must find it inside the document; never drip
+one question per turn. Fold every answer into the artifact, citing the reply; an
+intent choice with neither a source nor a weighing is a finding (`review.md`
+§Reviewing).
+
+**Declared assumptions exist only where no question can be asked:**
+
+- **Unattended** — the practitioner is not reachable (the Unattended path above).
+- **Delegated** — their own words handed you this choice; quote them. A general
+  "go ahead" is not a delegation.
+
+Each states **what it is taken from** and **the alternative it excludes**, and is
+listed where the practitioner will read it — an assumption nobody is shown is a
+silent decision. A dispatched subagent returns its open points in its final output
+(`dispatch.md`); the orchestrator treats them as its own candidate doubts
+(§When a doubt emerges).
+
+### The legality test
+
+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/`,
+   the Vision or the conversation — and the question states the terms, tools and
+   areas you searched **and what they returned**. Same standard as a router
+   verdict or a taxonomy-pass MISSING, and it carries their floors: a search
+   whose scope does not cover the question is not a search; a hit you did not
+   open narrows nothing; and **never fake the search** — "I looked and found
+   nothing" that names no terms and no areas is a search not run. A question the
+   corpus can answer is a search outsourced to the practitioner.
+2. **It names what is blocked.** The question states the specific decision or
+   fact that cannot be resolved without the reply — what you will do differently
+   depending on the answer. If nothing downstream changes, there is no question.
+
+Never legal:
+
+- **Generic confirmation** — "shall I proceed?", "is this OK?". The process
+  authorizes proceeding; if a real risk motivates the ask, name the risk and the
+  fork — that is a blocking question and carries the form below.
+- **Preference-fishing** — asking the practitioner to pick among options that
+  are equivalent in their effect on the benefit and already decided by the
+  project's conventions. Cheapness to undo is NOT the test.
+- **Re-asking the record** — goal, scope or constraints that an APPROVED
+  Vision, an earlier reply, or the request itself already states; or a fact a
+  claim row already carries with its source.
+
+What questions are FOR — what the practitioner uniquely owns: the benefit,
+priorities between conflicting goods, non-goals, acceptance, the approvals
+doctrine reserves to them, and **rulings on contested claims — where their
+answer counts only as a fact they know (`basis:`), never as a preference**
+(`source_check.md` §Source conflicts). Facts about intent come from the practitioner; facts
+about the documents come from the corpus. **Precedence:** a choice the
+practitioner uniquely owns is never preference-fishing; the list above reaches
+choices that are *not* theirs.
+
+### The form of a question
+
+The approvals reserved above and every stop the doctrine mandates are asked
+whatever you expect the answer: **legal by mandate**, never weighed, never
+re-argued here. Unattended, they are never assumed: the work holds, unless the
+mandating rule prescribes its own unattended handling (`review.md`'s gated rung
+does).
+
+**Only `review.md`'s round cap prescribes its own hand-over**, the artifact plus
+the open findings. That list is closed. Source conflicts follow `source_check.md` §Source conflicts
+and use the general blocking form below; no unavailable KB procedure is needed
+for a Standalone course. A question outside the
+planned occasions carries the **blocking form**, one line per element:
+
+- the fork: the options, each with its pros and cons, and what each implies for
+  the work;
+- the evidence: what you searched, read or tried, and what it leaves undecided;
+- why no assumption survives — why the weighing does not settle it, and what a
+  wrong pick costs; a reserved approval or a mandated stop cites the approval or
+  the mandate instead;
+- why it is the practitioner's call;
+- what stays blocked until answered.
+
+## The round
+
+Ask ONE structured set of questions, not a drip of follow-ups. Keep each
+question short and numbered; offer concrete options where a real choice
+exists, each with its pros and cons (this narrows the reply and speeds up the
+round). Cover:
+
+1. **Goal / benefit** — what problem this closes and why now. The answer must
+   name what the actor *obtains*, not a mechanism: "a dashboard" is not an
+   answer to "never lose the thread" — ask again until it is a benefit
+   (`vision.md`: the Vision is the distilled benefit; solutions and preferences
+   are what gets filtered out).
+2. **Actors** — who interacts with this: their role, primary goal, and what
+   "good UX" means to them. These become the Vision's `## Actors`; each
+   use-case below attaches to one (actor = who they are, use-case = what
+   they do). Skip only when an approved Vision already names them.
+3. **Scope boundaries** — what is explicitly included in this unit of work.
+4. **Non-goals** — what is explicitly excluded, so scope does not silently
+   creep in later.
+5. **Constraints** — technical, compatibility, and security constraints that
+   bound the solution space.
+6. **Acceptance signals** — how you and the user will both recognize the
+   work is done and correct.
+
+## Reflect
+
+Fold the answers into the ANALYSIS `## Objective` / `## Vision-Alignment`
+sections (Standalone) or into the D-UC/E-ISP (Hybrid) — do not leave them
+sitting only in the chat transcript. The written document, not the
+conversation, is what the next session and the next reviewer will read.
+
+Run a second round only when an answer opens a real fork in the design (a
+genuinely new question the first round could not have anticipated). Do not
+run a second round to double-check answers that were already clear.
+
+## Anti-patterns
+
+- **Interrogation**: an endless list of questions, or drip-feeding one
+  question at a time across many turns instead of one structured round.
+- **Asking what the approved vision already answers**: re-asking goal or
+  non-goals that a `Status: APPROVED` Vision or M-VISION already states.
+- **Deferring a doubt into the document**: writing a guess into the artifact
+  and leaving the practitioner to find it there.
+- **Collecting answers without folding them in**: getting replies in chat
+  and proceeding to design without writing them into the analysis document —
+  the next reader has no record of why the scope is what it is.
+
+## Course-specific elicitation
+
+Ask which explanation should become possible for the named learner, what they already know with evidence, where they will use the knowledge, which surfaces they use today, and, when a tool or agent is involved, which acts are theirs and which the tool performs for them. Distinguish an unknown fact from an unknown learner prerequisite. Ask for the benefit before selecting modules.

package/skills/course-creator/feedback.md

@@ -0,0 +1,7 @@
+# Feedback, improvement and efficacy
+
+Read when feedback from a real learner or observed use arrives. The feedback channel is chosen in `D-IC.md`; do not create or imply a service. A learner can also report an issue through another identified route. Recover course version and module from context; ask only if still missing, then record the smallest context needed to understand the observation in `FEEDBACK_REPORT.md`.
+
+Classify the report: unclear explanation, missing prerequisite, wrong or stale fact, delivery barrier, weak check, indistinguishable learning value, incomplete source content, or an issue outside the course's promise. Trace it to the learner profile, concept, module objective, source and check. Propose a correction and state what evidence would show improvement. A single concrete report can justify a correction. If it exposes a reproducible defect in **the course-creation method**, distill the reasoning into a guide or propose a change to `course-creator` under Agentic SDLC; never rewrite the skill automatically.
+
+An efficacy claim needs criteria for the learner's understanding or use, observations from sufficiently comparable real learners, contrary outcomes and limits. No formal pilot is mandatory; naturally arriving feedback may supply evidence. An isolated positive comment and a simulated PASS do not. Keep the visible label `efficacy not verified` until the evidence supports a narrower, explicit statement. Review privacy and retention before storing learner details; no continuing personal register is part of this method.

package/skills/course-creator/guides.md

@@ -0,0 +1,291 @@
+# Operative Guides — pipeline
+
+Support file for `ai_docs/reference/GUIDE_[topic].md`. Read this only when the
+trigger below fires; the template lives in `templates.md`.
+
+**The training model (what a guide IS).** A guide TRAINS the agent on a topic
+the user cares about, the way training works for a person: you study the
+material once, you carry a SYNTHESIS in your head, and you go back to the book
+when a task needs detail. Two levels, both produced by this pipeline:
+- **The guide = the synthesis** — compact and dense: core principles, decision
+  rules, the map of what exists, where people go wrong. Small enough that a
+  reader takes it in WHOLE before acting (that is the "preparation").
+- **The snapshot = the book** (`.sources/`, verbatim) — the details live here,
+  reachable on demand.
+- **The fidelity markers are the bridge**: `[source: <snapshot>#anchor]` both
+  proves provenance AND tells the reader where in the book the full detail is.
+A guide that restates the source at length is as wrong as a fragmented one:
+completeness is guaranteed by the book level, economy by the synthesis level.
+
+**Two source kinds.** A guide's `source_kind` is either `document` (the default —
+distilled from USER-PROVIDED indications; operative, "how to act") or `code`
+(distilled from the project's own code; a comprehension map of a complex component,
+"how it works"). Both are **source-faithful and snapshot-anchored** — the machinery
+below (snapshot, `source_hash`, fidelity markers, router, `stale`) is identical; only
+what is gathered into `.sources/` differs (a handed document vs verbatim code
+excerpts). Where a rule applies to only one kind, it says so.
+
+## 0. Consuming a guide (consult before acting)
+
+Guides only pay off if they reach the work they govern. **Before operative work,
+proportional to triage** — L1 is exempt; engaged for L2/L3 — ask: *does a guide
+already cover how to do this well?*
+
+- **Scan the router, not the guides.** Read the when-to-consult descriptions in
+  the guide router `ai_docs/reference/INDEX.md` **and** the agent-KB router
+  `~/.agentic-sdlc/ai_docs/reference/INDEX.md` (if present). Match by topic.
+- **On a match, read that guide's synthesis whole** before acting (the snapshot
+  stays on demand via the section markers). No match → proceed normally.
+- **Targeted match, never blanket.** Open only the guide whose description fits
+  the task — never load every guide, which would reintroduce the exact token
+  cost the "point to them" model exists to avoid. The two-level model (compact
+  synthesis / verbatim snapshot) already bounds a single guide's cost.
+- **Declare the router verdict.** The lookup result travels with the triage
+  level (`SKILL.md` Rule Zero) as one line — `router: no match`, or
+  `router: GUIDE_x.md → read`. This is what makes the consult reliable: an
+  undeclared lookup is indistinguishable from a skipped one, to the user, to a
+  later reviewer, and to you in the next session. Declaring `no match` on a repo
+  with no matching guide is the correct, expected output — not noise.
+- **Three legal verdicts, not two.** `GUIDE_x.md → read`, `no match` (the router
+  was read; nothing fitted — including a project whose router is an empty stub,
+  which is the normal state before the first guide exists), and
+  `router: absent (no router file)` for the case where `ai_docs/reference/INDEX.md`
+  does not exist at all. That third value exists so the honest answer is always
+  available: a required declaration with no truthful value gets faked or dropped,
+  and it takes the rest of Rule Zero with it. Regenerate the router
+  (`sdlc_check.py index`) when you report `absent`.
+- **Never fake the verdict.** `no match` means the router was read and nothing
+  fitted. A verdict that is always `no match` certifies a lookup that did not
+  happen and is worse than silence; a verdict listing the catalogue means the
+  match was not targeted (T7). Two guides are legitimate only when they cover
+  distinct concerns — typically an operative guide plus the comprehension map of
+  the component being touched; three is a smell, not a thorough lookup.
+- **Check a `code` guide against the code before you trust it.** No check can do
+  this for you (§6): the reader is the only one who sees that the map and the
+  component have parted. A divergence you observe is yours to close in the same
+  unit of work.
+- **Under subagent dispatch** the consult happens at plan-authoring time (the
+  orchestrator populates each task's `guides` field); a context-free subagent
+  reads the pointers it was handed and does not run its own router lookup. See
+  `dispatch.md`.
+
+## 1. When to trigger
+
+Trigger test is origin + purpose, not content taxonomy (no "is this technical
+enough" judgement call):
+- **Origin**: the user hands you indications to follow — a document to adhere
+  to, a pasted policy, "do it this way", a style guide, a runbook.
+- **Purpose**: the material is meant to GOVERN how the agent operates, not
+  just inform a one-off answer.
+
+Both hold → this is guide material. Either is missing (e.g. the user pastes
+background context with no operative intent, or asks a one-off question) →
+this is not a guide; answer normally, do not create a file.
+
+Never manufacture a guide from model knowledge. If the user asks for "a guide
+on X" without handing over source material, ask for the source first — a
+guide with no `distilled_from` is not this pipeline's output.
+
+### Proactive trigger (after reusable success)
+
+The trigger above is reactive (the user hands material over). It has a proactive
+twin: **after completing work that was governed by user-provided indications and
+is plausibly reusable** — it would prepare a future task — **PROPOSE** distilling
+a guide.
+
+- It is a **proposal to the user**, routed into this same pipeline (§2 onward):
+  the user confirms topic/scope before any file is written.
+- **Never a silent write, never from model knowledge.** If the work was not
+  governed by user-provided material there is nothing to distill — do not invent
+  a guide from general knowledge (the `distilled_from` fidelity constraint, §3,
+  is absolute). This adds a moment to PROPOSE, not a new writer.
+
+### Comprehension trigger (code source, autonomous — a duty, not a proposal)
+
+The two triggers above are for `source_kind: document` (the user hands material
+over). There is a third, for `source_kind: code`: while doing L2/L3 work, when you
+recognize that a component / feature / abstraction layer is **high-complexity** and
+no CURRENT guide already covers it, it is your **duty to WRITE a comprehension
+guide** — autonomously, no proposal, no human gate. The next session (or another
+agent) must not have to re-derive the model you just paid to build, and then break
+the component from partial understanding.
+
+- **Why autonomous is allowed here** (it is NOT for `document` guides): a
+  comprehension guide is **additive, code-anchored and reversible** (git). It changes
+  no code, plan or governed artifact — so the skill-wide "propose, never a silent
+  write" rule is relaxed for THIS kind only. The anti-hallucination floor still holds:
+  §3 fidelity is absolute — every claim traces to a verbatim code excerpt in the
+  snapshot, never to your assumption about what the code does.
+- **Recognize "high-complexity" by concrete signals** (any strong combination, not a
+  vibe): you had to trace one behavior across several files/modules (summaries were
+  not enough); high fan-in / large blast radius (many consumers); non-obvious control
+  or data flow (state machine, async/eventing, DI/plugin indirection, metaprogramming,
+  cross-cutting invariants); the area was already broken once — or **repeatedly
+  across sessions** — from partial understanding (handoff / diary / git shows it);
+  the "why" is not reconstructable from a single file.
+- **Guard-rails (autonomous is not unconstrained).** Search first (§2.0 — one CURRENT
+  guide per topic, both routers). Honor the fidelity floor (§3). RECOMMEND the
+  independent guide-vs-source review (§5) — it matters more here, since no human gated
+  creation. Announce the autonomous write in the closure / handoff so it is visible.
+- **When it fires.** As soon as you recognize the signal, during the work. The
+  Phase-5 **Comprehension checkpoint** (`SKILL.md` §5) is the backstop that asks the
+  question out loud before closure — a safety net for a signal you noticed and did not
+  act on, never a licence to defer. Writing it at closure is still far better than not
+  writing it: the model you built is complete now and gone next session.
+
+## 2. Pipeline
+
+0. **Search before creating (DRY — one CURRENT guide per topic).** Before
+   proposing anything, read `ai_docs/reference/INDEX.md` and grep
+   `reference/GUIDE_*.md` for topic overlap with the new material. Never end
+   up with two CURRENT guides on the same topic. Search BOTH routers: project
+   `ai_docs/reference/INDEX.md` AND the agent KB router
+   `~/.agentic-sdlc/ai_docs/reference/INDEX.md` (if present) — one CURRENT
+   guide per topic PER SCOPE; a project guide on a KB topic requires the
+   explicit `overrides:` declaration. On overlap, pick by provenance:
+   - **Same source, evolved** → UPDATE the existing guide in place: new
+     snapshot, new `source_hash`, same file (history lives in git).
+   - **Different source replacing the old one** → NEW guide + mark the old
+     one `status: SUPERSEDED` (its provenance chain must stay honest — do not
+     graft a new source onto a guide distilled from another).
+   - **Different source, partial overlap** → flag it to the user explicitly:
+     the current frontmatter binds ONE source per guide (`distilled_from`/
+     `source_hash` are singular), so a clean multi-source merge is not yet
+     supported — regenerate from the prevailing source and mark what the
+     merge drops, or keep the topics separate if they truly are.
+   Semantic overlap is NOT mechanically detectable: this step is agent
+   discipline plus the human reviewing the router — say what you found.
+   **Also verify the handed SOURCE itself is current**: check its lifecycle
+   (status/supersedes headers) and search the project for a newer version of
+   the same document before snapshotting. A user may hand you a path that a
+   migrated copy has since superseded — distilling from it produces a guide
+   that is born stale. If you find a newer version, surface it and distill
+   from that one. (Learned the hard way on first field use, 2026-07-02.)
+1. **Decompose into PREPARATION units — and weigh the fragmentation risk.**
+   A guide's goal is to PREPARE an agent for a situation: everything that
+   situation needs must arrive in ONE guide. The risk is asymmetric — extra
+   context injected costs tokens (cheap, recoverable); missing context makes
+   the agent invent or fail (the exact failure this pipeline exists to
+   prevent). Every split is a bet that no future task will cross the cut.
+   Therefore:
+   - **Default = one guide per source/domain.** Split ONLY when the resulting
+     guides would be consulted in DISJOINT situations — no plausible task
+     needs two of them at once.
+   - **Run the split test per proposed fragment and DECLARE it** in the
+     proposal: "which tasks consult this fragment, and would any of those
+     tasks also need another fragment?" Any overlap → merge, do not split.
+   - Heterogeneous sources (unrelated policies handed over together) are the
+     legitimate split case; a single coherent document about one subsystem
+     almost never is.
+   - **Also decide SCOPE per proposed guide**: project-scope
+     (`ai_docs/reference/`) or agent-scope (`~/.agentic-sdlc/ai_docs/reference/`,
+     governs the agent across ALL projects; origin+purpose test unchanged,
+     scope is a LOCATION decision by the user, never a content taxonomy; KB
+     created lazily with `.sources/` on the first agent-scope guide).
+2. **User confirms** the topic decomposition — including the fragmentation-risk
+   assessment and scope decision — before any file is written. **`source_kind: code`
+   skips this gate**: the comprehension guide is written autonomously (§1
+   comprehension trigger). Still run the fragmentation/scope judgement yourself — just
+   do not block on confirmation.
+3. **Snapshot each source verbatim** into
+   `ai_docs/reference/.sources/<slug>-<hash8>.md`:
+   - `slug` derives from the topic (lowercase, hyphenated).
+   - `hash8` = first 8 hex chars of the snapshot file's own SHA-256 (compute
+     the snapshot first, hash it, then name it — the hash is of the file you
+     just wrote, not of the original source).
+   - The hash is computed over LF-normalized content (CRLF → LF), exactly as
+     `sdlc_check.py` does in `sha256_file` — so recorded hashes survive
+     checkouts that rewrite line endings (e.g. Windows `core.autocrlf=true`).
+   - Recommended for consumer projects: add
+     `ai_docs/reference/.sources/** -text` to `.gitattributes` so git never
+     rewrites snapshot bytes at all (keeps snapshots byte-verbatim; the
+     normalized hash stays stable either way).
+   - The snapshot is verbatim: no paraphrasing, no reformatting beyond what is
+     needed to save it as markdown.
+   - **For `source_kind: code`** the snapshot is the verbatim CODE EXCERPTS the guide
+     explains — the specific functions / classes / regions of the real files, each
+     labelled with its `path:symbol` (or `path:startLine-endLine`) — assembled into
+     the one `.sources/<slug>-<hash8>.md` and hashed identically. Copy the code
+     verbatim (no paraphrase); include ONLY the regions the guide covers, not whole
+     files, so `stale` tracks the code that matters. `distilled_from` records those
+     code paths.
+4. **Source-anchored SYNTHESIS (not restatement).** Select and compress what
+   the source says into the operative essence — decision rules, invariants,
+   the "where people go wrong" list — and POINT INTO the snapshot for the
+   detail (`[source: <snapshot>#anchor]` doubles as the detail-lookup
+   pointer: "full checklist → snapshot §7"). Every claim must still trace to
+   a specific point in the snapshot; do not extract from memory of the
+   conversation — re-read the snapshot while writing each section. Selection
+   and compression are allowed and expected; ADDITION is not (that stays
+   summarize-and-expand, forbidden). A guide approaching the source's own
+   length is a paraphrase, not a synthesis — wrong output.
+5. **Render per template** (`templates.md` → `## ai_docs/reference/GUIDE_[topic].md`):
+   frontmatter with `source_kind` (`document` | `code`), `source`, `distilled_from`,
+   `source_hash` (the snapshot's SHA-256, matching what you just computed), optional
+   `source_version`; body sections chosen from the repertoire (a `code` guide uses the
+   comprehension repertoire — how it works / control & data flow / invariants / where
+   it breaks), each with a fidelity marker.
+   **Write for the two-level read**: the guide (synthesis) is small enough to
+   be read WHOLE before acting; the snapshot (book) is where size lives and
+   where readers grep/partial-read on demand, following the section markers.
+   Use the repertoire's stable, self-describing headings, keep one concern per
+   `##` section, and make the frontmatter `description` the "should I open
+   this file at all" answer. This is why one synthesis + one book beats
+   several fragments: the synthesis guarantees the whole picture, the book
+   guarantees the details, the markers connect them.
+6. **Run `sdlc_check.py index`** so both `ai_docs/INDEX.md` and
+   `ai_docs/reference/INDEX.md` (the guide router) regenerate.
+
+## 3. Fidelity rules (mandatory, the D5 constraint)
+
+"The source" below means the SNAPSHOT — a handed document for `source_kind: document`,
+verbatim code excerpts for `source_kind: code`. The constraint is identical for both:
+never from UNVERIFIED knowledge. A code guide's every claim traces to the actual code
+in the snapshot, never to your assumption about what the code does.
+
+- Only what the source supports goes in the guide. If the source is silent on
+  something a reader might expect, mark the section `[not covered by source]`
+  — never fill the gap from general knowledge.
+- Every `##` section body carries exactly one kind of marker: `[source:
+  <snapshot>#<anchor-or-line>]` for content traceable to the snapshot, or the
+  literal `[not covered by source]` for an acknowledged gap. A section with
+  neither is a validator warning.
+- `summarize-and-expand` is forbidden: do not take a short source note and
+  "helpfully" expand it into a longer procedure using inferred steps. If the
+  source says one sentence, the guide section says that one sentence
+  (source-anchored), not an elaborated version of it.
+- When in doubt about whether something is "supported" by the source, treat it
+  as not covered rather than stretching the marker to fit.
+
+## 4. Ingestion bound (T9)
+
+If a source document exceeds roughly 2000 lines, do not silently truncate or
+skim it. Stop and ask the user to either split it into smaller documents or
+select the specific sections relevant to the guide being built. Silent
+truncation produces a guide that looks complete but is missing unreviewed
+material — worse than asking.
+
+## 5. Review
+
+Before the guide is used operatively for the first time, recommend an
+independent guide-vs-source review (a fresh pass comparing the rendered guide
+against the snapshot, checking every marker) — process control per the
+threat model (P-TM). This is a recommendation to the user, not a hard gate:
+state it explicitly when handing off a newly created guide.
+
+## 6. Maintenance
+
+- **Source changed**: new snapshot, regenerate the guide from it (new
+  `source_hash`); a guide REPLACING another is `status: SUPERSEDED` on the old
+  one. `sdlc_check.py stale` (also under `--hybrid`) reports `[stale]` when a
+  guide's recorded hash and its snapshot file diverge — the signal to regenerate.
+- **`source_kind: code` freshness is NOT mechanized.** `stale` compares the guide
+  to its snapshot, and a code snapshot is a frozen copy — so a map whose component
+  was rewritten reports FRESH forever (measured 2026-09-06: +388/-71 lines in the
+  guided module, `stale` silent). The duty is therefore the author's, twice: when
+  you MODIFY code a comprehension guide describes, refresh the guide in the same
+  closure (docs travel with the code); when you merely READ one, check it against
+  the code before trusting it. Too large to absorb → mark it `SUPERSEDED` rather
+  than leave a confident-wrong map badged CURRENT, which is worse than none.
+- **Agent-global KB guides** use the same pipeline and validator via
+  `--root ~/.agentic-sdlc`; freshness via the same `stale` engine.