@antoneeo/kb-agentic-skill 1.22.0 → 1.24.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 Every significant change to this skill is recorded here.
 
+## [1.24.0] - 2026-10-17
+
+### Changed
+- F-073: one written form for a dated entry, `**YYYY-MM-DD — label.**`, is taught for Diary entries, spike outcomes and project notes that record an event, and shared readers (`entry_openers`, `request_entries`, `adr_date`, `frontmatter_date`) let a chronology list those events the same way the validator reads them. Three new advisories, which never fail a build, not even `--strict`: undated text in the Diary of an L3 analysis started on or after 2026-10-18; a HANDOFF `next:` longer than 240 characters on an L3 file updated on or after that date (`next:` now holds only the next step, and the state of the work goes to the Diary); and, in `check` only, an open L3 unit whose id another branch or tag uses for a different analysis (one `git grep` over local refs, silent without git). The doctrine now says to choose a new unit's id after fetching, and that a session sharing a checkout with another session works in its own git worktree. A source sidecar's `date:` is now stated to be the day the source was received.
+
+## [1.23.0] - 2026-10-17
+
+### Changed
+- F-068: on a live front, a new source or statement inside the declared `scope:` of an open unit (HANDOFF frontmatter) enters as an *ingestion step* of that unit: request entry, artifact or note, claim rows, reconciliation, `graph` until clean, one resume line. It does not reopen the full L3 cycle. Alignment (cascade on dependents, `stale`, registry, `index`, the `check` gate, commit) runs once, at an explicit closure the practitioner asks for or at session end. Two exceptions stay immediate: an in-flight draft is updated in the same step, and a sentence already delivered that a new fact falsifies is flagged in the same reply. Without isolation, a save commit marked `ingestion step` is allowed after a clean `graph`. Row locators come from `anchor`, ids from `claim-id --fill`. The Phase-5 instruction to update `handoff.md` by hand is gone: the registry is generated.
+- F1: closing the last open workstream now empties the generated registry `audit/handoff.md` instead of leaving its stale row behind: with zero `HANDOFF_*.md` sources `index` rewrites it empty (keeping `project_notes.md`), and `validate` reports a generated registry that still has rows but no sources as an error.
+- F-069: `graph`, `check`, `stale` and the session-start count are faster on a mature knowledge base, with byte-identical output. Citations of superseded claim ids are found with one pass per living document instead of one scan per (document, id) pair, and one check run reads and resolves each cited extraction once instead of once per claim row. On a synthetic ledger of 2183 rows and 1000 living documents, `graph` drops from 14 s to 4 s. No new flag.
+
 ## [1.22.0] - 2026-10-13
 
 ### Changed

package/README.md

@@ -46,7 +46,7 @@ Deliberately absent: any per-node coverage or completion state. `gaps:` says wha
 
 ## Key features
 
-- **Risk-proportional triage, measured in knowledge and never in files**: one claim row → propagating a fact already settled → a new knowledge unit (a source ingested, a node created or superseded, the hierarchy moved). Carrying one settled fact into eight documents is small; one claim that re-parents a node is not. A **Write Triggers** table maps each knowledge event to exactly one destination.
+- **Risk-proportional triage, measured in knowledge and never in files**: one claim row → propagating a fact already settled → a new knowledge unit (a source ingested, a node created or superseded, the hierarchy moved). Carrying one settled fact into eight documents is small; one claim that re-parents a node is not. On a live front, a new source or statement within an open unit's declared scope is an **ingestion step** of that unit — recorded on the ledger at once — while the rewrite of dependent documents, the registry and the full check run once, at a closure the practitioner calls. A **Write Triggers** table maps each knowledge event to exactly one destination.
 - **Portable knowledge**: `export` bundles a subgraph together with the bytes its claims cite — a closure, not a selection, because a claim whose source cannot be reopened is model knowledge arriving by another route. `import` merges it into another project **additively**: it never overwrites a node and never deletes, and claims already present are recognised by id rather than by comparing text, since the same artifact cited at the same span mints the same id in every project. Knowledge crosses the project boundary; **authority does not** — an imported ruling arrives as `prov: IMPORTED`, keeps its original `basis:`, and cannot settle a local disagreement until you re-ratify it.
 - **Several people, one project**: the workstream registry (`audit/handoff.md`) is **generated** from one file per open workstream, so two people opening or closing two workstreams on two branches edit two different files and their merge is clean. Row-per-workstream alone was not enough — a file-global `Date:` header defeats row-level ownership — so the header is derived from the sources and no writer touches it. The generated view can still conflict; that conflict is resolved by re-running `index`, never by hand, and `validate` refuses CLEAN until the file matches its sources. The append-only review log gets `merge=union` (a built-in driver, no per-clone configuration). It all works with no VCS at all: it is files and a generator.
 - **Vision-guided governance**: Standalone projects use `ai_docs/vision/`; Hybrid projects use devPNT `M-VISION` as the milestone north star. `DRAFT` informs, `APPROVED` binds, promotion is the user's alone.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "kb-agentic-skill",
