@antoneeo/kb-agentic-skill 1.13.0 → 1.15.0

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

@@ -45,12 +45,50 @@ below — so it needs no separate dispatch hook.)
 
 ## Model tiers (client-relative, no provider names)
 
-- Default dispatch: **economy** implementer tier.
+- 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:

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

@@ -96,11 +96,19 @@ Claims live in the owning topic's `## Claims` table (`templates.md` has the temp
   makes the same assertion mint the same id in another project, which is what makes
   `portability.md`'s de-duplication mechanical instead of a judgement call. The price is
   that **one span cannot carry two different assertions at the same qty** — the id
-  cannot tell them apart, and the validator refuses the pair. The fix is to widen one
-  locator to the span that actually carries its assertion, or to merge the two rows.
-  It is **not** to edit the qty or nudge the locator until the hash differs: that
-  distorts the evidence to satisfy a hash function, which is the one repair this
-  ledger exists to prevent.
+  cannot tell them apart, and the validator refuses the pair. That refusal is a
+  symptom of a non-atomic row (§3): the fix is to **narrow each locator to the
+  sub-span that carries its own assertion** — narrow spans make atomic rows
+  id-distinct by construction. Merge ONLY when the two rows state the same single
+  assertion twice; merging distinct assertions manufactures a bundled row (§3),
+  trading the mechanical error for a semantic one no check can see. Narrowing is
+  not nudging: a narrowed locator still addresses exactly the words that support
+  its assertion, and the validator still opens the span. What stays forbidden is
+  editing the qty, or moving a locator onto bytes that do NOT carry the assertion,
+  until the hash differs — that distorts the evidence to satisfy a hash function,
+  which is the one repair this ledger exists to prevent. A locator edit mints a
+  NEW id; citers of the old one are reached by the cascade (`reconciliation.md`
+  §Splitting a bundled row).
 - **valid** — `-`, `from X`, `until X`, `from X until Y`, `if <condition>`. Half-open:
   `until 2026-03-01` and `from 2026-03-01` do NOT overlap. A time-bounded fact is not a
   conflict with its successor — write the scope, or reconciliation will manufacture one.
@@ -117,8 +125,8 @@ Claims live in the owning topic's `## Claims` table (`templates.md` has the temp
   the file and checks.
 - **prov** — `GIVEN | ELICITED | DERIVED | RULING | IMPORTED`. `IMPORTED` is a ruling that came from another project (`portability.md`): it keeps its text and original `basis:`, its note must say `imported_from:`, and it may not supersede a local row until you re-ratify it. Information for whoever resolves a
   conflict; never a rank.
-- **state** — `OK`, `CONTESTED <ids>`, `SUPERSEDED <id>` (`reconciliation.md` owns the
-  transitions).
+- **state** — `OK`, `CONTESTED <id>[,..]`, `SUPERSEDED <id>[,..]` (`reconciliation.md`
+  owns the transitions; a split bundle names ALL its successors).
 
 ## 3. Extraction discipline
 
@@ -127,6 +135,29 @@ the offset span it came from. The extractor **invents nothing**: no labels, no
 summaries-as-claims, no filling of gaps from model knowledge. What the source does not
 assert does not become a row — it may become a `gaps:` entry on the topic.
 
+**One row asserts one thing — the span is not the unit.** The extraction unit is a
+source span; the unit of use is one assertion, and they are not the same size: a row
+can be atomic as provenance and plural as meaning. The common source of plurality is
+the **reviewer-comment shape** — one comment under one feature heading asserting
+several facts about several subjects (a capability at the door, another actor's
+console, a verification flow). Extracted as one span it becomes one legal row, and
+every downstream citation of it is faithful to the text while asserting what the
+source did not: the off-topic part is read as applying to the citing context
+(borrowed capability), another actor's surface counts as this actor's (wrong actor),
+an ambiguous subject silently switches referent — and the writer who avoids all
+three by quoting only the on-topic part has lost an assertion instead. Both halves
+of the north star, violated by one bundled row. So **emit one row per assertion even
+when the source packs several into one sentence**, and **cite the narrowest span
+that supports the assertion, not the paragraph that contains it** — narrow spans are
+also what make atomic rows id-distinct (§2). Sub-line precision needs no
+re-extraction on a stored `.txt`: a form-feed-free file is one page, so
+`p=1@<a>-<b>` addresses character offsets below the line; re-extraction is needed
+only for a source with no character-addressable stored form. A bundled row already
+in the ledger is repaired by splitting (`reconciliation.md` §Splitting a bundled
+row), never edited in place. The validator can only hint here — a `[note]` on
+suspicious claim text, heuristic and fallible, never an error: atomicity is
+meaning, and meaning is verified at the ingestion review.
+
 **Exhaust the source; never sample it.** *Invents nothing* is a floor, and a floor is not
 a target: an extractor that stops the moment nothing it wrote is false stops on page
 twenty of a two-hundred-page manual, with every row it emitted correct. A source is

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

