@antoneeo/agentic-sdlc-skill 1.38.0 → 1.40.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.40.0] - 2026-10-17
+
+### Changed
+- 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.39.0] - 2026-10-13
+
+### Changed
+- F-067: every L3 unit now keeps a verbatim, append-only request record `audit/requests/REQUEST_[feature].md`, started before the Vision Gate: the owner's opening words and every later statement that settles something (answers, approvals, costs, rulings). Artifacts cite its entries instead of paraphrasing; the shared `review.md` asks for the record and makes an owner statement with no resolving entry a finding. Secrets, personal data and confidential third-party or employer information are redacted. `review-map` classes the record as evidence.
+- F-066: every L3 closure now ships `MERGE_REVIEW_[feature].md` for the integrator (what to review, what was verified by which gate, what only a human can judge) and `E2E_TEST_[feature].md` for human testers in staging after the merge (regression scenarios always, new-behavior scenarios when behavior changed). New code-lens command `sdlc_check.py review-map [--base REF]` classes every changed file REVIEW / DESIGN / EVIDENCE / GENERATED; GENERATED is learned by running the project's own `index` on a throwaway copy, so it cannot drift from the writers.
+
 ## [1.38.0] - 2026-10-08
 
 ### Changed

package/README.md

@@ -26,6 +26,8 @@ Vendoring requires all three files: the entry point, `sdlc_core.py`, `knowledge.
 - **Execution disciplines**: explicit TDD (RED/GREEN/REFACTOR), evidence-first debugging with hypotheses ranked by likelihood and verification cost, supported causal questioning and clean Poka-Yoke correction with regression checks; an L3 spec-elicitation round and a single code-review definition wired into the workflow phases.
 - **Operative + comprehension guides + agent-global KB**: distil user-provided indications into source-faithful operative `GUIDE_*.md` (`source_kind: document`), and let the agent autonomously author **code-comprehension guides** (`source_kind: code`) for complex components — a source-faithful mental-model map that survives across sessions, so the next session doesn't re-derive and break the component from partial understanding. Consulted before work; shared cross-project via `~/.agentic-sdlc`.
 - **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.
+- **Merge review brief and E2E script**: every L3 closure ships `MERGE_REVIEW_[feature].md` for the integrator — what to review, what was verified by which gate, what only a human can judge — with a map from `sdlc_check.py review-map` that classes each changed file REVIEW / DESIGN / EVIDENCE / GENERATED (generated indexes are skipped, `check` proves them), and `E2E_TEST_[feature].md` for human testers after the merge: regression scenarios always, new-behavior scenarios when behavior changed.
+- **Verbatim request record**: every L3 starts `audit/requests/REQUEST_[feature].md` before the Vision Gate — the owner's own words and every later decision (answers, approvals, costs, rulings), append-only and redacted for secrets — so analyses cite what was asked instead of paraphrasing it, and reviewers can verify owner statements instead of trusting the author.
 - **Opt-in subagent execution**: an approved design projects into a validated executable plan an orchestrator can drive through subagents.
 - **Self-activating**: a SessionStart hook emits repo-sourced orientation; a deterministic self-eval battery guards the skill's own doctrine as the release gate.
 - **Standalone complete**: works fully with local `ai_docs/` without requiring devPNT.
@@ -33,7 +35,7 @@ Vendoring requires all three files: the entry point, `sdlc_core.py`, `knowledge.
 - **Independent review, twice**: the design is reviewed before it is implemented and the diff before the work is declared done — by somebody other than its author, who receives the whole review mandate in a fixed block copied verbatim, never a paraphrase of it. Three rungs of independence (fresh-context subagent > one-shot run > a declared self-pass, legal only when no higher rung is usable: absent, or permission-gated and declined — a gated rung is asked about, never silently skipped, and the log says which), capped at 3 rounds, one log line per review, and a PASS is invalid on "found nothing" — it must state where each constraint is satisfied.
 - **Question discipline**: a real doubt is asked when it emerges, before its answer is written into any document — grouped, with the pros and cons of each option. A choice whose pros clearly win is taken without asking, and the weighing is written next to it; a fact is settled by evidence or asked, never weighed. A question is legal only when the agent searched first, names the search with its result, and names the decision it unblocks — never a stream of "shall I proceed?".
 - **Installed support files**: Claude, Codex, Gemini, and Google Antigravity receive the full skill folder, including `templates.md`, `architect.md`, `guides.md`, `vision.md`, `tdd.md`, `debugging.md`, `elicitation.md`, `review.md`, `dispatch.md`, `routing.md`, `hybrid.md`, `ENFORCEMENT.md`, `memory.md`, and the validator's three files, `scripts/sdlc_check.py` + `scripts/sdlc_core.py` + `scripts/knowledge.py` — plus the `LICENSE` and `NOTICE` it ships under.