-  "version": "1.22.0",
+  "version": "1.24.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.22.0",
+  "version": "1.24.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/scripts/init.js

@@ -196,16 +196,16 @@ in the skill's \`routing.md\`: it decides which lens's method and validation rul
 that unit. L1 never reaches it. Never refer to a document whose meaning differs by lens
 ("threat model", "vision", \`principles.md\`, \`handoff.md\`) by its bare name.
 
-Select the owning lens by the unit's purpose, then apply only its risk scale.
-The project's always-on pointer stays intact: consult the selected skill rather than
-merging multiple mandatory ladders. All lenses already carry shared project memory
-(\`memory.md\`); another installation is not needed for cross-domain recall.
+Select the owning lens by the unit's purpose, then apply only its risk scale.
+The project's always-on pointer stays intact: consult the selected skill rather than
+merging multiple mandatory ladders. All lenses already carry shared project memory
+(\`memory.md\`); another installation is not needed for cross-domain recall.
 This file is NOT auto-loaded by any client: it is a note for you, deliberately additive.
-Delete this note once the routing pointer is integrated.
+Delete this note once the routing pointer is integrated.
 `, 'multi-lens routing note');
   if (wrote && protocolPreexisting) {
     console.log('   ⚠️  A protocol pointer already existed and was NOT overwritten.');
-    console.log('       Integrate the routing pointer from AGENTIC_MULTI_LENS.md; keep one risk scale per unit.');
+    console.log('       Integrate the routing pointer from AGENTIC_MULTI_LENS.md; keep one risk scale per unit.');
   }
 }
 

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

@@ -47,8 +47,8 @@ The consolidated view is `sdlc_check.py stale` (the overlay intercepts
 the spine command, preserves its output, flags and exit code --
 `--hybrid` included -- and appends `## claims` only when nonempty). The
 orient append prints one count line at session start, only when dirty
-and always fail-open. Event-driven by design: reconciliation §2 runs
-`stale` after recording a supersession; nothing polls per turn.
+and always fail-open. Event-driven by design: reconciliation §2 runs `stale` at the unit's
+closure, once for every supersession since the last one; nothing polls per turn.
 
 ## 2. Check in CI (recommended for teams)
 

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

@@ -1,6 +1,6 @@
 ---
 name: kb-agentic
-version: 1.22.0
+version: 1.24.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
@@ -70,7 +70,8 @@ Cross-cutting rules:
 - **Domain routing (multi-lens installs only).** After the level is set, and only when a sibling lens skill of this family is installed (`agentic-sdlc`, `mkt-agentic-sdlc`, `course-creator`), run the router in `routing.md` for every L2, L3 and Spike: it decides which lens's method and validation rules govern this unit of work. L1 never reaches it, and a single-lens install never reads the file — detection fails open. In such a project, never refer to a document whose meaning differs by lens ("threat model", "vision", `principles.md`, `handoff.md`) by its bare name: qualify it with its domain, or name its path.
 - Personal data, credentials, security-sensitive processes, authN/authZ specs are high-risk: never L1.
 - **Escalation triggers — ANY of these makes it L3, whatever the file count:** the change touches the topic hierarchy (`parents:`, a `GENERALIZES` verdict, a re-parent); it touches more than one node's frontmatter; it creates or supersedes a node other nodes reference. Re-shaping the graph is a unit of change, never a side effect of placing one claim.