@@ -60,6 +60,10 @@ already cover how to do this well?*
   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
@@ -271,17 +275,17 @@ state it explicitly when handing off a newly created guide.
 
 ## 6. Maintenance
 
-- **Source changed**: create a new snapshot (new hash), regenerate the guide
-  from it (new `source_hash`), and if the guide is replacing a prior guide
-  rather than updating in place, mark the old one `status: SUPERSEDED`.
-- **`stale` flags hash drift**: `sdlc_check.py stale` (also under `--hybrid`)
-  compares each guide's recorded `source_hash` against the live snapshot file
-  and reports `[stale]` when they diverge — that is the signal to regenerate,
-  not a manual freshness check.
-- **`source_kind: code` freshness**: `stale` works unchanged (the code-excerpt
-  snapshot drifts when the code changes → regenerate). ADDITIONALLY, when you modify
-  the code a comprehension guide describes, refresh that guide in the SAME closure
-  (docs travel with the code) — do not wait for `stale` to catch it. A stale
-  comprehension guide is a confident-wrong map, worse than none.
+- **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.

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

@@ -69,6 +69,28 @@ premise: signed amendments arrive later.
 | newer source vs a ruling | new set {new row, ruling row}; escalation shows the `basis:` |
 | member refined | the refining row inherits the member's contested relations (re-judged); counterparts rewritten to the new id |
 | corroboration of a contested member | source appended; the set untouched — more evidence is not new information, and the escalation form shows source counts |
+| bundled row split (`distillation.md` §3) | N atomic rows `OK`, each on its narrowed span; the bundle → `SUPERSEDED <id1>[, <id2> ..]`, text intact; contested relations re-judged per successor |
+
+## 3-bis. Splitting a bundled row
+
+A row carrying more than one assertion (`distillation.md` §3 — atomic as provenance,
+plural as meaning) is repaired by supersession, never in place:
+
+1. Write one atomic row per assertion, each citing the **narrowed span** that carries
+   it (`p=1@<a>-<b>` reaches below a line on a stored `.txt`). Narrow spans mint
+   distinct ids by construction.
+2. The bundled row becomes `SUPERSEDED <id1>, <id2>, ...` — every successor named,
+   its text intact, exactly as refinement keeps superseded text.
+3. Contested relations of the bundle are **re-judged per successor**: a counterpart
+   usually contests ONE of the assertions, not all of them.
+4. The cascade runs (§2, *the cascade runs*): every living document citing the fallen
+   id joins the revision worklist, and each citer is revised to the successor in ITS
+   scope — the moment a borrowed-capability citation dies.
+
+This is not new information arriving (§2): the source said N things all along; the
+ledger only now says them one at a time. No ruling and no `basis:` is needed — the
+split is a repair of our own extraction, and it travels with its own diary/commit
+record like any claim-table edit.
 
 ## 4. Escalation — batched, and in the legal form only
 

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

@@ -82,15 +82,92 @@ its outcome. The trigger term "permission-gated" scopes the STOP; the row word
 
 Use a different model from the author's where the client allows it.
 