-- **Mechanical checks**: optional validator for document structure, generated feature history, stale audit areas, and protected-path gates — `check`, `validate`, `index`, `stale`, `mark`, `benefit`, `gate`, `plan`, `orient`, `migrate`. `benefit` reports what the review gates have already caught, beside what the doctrine costs to read — it always exits 0 and carries no verdict, because a measurement that can fail a build becomes a target.
+- **Mechanical checks**: optional validator for document structure, generated feature history, stale audit areas, and protected-path gates — `check`, `validate`, `index`, `stale`, `mark`, `benefit`, `gate`, `plan`, `orient`, `migrate`, `review-map` (code lens: classes the files of a change for the merge review brief). `benefit` reports what the review gates have already caught, beside what the doctrine costs to read — it always exits 0 and carries no verdict, because a measurement that can fail a build becomes a target.
 
 ## Installation
 

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.38.0",
+  "version": "1.40.0",
   "description": "Documentation-First SDLC protocol with triage, Vision governance and optional devPNT integration.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/agentic-sdlc-skill",
-  "version": "1.38.0",
+  "version": "1.40.0",
   "description": "Documentation-First SDLC protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, installed support files and optional devPNT integration.",
   "keywords": [
     "claude-code",

package/scripts/init.js

@@ -203,16 +203,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/agentic-sdlc-skill/ENFORCEMENT.md

@@ -14,17 +14,17 @@ python "<skill_dir>/scripts/sdlc_check.py" check
 
 ## 2. Check in CI (recommended for teams)
 
-Copy all three validator files into the repository: `scripts/sdlc_check.py`, `scripts/sdlc_core.py`, and `scripts/knowledge.py`, keeping them side by side. Then add to the pipeline:
+Copy all three validator files into the repository: `scripts/sdlc_check.py`, `scripts/sdlc_core.py`, and `scripts/knowledge.py`, keeping them side by side. Then add to the pipeline:
 
 ```
 python tools/sdlc_check.py validate --strict
 ```
 
-The validator ships as **three files**: the domain entry point, `sdlc_core.py` and `knowledge.py`. Keep all three together. The core alone still runs but omits shared-memory/KB checks and domain-specific overlays; it is not an equivalent CI gate. `check` includes the knowledge surface when present.
+The validator ships as **three files**: the domain entry point, `sdlc_core.py` and `knowledge.py`. Keep all three together. The core alone still runs but omits shared-memory/KB checks and domain-specific overlays; it is not an equivalent CI gate. `check` includes the knowledge surface when present.
 
 Effect: an unregenerated index, invalid frontmatter, a missing security section or incoherent states **block the pipeline** instead of relying on the agent's memory. `--strict` also fails on warnings and on a missing `ai_docs/`, so a wrong working directory cannot produce a green pipeline. This works because documents travel in the same PR as the code (Phase 5 rule).
 
-Note: the copy in the repo is the authoritative one for CI; update it when you update the skill — all three files, together.
+Note: the copy in the repo is the authoritative one for CI; update it when you update the skill — all three files, together.
 
 **Projects whose docs root is not `ai_docs/`.** Pass `--docs-dir <name>` (e.g. `--docs-dir mkt_docs`) on any subcommand, or set `AGENTIC_SDLC_DOCS_DIR`. Without either, the validator walks up from the working directory and takes the nearest root it recognizes. If it finds two side by side — the shape of a half-finished migration — it refuses and names both rather than validating half a project and printing a verdict. `ai_docs/` remains the default and the recommended root: the parameter exists so a legacy tree can be read and migrated, not so a second one can be kept.
 
@@ -155,7 +155,7 @@ Gemini CLI — wire the same command into its startup-hook mechanism if present;
 **Usage notes:**
 - The hook assumes the working directory is the project root (standard Claude Code hook behavior); it also accepts `--root <path>`.
 - **Hybrid/devPNT projects**: add `--hybrid` — the hook then appends a one-line pointer to run `devpnt_mcp_get_bootstrap` for the Master Plan / Knowledge Layer and does not replicate them; the filesystem orientation (router + handoff + README) still emits.
-- Like the CI gate (§2), if you copied the validator into the repo, the hook references that copy — keep all three files current when you update the skill.
+- Like the CI gate (§2), if you copied the validator into the repo, the hook references that copy — keep all three files current when you update the skill.
 
 ### Per-turn reminder: `remind` (UserPromptSubmit -- wired by default)
 
@@ -215,7 +215,7 @@ It aggregates the test files (`test_plan.py` + `test_session_start.py` + `test_s
 
 **Optional CI** (same shape as §2, not mandatory): add a `run:` step invoking the `unittest discover` command above.
 
-**T10 note:** if you copied the validator (all three files) and the `test_*.py` battery into the repo for CI, that copy is authoritative — keep it current when you update the skill.
+**T10 note:** if you copied the validator (all three files) and the `test_*.py` battery into the repo for CI, that copy is authoritative — keep it current when you update the skill.
 
 ## `benefit` is a report, never a CI gate
 

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

@@ -1,6 +1,6 @@
 ---
 name: agentic-sdlc
-version: 1.38.0
+version: 1.40.0
 description: Documentation-First SDLC protocol with risk-proportional triage, Vision as a guide, a complete Standalone mode and optional symbiosis with devPNT. Use for features, significant bugs, refactors, audits and documented maintenance.
 author: Antonio Pinto (https://github.com/Antoneeo)
 copyright: (c) 2026 Antonio Pinto
@@ -84,7 +84,10 @@ Triage decides IF documentation is due; this table decides WHICH document each e
 | Document | Write trigger | Phase |
 |---|---|---|
 | `solutions/ANALYSIS_[feature].md` | Every L3, after elicitation and before any code. On topic match with an existing analysis, update that one instead of a new file -- a revision re-reads the WHOLE document and rewrites it to current state (history in the Diary), never an appended delta section. A capability the architect pass splits out as its own unit of change (`architect.md` §4) gets its own ANALYSIS, and the two documents name each other. | 3 |
+| `audit/requests/REQUEST_[feature].md` | Every L3, the moment the level is declared — before the Vision Gate and the first question: R1 quotes the owner's opening words verbatim; every later owner statement that settles something for the unit (answer, approval, cost, ruling, merge) is appended before acting on it. Append-only, never deleted; artifacts cite its entries, a paraphrase never replacing the citation (`templates.md`). | 1 → 5 |
 | `solutions/SPIKE_[topic].md` | Closing any Spike — including a failed one (a negative outcome is still an outcome). | — |
+| `solutions/E2E_TEST_[feature].md` | Every L3, before the closure review (it is part of the reviewed diff): the human tester's post-merge script — new-behavior scenarios when behavior changed, regression scenarios always (`templates.md`). | 5 |
+| `solutions/MERGE_REVIEW_[feature].md` | Every L3, after the closure review: the integrator's brief — what to review (`sdlc_check.py review-map`), what was verified by which gate, what only a human can judge (`templates.md`). The PR description links it. | 5 |
 | `vision/features/VISION_[feature].md` | Feature known multi-milestone at analysis time, OR the retroactive trigger: you are about to create the SECOND `ANALYSIS_*` on the same theme — extract the shared feature vision first, then let both analyses reference it. | 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. It is an inventory for lookup, not a work board: no assignment, no due dates, no ordering, no holder. | 5 / session end |
 | `audit/HANDOFF_[feature].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. Also carries the resume logistics; **the ANALYSIS Diary keeps the durable narrative (DRY)**, and this file is DELETED at closure — deleting it *is* removing the row. | 4 / 5 / session end |
@@ -148,6 +151,7 @@ devPNT is not there, work Standalone and nothing is lost.
 
 Standalone:
 - Read `project_vision.md`, `roadmap.md`, `principles.md`.
+- Compare them with the request as recorded in `audit/requests/REQUEST_[feature].md`, not with a paraphrase of it.
 - If a document declares `Status: DRAFT`, treat it as a hypothesis: flag conflicts, but do not block an explicit user request.
 - If it declares `Status: APPROVED` and the request conflicts, stop and ask for a choice: update the Vision or modify/reject the request.
 - Never promote a Vision to `APPROVED` without the user's confirmation.
@@ -229,6 +233,7 @@ Hybrid L3:
   - guides created or changed: `sdlc_check.py index` regenerates BOTH manifests (`ai_docs/INDEX.md` and the guide router `ai_docs/reference/INDEX.md`) in one run.
 - If an architectural decision was taken (new pattern, layer or contract change, structural dependency), record an ADR before DONE — Standalone in `architecture/`, Hybrid propose the ADR/KL update in the devPNT DB. No decision, no ADR (Write Triggers).
 - In Standalone, if the project adopts `sdlc_check.py`, run `python <skill_dir>/scripts/sdlc_check.py check --root <project_root>` or the equivalent local copy.
+- **Merge review and E2E script (L3).** The integrator and the tester need different documents at different moments, so both are written at every L3 closure, in this order: `E2E_TEST_[feature].md` before the closure review; `MERGE_REVIEW_[feature].md` after it; then `index`, `sdlc_check.py review-map --base <base>`, its table pasted into the brief, and `index` again (the brief's catalog hash changed; the map's files did not, its line counts are as of the run). Without the brief an integrator cannot tell the code to review from the indexes `check` already proves, nor the claims a gate verified from the ones left to them (Write Triggers; templates: `templates.md`).
 - Updated documents must travel in the same commit/PR as the code they describe.
 - **Branch/worktree hygiene**: an L3 ran on its own branch (Phase 4) — close it with an explicit merge decision (merge, keep open, or discard), and once the user has chosen, PROPOSE the branch/worktree cleanup their choice implies; an orphan branch left behind with nothing said is the failure this bullet prevents — the cleanup itself is theirs to authorize (next bullet). In Hybrid, the running devPNT server locks `.devpnt/*.db`, so the merge is done from a separate git worktree or via a ref-only push, never an in-place branch switch in the primary worktree.
 - **Destructive guards (integration is the user's; destruction is explicit).** The integration choice — merge, push/PR, keep — belongs to the user. Discard happens ONLY on the user's explicit request, and the confirmation names exactly what dies: the branch, its commits, the worktree path. Never force-push without explicit authorization; a rejected push means the remote moved — investigate, don't force. Never clean up a worktree this workflow did not create — the host or another workflow owns it. Repository-specific release/finish commands are the project guide layer's (the router in `## Operative Guides`): the skill owns this discipline, the matched `GUIDE_*.md` owns the commands — cite it, never restate it.

package/skills/agentic-sdlc-skill/debugging.md

@@ -34,11 +34,11 @@ proof that it caused this incident.
    Do not repeat an invalidated hypothesis unless new evidence reopens it.
 
 3. **Test and trace the mechanism.** Reproduce and isolate the smallest faithful
-   failing case when feasible; bisect inputs, paths or changes when informative.
-   Skip a reproduction already known to omit the incident's causal conditions;
-   choose a faithful alternative or disclose the gap. Stop diagnostic checks when
-   further results cannot change the causal or fix decision; this does not replace
-   the regression and recovery verification in step 5.
+   failing case when feasible; bisect inputs, paths or changes when informative.
+   Skip a reproduction already known to omit the incident's causal conditions;
+   choose a faithful alternative or disclose the gap. Stop diagnostic checks when
+   further results cannot change the causal or fix decision; this does not replace
+   the regression and recovery verification in step 5.
    If the incident is intermittent or inaccessible, use captured traces and
    targeted diagnostic observations instead of declaring investigation impossible.
    Add minimal instrumentation when evidence is insufficient. Prefer read-only

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

@@ -67,15 +67,17 @@ Ask it before the first write that would embed its answer — in an analysis, pl
 guide or code — 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 user must find it inside the document; never
-drip one question per turn. The round below is this rule's planned occasion. Fold
-every answer into the artifact, citing the reply (§Reflect); an intent choice with
+drip one question per turn. The round below is this rule's planned occasion. At L3
+record every answer verbatim in the request record (`audit/requests/REQUEST_[unit].md`)
+and fold it into the artifact citing that entry (§Reflect); 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 user is not reachable (the Unattended path above).
-- **Delegated** — the user's own words handed you this choice ("your call"); quote
-  them. A general "go ahead" is not a delegation.
+- **Delegated** — the user's own words handed you this choice ("your call"); cite
+  their entry in the request record, or quote them where the unit has none (below
+  L3). 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 user will read it: an assumption recorded alone is a decision
@@ -193,7 +195,8 @@ round). Cover:
 
 ## Reflect
 
-Fold the answers into the ANALYSIS `## Objective` / `## Vision-Alignment`
+At L3, append the answers verbatim to the request record first
+(`audit/requests/REQUEST_[unit].md`, template in `templates.md`). Then fold them 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.

package/skills/agentic-sdlc-skill/hybrid.md

@@ -9,12 +9,15 @@ write triggers are `SKILL.md`'s, and they are identical in both modes.
 
 Moved out of `SKILL.md` by F-051 so a Standalone session stops paying for a seam
 it cannot reach. **The content below is the relocated text, unchanged except
-for one declared amendment**: F-065 rewrote the review rows (devPNT performs no
-review; the agent review precedes the proposal — `ADR_2026-10-07_agent_review_precedes_human`).
-The digest certifies the amended block, re-stamped only after the pre-edit
-block matched the previous digest and the diff showed only those rows changed.
-
-<!-- moved-block-sha256: b700966fdb47f85a794f883d38caab0a9d3443305d5800dbd186b0f0124d0681 -->
+for three declared amendments**: F-065 rewrote the review rows (devPNT performs no
+review; the agent review precedes the proposal — `ADR_2026-10-07_agent_review_precedes_human`);
+F-066 added one ownership-matrix row (merge review brief and E2E script, always
+filesystem); F-067 added one (the request record, always filesystem). The digest
+certifies the amended block, re-stamped each time only after the pre-edit block
+matched the previous digest (F-066: `b700966f…0681`; F-067: `3636fe4a…9c9a`)
+and the diff showed only the declared rows changed.
+
+<!-- moved-block-sha256: 19641538bf1357bfad7197ff1f6a36f856534efe10690675efa31abb173cf9fe -->
 ### Hybrid in symbiosis with devPNT
 
 Use this mode when the `devpnt_*` tools are available and point at the current project.
@@ -59,6 +62,8 @@ process; it never replaces it.
 | Review log | `audit/reviews/REVIEW_LOG.md` | devPNT `REVIEW_LOG.md` (same path) | always filesystem |
 | Operative guides | `ai_docs/reference/` | `ai_docs/reference/` — **filesystem-first even in Hybrid** | devPNT bootstrap may point at their index; it never copies their content |
 | Handoff | `audit/handoff.md` | `audit/handoff.md` | always filesystem |
+| Request record | `audit/requests/REQUEST_[feature].md` | same path; D-UC, E-ISP and M-VISION cite its entries; an approval given in devPNT is named by its proposal, not quoted | always filesystem: devPNT holds no owner chat statements |
+| Merge review brief, E2E script | `solutions/MERGE_REVIEW_[feature].md`, `solutions/E2E_TEST_[feature].md` | same paths; they cite the E-TDD shadow and the devPNT doc_keys | always filesystem: they travel in the PR with the code |
 
 ### Triage equivalence (one threshold, two vocabularies)
 

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

@@ -270,6 +270,10 @@ The binding inputs, by review type:
   **against** them, not only for internal consistency.
 - **For a closure review, the diff and the test evidence**: the run output that
   backs every completion claim, dated after the final relevant change.
+- **For a design or closure review of an L3/E3 unit, the request record**
+  (`audit/requests/REQUEST_[unit].md`): the owner's own words, verbatim, that the
+  artifact's owner statements must resolve to. Without it, every such statement is
+  a CANNOT VERIFY.
 - **For a design review, the threat model too** (same sources as above). Why this
   one and not the whole set: file coverage crosses the impact-analysis→design hop on
   a mechanical gate (every impacted file needs a design block), so a dropped file is
@@ -398,7 +402,11 @@ When you are the reviewer:
   intent choice written with no owner-authored source and no weighing, a weighing
   that names no rejected option or turns on an owner priority not on record, and a
   fact or owner-held datum settled by a weighing instead of evidence are findings;
-  so is a cited source that does not say what the line claims. What makes a ground
+  so is a cited source that does not say what the line claims. An owner statement
+  the artifact relies on — an answer, an approval, a cost acceptance, a ruling, a
+  delegation — that resolves to no entry of the unit's request record, or that the
+  record contradicts, is a finding; so is a quotation in the record carrying what
+  its template says to redact. What makes a ground
   or an assumption legal is each lens's `elicitation.md` §The question discipline —
   cite it, never restate it. The fix is the question, not a better justification.
 - **Restated facts (cite, never copy).** Every governance slot has ONE owning document

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

@@ -336,6 +336,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 +368,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 +567,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 +583,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 +608,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 +1115,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 +1208,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 = {}