-- Adding one claim row to an existing topic is L1: the `id` may be left empty (the validator fills it — `claim-id --fill`), and no check errors on a hand-written row.
+- Adding one claim row to an existing topic is L1. The locator comes from `anchor <path> <phrase>`, not from counting lines by hand except for a form `anchor` does not produce; the `id` is left empty and filled by `claim-id --fill` once, after the row is complete (`qty` included), and no check errors on a hand-written row. `graph` verifies that the span exists and that the id matches locator and `qty` — never that the span says what the claim says — so such a hand-counted locator is re-read at its span before the row is written.
+- **An open unit absorbs.** A unit is open while its `audit/HANDOFF_*.md` exists, in the checkout its `branch:` names (from another checkout, its row in the registry says so); its scope is the `scope:` field of that HANDOFF's frontmatter — the file every open unit has by construction (a unit opened on a live front declares a front-wide scope there). A source or practitioner statement the scope covers is not a new unit: work in that checkout, declare `ingestion step of <unit>` in place of a new triage, and do only this — the request-record entry; the `given/` artifact with sidecar, or the note; the claim rows; the reconciliation classification, recording any supersession or contested set at once and presenting its escalations at the end of the step (a step is a run for `reconciliation.md` §4); `graph`, fixed until clean; one resume line in the HANDOFF body ("alignment pending since <date>: <what landed>"), frontmatter untouched. The step reply states what landed on the ledger, any escalation, any immediate exception (Phase 4), and that alignment is pending — this is how the practitioner knows the dependent documents lag. A step does not rewrite dependent documents, run `stale`, edit HANDOFF frontmatter or the registry, run `index` or `check`, or commit — that is the closure's work (Phase 5). One exception: on a project with no branch isolation (every session in one shared checkout), the step may end with a save commit once `graph` is clean, its message marked `ingestion step`, so history protects the work; such a commit has not passed the closure gate, which stays mandatory before the closure commit and before any push or integration. Without isolation the residual risk is higher — the save commit lands on the shared line itself, where other sessions read it before any closure gate, and another session's `index` or a sync tool can pick up uncommitted step files — and the step reply says so once per session. When coverage is doubtful, or two open units' scopes both cover it, ask one question before ingesting, naming the candidate units. When the step would fire an escalation trigger the approved ANALYSIS did not plan, stop, declare it, and amend the ANALYSIS with the practitioner's approval before continuing. No open unit, or outside every scope: triage as usual.
 - If a bigger impact emerges during L1/L2 work, stop, reclassify and declare it.
 - When in doubt, pick the higher level.
 - **Doubts asked, questions legal.** A real doubt is asked when it emerges, before its answer is written; every question passes the legality test of the question discipline (`elicitation.md`): searched first with the search named, and the blocked decision named. Claim-conflict escalations additionally carry their own mandated form and are batched at run end (`reconciliation.md` §4).
@@ -85,8 +86,8 @@ Triage decides IF documentation is due; this table decides WHICH document each e
 | `solutions/ANALYSIS_[topic].md` | Every L3, after elicitation and before any drafting. On topic match with an existing analysis, update that one instead of a new file. | 3 |
 | `solutions/SPIKE_[topic].md` | Closing any Spike — including a negative outcome. | — |
 | `vision/features/VISION_[feature].md` | Multi-milestone topic at analysis time, or retroactive trigger (second ANALYSIS on same theme). | 3 |