+**The capability floor — which tier may run this role.** Independence says the
+reviewer must not be the author; it says nothing about whether the reviewer *can
+do the job*. A gate run below the capability its judgement needs produces the
+myopia the gate exists to catch, **while reporting as an independent review** —
+worse than no gate, because it certifies. So each role carries a minimum tier.
+Tiers are **client-relative capability levels, never provider names** (a name
+rots at the next model release; the tier→model binding lives in the client's own
+agent definition, never in this file):
+
+| Role | Floor | Why there |
+|---|---|---|
+| **authoring a governed artifact** (Vision, the analysis/design, use cases, the Interface Contract, threat model — `dispatch.md`'s never-list owns the enumeration) | **deep** | the purest case of the rule below: the output is judgement, nothing scores it, and `dispatch.md`'s never-list forbids moving it elsewhere — so the session's own capability IS this work's capability |
+| design review, closure review, any verdict on judgement | **deep** | the output is a judgement whose wrongness no check can see |
+| a light conformance or consistency pass (schema, coverage, citation resolution) | **light** | the criterion is stated and mechanical |
+| implementer dispatch, probe execution, anchor resolution, index regeneration | **economy** | a threshold signal catches a wrong cheap answer |
+
+The rule underneath the table: **a tier may be lowered only where a threshold
+signal exists** — `task.verify`, a test, a diff against a spec, an assertion
+harness — because that is what makes a wrong cheap answer visible instead of
+plausible. Where the output is judgement and nothing scores it, there is no
+signal to lower against, and the floor is the whole policy.
+
+**A session's floor is the highest floor among the roles it performs itself.** The
+table above binds reviewers and dispatched subagents, chosen per call — but the
+session doing the authoring was chosen by the USER before the agent existed, and
+an agent cannot re-tier itself mid-session. So the rule that reaches it is not
+routing, it is **disclosure**: where a session can determine that it is below the
+floor for a role it performs itself, it says so **once per session, at the first
+such role** — not once per unit — and the disclosure is repeated in the review
+row's existing `reviewer` cell (Hybrid: `notes`), which is what makes the pair
+below visible without adding a column.
+
+**Say plainly how thin this reach is.** A session knows its model NAME; tiers here
+are deliberately client-relative and this file maps no name to a tier, so the
+antecedent is satisfiable only where a session can recognize its own tier — which
+is also the session least likely to run the check. Where a session **cannot
+determine its own tier**, it owes nothing: the rule binds what an agent can know
+and say, never a capability it cannot acquire. **The reliably working half of this
+rule is the one addressed to the user, not to the agent** — which is why the
+package READMEs carry the tier-selection guidance, and why that is not a footnote.
+
+**Never both below the floor on the same unit — except when nothing better
+exists.** Where the authoring session ran below floor, the independent review's
+floor becomes non-negotiable and the same unit should not ALSO run a below-floor
+review. **The exception is the case *When independence and capability conflict*
+governs below**: where no independent rung at or above the floor exists at all,
+that rule wins, the review still runs, BOTH disclosures are recorded, and the
+result is not a violation but the worst admissible state — honestly labelled.
+Forbidding it outright would push the agent toward the abstention that rule
+explicitly rejects.
+
+**When independence and capability conflict, independence wins.** A client whose
+only independent rung is bound below the floor (a single-model client, or a
+subagent facility whose agent definition fixes a cheap model) still runs the
+gate: a below-floor *independent* reviewer catches the class the author is
+structurally blind to, while a self-pass catches none of it. What the floor then
+requires is **disclosure, not abstention** — the row records the tier that
+actually ran (`below floor: <reason>`), and that record IS the remedy. Where a
+higher-capability path exists but is permission-gated, nothing new applies: *The
+gated rung* above already governs, one question per gate per intact context.
+Where the client exposes no capability choice at all, the row says
+`single (client exposes no choice)` and the floor is satisfied by construction —
+it is a routing rule, and a routing rule with one route is not a failure.
+
 **Rounds are capped at 3.** FAIL → revise → re-review. If findings still stand
 after the third, stop and surface them to the user with the artifact — a gate that
 can block forever gets removed. **Log one row per completed review, PASS or FAIL**
 — a FAIL surfaced to the user is the highest-value outcome the gate produces, and
 logging only passes would erase exactly that evidence. The row goes in
 `ai_docs/audit/reviews/REVIEW_LOG.md` (create it if absent — `templates.md`):
-`| date | doc_key | tier | reviewer | findings_raised | findings_real | verdict | revise_rounds |`,
-with `tier` = `design` or `closure` in Standalone. One schema for both modes: a
-Hybrid project's devPNT gates write to the same file.
+`| date | doc_key | tier | model | reviewer | findings_raised | findings_real | verdict | revise_rounds |`,
+with `tier` = `design` or `closure` in Standalone. **`model` records the capability
+tier that actually ran** — `deep`, `light`, `economy`, `single (client exposes no
+choice)`, or `below floor: <reason>` — never a provider name in doctrine (a project
+may of course write its own model names in its own log). Without it the floor above
+is a belief: the row would say a gate ran and never whether it could do its job, and
+the correlation with `revise_rounds` and `findings_real` — the only evidence the
+policy pays — could not be drawn.
+
+**One schema for both modes**, meaning one required CORE plus each mode's own
+**mode-specific** realization columns. The core is what both modes actually share: `date`, `doc_key`,
+`tier`, `model`, `findings_raised`, `findings_real`, `verdict`, `revise_rounds`.
+Around it, Standalone adds `reviewer` and Hybrid adds `instrument` and `notes` —
+a devPNT row carries no `reviewer` column at all, so "one identical column list"
+was never true of the two modes. This costs nothing for the reason `templates.md`
+§`ai_docs/audit/reviews/REVIEW_LOG.md` owns and states.
 The log is how the gate's value is measured over time; skipping it makes the gate
 unfalsifiable, the same defect as an unnamed EXISTS or a faked router verdict.
 

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

@@ -80,6 +80,19 @@ sdlc_core.set_profile(
         # sdlc_core.py in three distributions to buy nothing.
         "taxonomy_pass", "subagent_dispatch", "question_discipline",
     ),
+    # F-046: the per-turn line moved from this file's own `remind` command into
+    # the shared spine, which now carries the machine for all three lenses. The
+    # kb duties below are unchanged; what is new is the first one -- an unread
+    # protocol cannot be applied, and until now nothing said so.
+    remind_line=(
+        "first decide if this skill governs the work; if yes, LOAD it once -- an "
+        "unread protocol cannot be applied. Triage: L1 quick fact, L2 propagation, "
+        "L3 new knowledge unit, Spike; declare the level. On this project's "
+        "domain, read topics/INDEX.md first and cite claim ids, or state no "
+        "coverage. Decisions today get recorded in the KB at close. Revising a "
+        "document? Re-read it whole and rewrite to current state -- never append "
+        "a delta."
+    ),
     design_gate_between=("### 3. Request Analysis & Taxonomy Pass",
                          "### 4. Knowledge Processing & Distillation"),
 )