-| `audit/handoff.md` (workstream registry) | **Never by hand — generated by `sdlc_check.py index` from the `HANDOFF_*.md` sources**, and `validate` errors when the two disagree. Regenerate at every L3 closure and at session end; the `Date:` header is derived, so no writer touches it. Inventory for lookup, never a work board. | 5 / session end |
-| `audit/HANDOFF_[topic].md` | **One per OPEN workstream, with or without volatile state** — it is the authored home of that workstream's registry row (frontmatter `workstream`/`level`/`branch`/`status`/`since`/`next`/`details`/`updated`), so no file means no row. Carries the resume logistics too; the ANALYSIS Diary keeps the durable narrative (DRY). DELETED at closure — deleting it *is* removing the row. | 4 / 5 / session end |
+| `audit/handoff.md` (workstream registry) | **Never by hand — generated by `sdlc_check.py index` from the `HANDOFF_*.md` sources**, and `validate` errors when the two disagree. Regenerate at every L3 closure (alignment or unit, Phase 5) and at session end — never at an ingestion step; the `Date:` header is derived, so no writer touches it. Inventory for lookup, never a work board. | 5 / session end |
+| `audit/HANDOFF_[topic].md` | **One per OPEN workstream, with or without volatile state** — it is the authored home of that workstream's registry row (frontmatter `workstream`/`level`/`branch`/`status`/`since`/`next`/`details`/`updated`, plus `scope` for a unit that absorbs ingestion steps), so no file means no row. Its `next:` is the next concrete step in one sentence; what happened, and the state of the work, go to the Diary as a dated entry. Carries the resume logistics too; the ANALYSIS Diary keeps the durable narrative (DRY). Frontmatter updated at a closure or session end, never at an ingestion step (a step adds only its body resume line). DELETED at unit closure — deleting it *is* removing the row. | 4 / 5 / session end |
 | `audit/project_notes.md` | A note true for the whole project rather than one workstream. Appended verbatim to the generated registry, so regenerating cannot destroy notes that belong to no workstream. | 5 / session end |
 | `audit/handoff.md` — converting an existing project | **Lazily, at the first write — and then ALL AT ONCE.** Converting one row at a time is the state that loses the others, so `index` refuses to write while anything in the file is unaccounted for and names it. Until the first source exists nothing generates and nothing errors. | 5 / session end |
 | `audit/audit_plan.md` (Standalone) | Bootstrap, and whenever a mapped area changes state (`sdlc_check.py mark`). | 1 |
@@ -140,21 +141,25 @@ Use this mode when `devpnt_*` tools are available and point at the current proje
 - **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 — full re-read per `## Revision` — and does 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.
+- **Isolate the work (Branch/worktree hygiene).** Distillation rewrites existing notes — full re-read per `## Revision` — and does 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. Where a project does not isolate (one shared checkout), that is a departure from this rule, not a second mode: Rule Zero's step save commit and its declared residual apply. A session that may run while another session uses the same checkout works in its **own git worktree**, and never switches branch, stashes, resets or runs `index` in a checkout another session may be using. Parallel work also shares ids: choose a new unit's id **after fetching**, as the first id free on every branch and tag the checkout can see (`check` names a collision while the unit is open).
 - Before drafting (L2/L3; L1 exempt), **consult the guide router** for a guide covering the task and read it first (the consult trigger, `guides.md` §0). A targeted description match, not a blanket read. Its result is the router verdict already declared with the triage level (Rule Zero).
 - Execute knowledge extraction using **Signal Distillation** (`distillation.md`).
 - **Opt-in subagent execution**: for an L3 with an approved analysis, the work MAY be executed via subagents per `dispatch.md`; default stays same-session. `dispatch.md` also carries the family-wide **delegation boundary** (what may be delegated at all, and what never may) — that section is not gated by the opt-in trigger and applies at any level, dispatch or no dispatch.
 - Handle conflicting or outdated information via **Reconciliation** (`reconciliation.md`). Mark obsolete files `status: SUPERSEDED`.
+- **New information on an open unit arrives as ingestion steps** (Rule Zero, *An open unit absorbs*), and the dependent documents wait for the closure — with two exceptions that never wait: a communication draft in progress whose sentence a new fact changes is updated in the same step, and a new fact that makes false a sentence already delivered to the practitioner in this session is flagged in the same reply, naming the sentence and the fact. Across sessions what was delivered is unknowable; the HANDOFF resume line and the request record are what the next session reads.
 
 ### 5. Closure & Indexing
-- Run verification checks (`sdlc_check.py check --root <project_root>`).
-- If the session recorded any supersession, run `sdlc_check.py stale`: its
-  `## claims` section is the revision worklist (superseded-cited documents,
-  expired windows, superseded derivation chains), worked per `## Revision`
-  -- one document, one full re-read.
-- If the work was governed by user-provided indications and is reusable, **PROPOSE distilling a guide** (proactive trigger, `guides.md` §1) — a proposal for the user, never a silent write, never from model knowledge.
-- Update `audit/handoff.md`.
-- Regenerate manifests: `python <skill_dir>/scripts/sdlc_check.py index --root <project_root>`.
+- **Phase 5 fires only on the practitioner's request** ("allinea", "chiudi") or on a session-closing signal (the Capture Moment's); propose it when the planned work is done. A unit that absorbed no ingestion step closes as before, when its planned work is done. It covers everything since the last closure, enumerated from the request-record entries since then and the uncommitted changes on the unit's branch, and runs once, in this order:
+  - the Capture Moment sweep;
+  - `sdlc_check.py stale`: its `## claims` section is the revision worklist (superseded-cited documents, expired windows, superseded derivation chains);
+  - the revision, per `## Revision` — one document, one full re-read — of every document that worklist names and every document the enumerated entries affect;
+  - if the work was governed by user-provided indications and is reusable, **PROPOSE distilling a guide** (proactive trigger, `guides.md` §1) — a proposal for the user, never a silent write, never from model knowledge;
+  - the HANDOFF update (below), then `python <skill_dir>/scripts/sdlc_check.py index --root <project_root>`;
+  - the closure gate, `sdlc_check.py check --root <project_root>` — the only gate command: it already runs `validate`, `graph` and `corpus`, so those are not run separately before it. Its stale stage is the spine's and does not print the kb `## claims` worklist (expired windows above all), which is why the `stale` step above stays — then the commit.
+- **Alignment closure** — the unit stays open: update the HANDOFF frontmatter and body to current state; commit on the unit's branch and propose its integration, so the day's ledger reaches the shared line the same day; the integration choice is the practitioner's.
+- **Unit closure** — the practitioner declares the work done: run the closure review (`review.md`) before DONE, then delete the HANDOFF; deleting it *is* removing the registry row, and the registry is never edited by hand. When it was the last one, `index` empties the generated registry.
+- When the closure gate is red: no commit; the unit stays open; name the failing checks, fix, re-run.
+- The closure reply states the closure-gate result, the documents revised, and the commit — or, when red, that nothing was committed.
 - Mark output clean and complete.
 
 ## Operative Guides & Router
@@ -233,10 +238,14 @@ Capture today is what makes recall honest tomorrow: a captured elicited or ruled
 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
+- **When — user-signed closings, once per session** — and at every Phase 5, so
+  also again at the session's closing when an alignment closure already ran earlier
+  in it; the sweep is idempotent, so a later run only adds what came after the
+  earlier one. 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
+  done"); the session-end pass that updates the `HANDOFF_*.md` files and
+  `project_notes.md`, then regenerates the registry with `index`, 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

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

@@ -41,14 +41,18 @@ dangling ids are errors, duplicates are errors.
    is now the assertion, and no row lingers contested against rows that no longer
    contest it.
 
-3. **The cascade runs.** Recording a supersession ends by running
-   `sdlc_check.py stale`: its `## claims` section lists every living
-   document still citing the fallen id without naming its successor(s)
-   and every derivation resting on a superseded source -- the revision
-   worklist, worked per the kb `## Revision` doctrine, one document at a
-   time. The citation warn also stands in `check` until each document is
-   revised (or an append-only correction naming the successors lands),
-   so the worklist cannot be silently forgotten.
+3. **The cascade runs.** The supersession is recorded in the ledger at
+   once; the cascade runs at the unit's next closure (`SKILL.md` Phase 5),
+   once for every supersession since the last one: `sdlc_check.py stale`,
+   whose `## claims` section lists every living document still citing the
+   fallen id without naming its successor(s) and every derivation resting
+   on a superseded source -- the revision worklist, worked per the kb
+   `## Revision` doctrine, one document at a time. The list is derived from
+   the ledger's state, so running it later loses nothing; meanwhile the
+   citation warn stands in `check` until each document is revised (or an
+   append-only correction naming the successors lands), so the worklist
+   cannot be silently forgotten. What does not wait for the closure is
+   named once, in `SKILL.md` Phase 4 (the two immediate exceptions).
 
 **No basis, no ruling.** A preference is not a fact; the validator refuses a ruling note
 without `basis:` exactly as it refuses a DERIVED note without `derived_from:`. If the

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

@@ -125,6 +125,21 @@ def kb_unquote(value):
     return v
 
 
+def frontmatter_date(meta):
+    """A note's or a sidecar's `date:` as `YYYY-MM-DD`, or None (F-073).
+    Quotes stripped, a datetime suffix tolerated, an impossible date refused --
+    the one parser behind orient's recency probe and any chronology reader."""
+    m = re.match(r"(\d{4}-\d{2}-\d{2})", kb_unquote((meta or {}).get("date")))
+    if not m:
+        return None
+    try:
+        import datetime as _dt
+        _dt.date.fromisoformat(m.group(1))
+    except ValueError:
+        return None
+    return m.group(1)
+
+
 def kb_parse_scope(text):
     """'-' | 'from X' | 'until X' | 'from X until Y' | 'if <cond>' ->
     ('always',) | ('window', from, until) | ('if', cond). Raises on junk."""