@@ -174,6 +187,13 @@ def kb_claim_id(source_path, locator, qty_key=""):
     return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:12]
 
 
+# F-047: bundling tells for the atomicity note in kb_check_claims. Literal
+# substrings, deliberately few and conservative: the note is a hint, and a
+# noisy hint trains readers to skip notes. Field-calibrated on the motivating
+# reviewer-comment shape ("states X, that Y, and that Z").
+KB_BUNDLE_HINTS = (", and that ", "; ", ", while ", " and also ")
+
+
 def kb_unquote(value):
     """Strip ONE pair of wrapping YAML quotes (then re-strip whitespace).
     load_frontmatter keeps values verbatim by design; paths with spaces force
@@ -485,6 +505,20 @@ def kb_check_claims(root):
                 if not m:
                     errors.append("%s: about must be '<predicate> -> <slug>' or '-'"
                                   % where)
+            # --- atomicity hint (F-047): a row atomic as provenance can be
+            # plural as meaning. Text cannot PROVE plurality, so this is a
+            # note — never a warning or an error, never the exit code.
+            hints = [h for h in KB_BUNDLE_HINTS if h in row["claim"]]
+            if hints:
+                notes.append("%s: claim text of %s reads like more than one "
+                             "assertion (matched %s) — one row asserts one "
+                             "thing; if it is a bundle, split it "
+                             "(distillation.md section 3, reconciliation.md "
+                             "section 'Splitting a bundled row'). Heuristic "
+                             "only: a genuinely "
+                             "single assertion needs no change"
+                             % (where, row["id"] or "(id pending)",
+                                ", ".join(repr(h) for h in hints)))
             # --- id: recompute, or note fill-pending ---
             if not row["id"]:
                 notes.append("%s: id missing — fill-pending, run "
@@ -521,14 +555,22 @@ def kb_check_claims(root):
                                       "is global across topics/" % (where, row["id"],
                                                                     all_ids[row["id"]]))
                     elif same_span:
+                        # F-047: recommending a merge here was a trap — merging
+                        # distinct assertions manufactures a bundled row, trading
+                        # this mechanical error for a semantic one no check sees.
                         errors.append(
                             "%s: id %s collides with the row at %s — two "
                             "DIFFERENT rows cite the same span with the same "
                             "qty, and the id function cannot separate them (it "
                             "hashes path#locator#qty and excludes the text on "
-                            "purpose). Widen one locator to the span that "
-                            "actually carries its assertion, or merge the two "
-                            "rows — do not edit the qty to break the tie"
+                            "purpose). Narrow each locator to the sub-span that "
+                            "carries its own assertion — narrow spans make "
+                            "atomic rows id-distinct (on a stored .txt, "
+                            "p=<page>@<a>-<b> reaches below a line). Merge ONLY "
+                            "if the two rows state the same single assertion; "
+                            "merging distinct assertions trades this mechanical "
+                            "error for a semantic one no check can see — do not "
+                            "edit the qty to break the tie"
                             % (where, row["id"], all_ids[row["id"]]))
                     else:
                         # Same id, different text AND different span: the id
@@ -557,7 +599,7 @@ def kb_check_claims(root):
             m = re.match(r"^(CONTESTED|SUPERSEDED) ([0-9a-f, ]+)$", state)
             if not m:
                 errors.append("%s: state must be OK, 'CONTESTED <id>[,..]' or "
-                              "'SUPERSEDED <id>': %r" % (where, state))
+                              "'SUPERSEDED <id>[,..]': %r" % (where, state))
                 continue
             kind = m.group(1)
             targets = [t.strip() for t in m.group(2).split(",") if t.strip()]
@@ -1884,26 +1926,6 @@ def kb_cmd_orient(argv):
     return rc
 
 
-def kb_cmd_remind(_argv):
-    """F-041 item B: the per-turn one-line reminder (UserPromptSubmit, opt-in).
-
-    A CONSTANT, zero-read line -- the kb minimum an agent needs re-armed every
-    prompt: triage, the recall trigger, the capture moment, the revision gesture. Constant by
-    contract: nothing repo-controlled may ride a line injected into the agent's
-    context every turn, and zero reads is what keeps the per-turn cost flat.
-    The vision's non-goal bans per-turn GRAPH queries; this line only re-arms
-    the entry-into-topic criterion, it never runs the descent. Never wired by
-    init and never a default: ENFORCEMENT par.4 documents the manual snippet
-    and the ~50 tokens/prompt cost -- the project chooses. Fail-open like every
-    hook surface: argv is ignored whole, the exit code is always 0."""
-    print("kb-agentic: triage before acting -- L1 quick fact, L2 propagation of "
-          "settled knowledge, L3 new knowledge unit, Spike exploration; declare "
-          "the level. Answering about this project's domain? Read topics/INDEX.md "
-          "under the docs root first and cite claim ids, or state no coverage. "
-          "Decisions made today get recorded in the KB at session close. Revising an existing document? Re-read it whole and rewrite it to current state -- never append a delta.")
-    return 0
-
-
 def kb_cmd_help():
     """The spine's usage, then the overlay's own commands.
 
@@ -1946,10 +1968,6 @@ def main(argv=None):
     # 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)
-    # `remind` too: it is a hook surface (UserPromptSubmit), so a stray flag
-    # must print the line, not an argparse usage error into someone's prompt.
-    if argv and argv[0] == "remind":
-        return kb_cmd_remind(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`).