@@ -336,6 +351,17 @@ def kb_check_claims(root):
         if rel not in fm_cache:
             fm_cache[rel] = _note_frontmatter(root, rel)
         return fm_cache[rel]
+    # F-069: the same per-run memo for the source paths themselves -- each
+    # distinct path is resolved and stat'ed once, and each cited extraction
+    # read once (loc_cache, owned here, dropped when this call returns).
+    src_cache = {}
+    loc_cache = {}
+
+    def _resolved(path_s):
+        if path_s not in src_cache:
+            t = sdlc_core.confine_under(root, path_s)
+            src_cache[path_s] = (t, t is not None and t.is_file())
+        return src_cache[path_s]
     per_file_rows = []
     for p in sorted(topics.glob("*.md")):
         rel = "topics/" + p.name
@@ -357,16 +383,16 @@ def kb_check_claims(root):
                     errors.append("%s: source %r has no locator" % (where, src))
                     continue
                 path_s, loc = src.rsplit("#", 1)
-                target = sdlc_core.confine_under(root, path_s)
+                target, is_file = _resolved(path_s)
                 if target is None:
                     errors.append("%s: source %r escapes the docs root" % (where, src))
                     continue
-                if not target.is_file():
+                if not is_file:
                     errors.append("%s: source %r does not resolve — a claim whose "
                                   "origin cannot be reopened is model knowledge"
                                   % (where, src))
                     continue
-                kb_check_locator(target, loc, where, errors)
+                kb_check_locator(target, loc, where, errors, loc_cache)
             # --- provenance ---
             prov = row["prov"]
             # Resolved ONCE, for every provenance: the non-GIVEN classes read it
@@ -556,8 +582,14 @@ def kb_check_claims(root):
     return errors, warnings, notes
 
 
-def kb_check_locator(target, loc, where, errors):
-    """A locator must address an existing span of the stored bytes."""
+def kb_check_locator(target, loc, where, errors, cache=None):
+    """A locator must address an existing span of the stored bytes.
+
+    `cache` is an optional dict the CALLER owns for one run (F-069): keyed by
+    the path actually read, it holds only what the checks compare against --
+    page lengths, a line count, or False for a missing extraction -- never the
+    text. Findings are still appended per call, so per row. Without it, every
+    call reads the file, as before."""
     m = LOC_PAGE_RE.match(loc)
     if m:
         page, a, b = int(m.group(1)), int(m.group(2)), int(m.group(3))
@@ -566,17 +598,24 @@ def kb_check_locator(target, loc, where, errors):
             return
         # offsets address the stored extraction (<stem>.txt beside the original)
         ext = target if target.suffix == ".txt" else target.with_suffix(".txt")
-        if not ext.is_file():
+        key = ("p", ext)
+        if cache is None or key not in cache:
+            lengths = ([len(pg) for pg in sdlc_core.read_text(ext).split("\f")]
+                       if ext.is_file() else False)
+            if cache is not None:
+                cache[key] = lengths
+        else:
+            lengths = cache[key]
+        if lengths is False:
             errors.append("%s: no stored extraction %s for locator %r — offsets "
                           "must address kept bytes" % (where, ext.name, loc))
             return
-        pages = sdlc_core.read_text(ext).split("\f")
-        if page < 1 or page > len(pages):
+        if page < 1 or page > len(lengths):
             errors.append("%s: locator %r addresses page %d of %d" %
-                          (where, loc, page, len(pages)))
-        elif b > len(pages[page - 1]):
+                          (where, loc, page, len(lengths)))
+        elif b > lengths[page - 1]:
             errors.append("%s: locator %r spans past the end of page %d "
-                          "(%d chars)" % (where, loc, page, len(pages[page - 1])))
+                          "(%d chars)" % (where, loc, page, lengths[page - 1]))
         return
     m = LOC_LINE_RE.match(loc)
     if m:
@@ -584,7 +623,13 @@ def kb_check_locator(target, loc, where, errors):
         if a > b or a < 1:
             errors.append("%s: locator %r has an invalid line range" % (where, loc))
             return
-        n = sdlc_core.read_text(target).count("\n") + 1
+        key = ("L", target)
+        if cache is None or key not in cache:
+            n = sdlc_core.read_text(target).count("\n") + 1
+            if cache is not None:
+                cache[key] = n
+        else:
+            n = cache[key]
         if b > n:
             errors.append("%s: locator %r spans past line %d" % (where, loc, n))
         return
@@ -1085,12 +1130,18 @@ KB_GENERATED_RE = re.compile(r"GENERATED by \S+ index - do not edit by hand")
 KB_HEX12_RE = re.compile(r"^[0-9a-f]{12}$")
 
 
-def _kb_hex_bounded(text, cid):
-    """True when cid appears NOT embedded in a longer hex run: a git hash
-    sharing a substring must never count as a citation (either side, either
-    case). cid is pre-validated 12-hex, so it is regex-safe by construction."""
-    return re.search(r"(?<![0-9a-fA-F])%s(?![0-9a-fA-F])" % cid,
-                     text) is not None
+# A citation of a claim id is a run of exactly its 12 lowercase hex characters
+# NOT embedded in a longer hex run: a git hash sharing a substring must never
+# count as a citation (either side, either case). Two such bounded runs cannot
+# overlap, so findall returns every one of them.
+KB_HEX_TOKEN_RE = re.compile(r"(?<![0-9a-fA-F])[0-9a-f]{12}(?![0-9a-fA-F])")
+
+
+def _kb_hex_tokens(text):
+    """The ids a text cites, extracted in one pass (F-069). Callers test
+    membership instead of scanning the text once per id: that per-(document,
+    id) scan made the time cycle grow with superseded ids x living documents."""
+    return frozenset(KB_HEX_TOKEN_RE.findall(text))
 
 
 def _kb_df_entries(value):
@@ -1172,19 +1223,23 @@ def kb_time_cycle(docs):
         if (meta.get("status") or "").strip() == "SUPERSEDED":
             continue
         living.append((rel, text))
-    for rel, text in living:
-        for old in sorted(superseded):
-            if _kb_hex_bounded(text, old):
-                succs = superseded[old]
-                missing = tuple(x for x in succs
-                                if not _kb_hex_bounded(text, x))
-                if missing:
-                    cited.append((rel, old, missing, succs))
+    # One token pass per living document, and none at all on a KB with no
+    # supersession and no validity window (the orient line runs this at every
+    # session start).
+    tokens = ({rel: _kb_hex_tokens(text) for rel, text in living}
+              if superseded or windows else {})
+    for rel, _text in living:
+        cites = tokens[rel] if tokens else frozenset()
+        for old in cites.intersection(superseded):
+            succs = superseded[old]
+            missing = tuple(x for x in succs if x not in cites)
+            if missing:
+                cited.append((rel, old, missing, succs))
     today = _dt.date.today().isoformat()
     for topic_rel, rid, until in sorted(windows):
         if until <= today:
-            by = tuple(rel for rel, text in living
-                       if rel != topic_rel and _kb_hex_bounded(text, rid))
+            by = tuple(rel for rel, _text in living
+                       if rel != topic_rel and rid in tokens[rel])
             expired.append((topic_rel, rid, until, by))
     rev = {}
     node_meta = {}
@@ -1905,14 +1960,13 @@ def kb_cmd_orient(argv):
                     # it -- the file was already fully read, so the cap bought
                     # only failure. load_frontmatter is the authoritative
                     # reader (fence-bounded, so a column-0 date: in the body
-                    # still cannot misdate the note); kb_unquote covers quoted
-                    # dates; the prefix match tolerates a datetime suffix.
+                    # still cannot misdate the note); frontmatter_date covers
+                    # quoted dates and tolerates a datetime suffix.
                     meta = sdlc_core.load_frontmatter(
                         sdlc_core.read_text(p).splitlines()) or {}
-                    m = re.match(r"(\d{4}-\d{2}-\d{2})",
-                                 kb_unquote(meta.get("date")))
-                    if m:
-                        stamp = _dt.date.fromisoformat(m.group(1))
+                    day = frontmatter_date(meta)
+                    if day:
+                        stamp = _dt.date.fromisoformat(day)
                 except Exception:
                     pass
                 if stamp is None: