@antoneeo/kb-agentic-skill 1.9.0 → 1.11.0

package/CHANGELOG.md

@@ -2,6 +2,80 @@
 
 Every significant change to this skill is recorded here.
 
+## [1.11.0] - 2026-08-28
+
+F-044 -- the time cycle (second-brain unit 3): claims age, fall, and their fall
+reaches whoever cites or derives from them. Plus two field-reported defects.
+
+### Added
+- **Citation staleness (WARN).** A living document citing a `SUPERSEDED` claim
+  id without naming EVERY successor id warns per (document, id) in
+  `check`/`graph` -- the vision sentence made mechanical ("no superseded claim
+  cited without the supersede visible"). Self-clearing two doctrine-conform
+  ways: a full-re-read revision that replaces the id, or an append-only
+  correction naming the successors -- history is never rewritten to satisfy a
+  check. Generated files (any lens's marker), `corpus/given/` + sidecars, and
+  `status: SUPERSEDED` tombstones are exempt; the owning topic self-clears by
+  construction.
+- **Expired windows (report-only).** A `valid` window whose half-open `until`
+  has passed marks the claim EXPIRED in `stale`'s `## claims` and the orient
+  count line -- computed at report time, never written into `state`, never a
+  check warning (no successor could clear it: a warn would be an unfixable
+  ratchet).
+- **Chain cascade + walkability.** A superseded `given/` artifact now reaches
+  every TRANSITIVE derivation through both `derived_from` carriers (note
+  frontmatter and `given/*.meta.md` sidecars -- the OCR/extraction class),
+  extending the direct-claims warn; and any `derived_from` entry that resolves
+  to nothing warns STANDING, supersession or not -- a chain must be walkable
+  before anything falls.
+- **`stale` intercepted: the consolidated view.** Spine output, flags and exit
+  code preserved (`--hybrid` included), then `## claims` -- superseded-cited
+  docs, expired windows, superseded chains -- appended only when nonempty and
+  never moving the rc. One staleness door per lens.
+- **Orient count line.** `kb time: N docs cite superseded claims; M claims
+  expired; K derivations on superseded sources -- run sdlc_check.py stale` --
+  once per session, only when dirty, always fail-open. Event-driven by design:
+  reconciliation ends a supersession by running `stale`; nothing polls per
+  turn.
+
+Two field-reported defects (2026-08-28), both in the frontmatter-value substrate.
+
+### Fixed
+- **YAML-quoted values are unquoted at the point of use** (`kb_unquote`).
+  `original_path:` values quoted because the path contains spaces produced
+  false "does not resolve" warnings -- 102 on one real corpus; the pointers
+  resolved all along. Worse, a quoted `supersedes:` silently MISSED the
+  supersession (no warning at all, and the claims-resting-on-superseded check
+  never fired). Both readers, plus the corpus-INDEX display, now strip one
+  pair of wrapping quotes; a genuinely dangling quoted path still warns.
+- **The orient recency line discloses when mtime decided it.** The line is
+  date-first as documented, but any note whose `date:` failed to parse fell
+  back to file mtime IN SILENCE -- and mtime lies after a rewrite or checkout,
+  so a note dated days ago could read "0 days old" with nothing marking the
+  degraded basis. Quoted dates now parse, a dated stamp beats an mtime stamp
+  on a same-day tie, and when the winning stamp still came from mtime the line
+  says so: `(corpus/notes; mtime -- date: not parsed)`.
+
+## [1.10.0] - 2026-08-28
+
+F-043 -- the revision doctrine: documents read as current state.
+
+### Added
+- **`## Revision — the full re-read` (SKILL.md).** Incorporating new knowledge
+  into an existing document is a rewrite, not an append: full re-read first,
+  body rewritten to current state, history in the Diary (past entries never
+  rewritten -- a correction is a new entry), claim tables exempt (rows move only
+  per reconciliation), node frontmatter exempt (a revision never re-parents),
+  and a multi-document pass re-reads PER DOCUMENT. Wired where the trigger
+  fires: the L2 triage row and the L3 Phase-4 flow (citation-only pointers);
+  the honest limit is in the doctrine's own text. Born from a field post-mortem
+  (12 documents realigned by delta-append; stale sentences left standing) --
+  and completed by its own review: three rounds, each catching the doctrine's
+  failure mode inside its own ANALYSIS.
+- **The `remind` line carries the gesture** ("Re-read it whole and rewrite it
+  to current state ..."): 443 chars, ~75 tokens per prompt, still one constant
+  zero-read line.
+
 ## [1.9.0] - 2026-08-28
 
 F-042 -- the install wires the hook; the incomprehensible question dies.

package/README.md

@@ -24,6 +24,8 @@ Two axes are kept apart on purpose — **abstraction** (a topic made of topics:
 
 7. **Capture — the day's decisions reach the ledger before they evaporate.** At a user-signed closing ("chiudiamo"), one sweep question — carrying its own inline result: "today I recorded X and Y — any other decisions from today?" — reaches even the decisions taken outside the session, which no transcript search could find. What surfaces lands on the existing rails (an elicited dated note, an L1 claim row) with explicit provenance; the sweep is idempotent (nothing captured twice), never creates topics, and stays silent when no one signed off. The kb `orient` shows notes recency at every session start — dated from note frontmatter, because file mtimes lie after a clone or worktree — so a missed capture is visible the next morning.
 
+8. **Revision — documents read as current state.** Incorporating new knowledge into an existing document is a full re-read and a body rewrite, not a stack of dated deltas: anchored edits are each correct while the document as a whole rots. The doctrine keeps history in the Diary (past entries never rewritten), leaves claim tables to reconciliation and graph edges to the taxonomy, and runs per document even in a multi-document pass. Born from a real field post-mortem: twelve documents realigned by append, every untouched sentence left standing as printed truth.
+
 Deliberately absent: any per-node coverage or completion state. `gaps:` says what a node lacks; nothing collects it into a dashboard. A **source** does record how far it has been read, but on its own sidecar and nowhere else — the corpus index prints that fact for every artifact, including the finished ones, because a list of only what is behind is the dashboard this method refuses.
 
 ## Key features
@@ -35,7 +37,7 @@ Deliberately absent: any per-node coverage or completion state. `gaps:` says wha
 - **Independent review, twice**: the design before it is implemented, the result before it is declared done — fresh-context subagent > one-shot run > a declared self-pass, 3 rounds max, one log line each, and a PASS is invalid on "found nothing".
 - **Question discipline**: a question is legal only when the agent searched first, names the search with its result, and names the decision it unblocks; otherwise it proceeds on a declared assumption, batched.
 - **Operative guides + agent-global KB**: distil user-provided indications into source-faithful `GUIDE_*.md` (`source_kind: document`) — verbatim snapshot plus hash, so drift is detected mechanically.
-- **Mechanical checks**: `check`, `validate`, `index`, `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`, plus the spine's `stale`/`mark`/`gate`/`plan`/`orient`/`migrate`. The graph and corpus checks verify spans against the stored extraction, recompute every id, refuse cycles and unreachable nodes, and enforce `CONTESTED` symmetry.
+- **Mechanical checks**: `check`, `validate`, `index`, `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`, `stale` (spine staleness plus `## claims` -- superseded-cited documents, expired `valid` windows, superseded derivation chains), plus the spine's `mark`/`gate`/`plan`/`orient`/`migrate`. The graph and corpus checks verify spans against the stored extraction, recompute every id, refuse cycles and unreachable nodes, and enforce `CONTESTED` symmetry.
 - **Installed support files**: Claude, Codex, Gemini and Google Antigravity receive the full skill folder — `SKILL.md`, `templates.md`, `taxonomy.md`, `distillation.md`, `reconciliation.md`, `guides.md`, `vision.md`, `elicitation.md`, `review.md`, `dispatch.md`, `routing.md`, `ENFORCEMENT.md`, and the validator's two files, `scripts/sdlc_check.py` + `scripts/sdlc_core.py` (the core is the family's shared spine — copy both, or neither).
 
 ## Installation

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "kb-agentic-skill",
-  "version": "1.9.0",
+  "version": "1.11.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.9.0",
+  "version": "1.11.0",
   "description": "Knowledge-Base & Document-First protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, signal distillation and optional devPNT integration.",
   "keywords": [
     "claude-code",

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

@@ -10,7 +10,45 @@ The agent runs a single gate at closure (Phase 5):
 python "<skill_dir>/scripts/sdlc_check.py" check
 ```
 
-(`check` = validate + stale in one command.) Exit code ≠ 0 ⇒ the feature is not declared closed. This is the minimum level the skill expects.
+(`check` = validate + stale in one command -- the SPINE's stale: the kb
+`## claims` section prints only under the overlay's own `stale` command,
+while `check` carries the same findings as warn lines.) Exit code ≠ 0
+⇒ the feature is not declared closed. This is the minimum level the
+skill expects.
+
+### The time cycle (F-044): superseded citations, expired windows, chains
+
+Three read-only checks share one collector and never touch exit-code
+semantics beyond ordinary warnings:
+
+- **Citation staleness (WARN, in `check`/`graph`).** A living document
+  citing a `SUPERSEDED` claim id without naming EVERY successor id warns
+  per (document, id). Self-clearing: a full-re-read revision that
+  replaces the id, or an append-only correction naming the successors,
+  both end the warn -- history is never rewritten to satisfy a check.
+  Exempt: generated files (header marker, any lens), `corpus/given/` and
+  its sidecars, `status: SUPERSEDED` tombstones. The owning topic file
+  self-clears by construction (its state cell carries the successors).
+  WARN and not ERROR by owner ruling: the vision demands the supersede
+  be VISIBLE where cited, not that closures block on unrelated debt.
+- **Expired windows (report-only).** A `valid` window whose half-open
+  `until` has passed marks the claim EXPIRED in `stale`'s `## claims`
+  and the orient count -- never a state write, never a check warning:
+  expiry is honest self-declaration with no successor whose naming
+  could clear a warn, so a warn would be an unfixable ratchet.
+- **Chain cascade + walkability (WARN, in `check`/`corpus`).** A
+  superseded `given/` artifact reaches every transitive derivation
+  through both `derived_from` carriers (note frontmatter and sidecars);
+  a `derived_from` entry that resolves to nothing warns STANDING --
+  supersession or not -- because a chain must be walkable before
+  anything falls.
+
+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.
 
 ## 2. Check in CI (recommended for teams)
 
@@ -169,8 +207,8 @@ Gemini CLI — wire the same command into its startup-hook mechanism if present;
 `orient` fires once, at session start; a long session drifts after it (a compaction,
 ten turns of other work -- the F-041 field report). `sdlc_check.py remind` prints ONE
 constant line -- the kb minimum: the triage levels, the topic-index recall trigger, the
-capture moment -- for the client to inject at every prompt. Cost: ~50 tokens per
-prompt, which is exactly why `init` never wires it and never will by default: the
+capture moment, the revision gesture -- for the client to inject at every prompt.
+Cost: 443 characters, ~75 tokens per prompt, which is exactly why `init` never wires it and never will by default: the
 per-turn cost is the project's choice. The line is constant and zero-read, so nothing
 repo-controlled can ride into the agent's context through it, and the vision's
 no-per-turn-graph-queries non-goal stays honored -- the line re-arms the

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

@@ -1,6 +1,6 @@
 ---
 name: kb-agentic
-version: 1.9.0
+version: 1.11.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
@@ -23,7 +23,7 @@ Support files in the skill directory:
 - `review.md`: the review discipline — when a review is due, how to request one, how to receive findings, how to review.
 - `dispatch.md`: opt-in subagent execution of an approved plan.
 - `routing.md`: which lens owns this unit of work. Read ONLY when a sibling lens skill is installed alongside this one; a single-lens install never reads it.
-- `scripts/sdlc_check.py` + `scripts/sdlc_core.py`: the mechanical validator for the docs root (`check`, `validate`, `index`, `stale`, `mark`, `gate`, `plan`, `orient`, `migrate`, and the knowledge overlay: `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`, plus `remind` — the opt-in per-turn one-line reminder, ENFORCEMENT §4). Two files: the core is the family's shared spine; the entry point IS the knowledge overlay — the claim ledger and topic-graph checks live inside it, so the core alone runs none of them. Copy both, or neither.
+- `scripts/sdlc_check.py` + `scripts/sdlc_core.py`: the mechanical validator for the docs root (`check`, `validate`, `index`, `mark`, `gate`, `plan`, `orient`, `migrate`, and the knowledge overlay: `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`, `stale` (spine staleness plus `## claims` -- the time cycle's consolidated view), plus `remind` — the opt-in per-turn one-line reminder, ENFORCEMENT §4). Two files: the core is the family's shared spine; the entry point IS the knowledge overlay — the claim ledger and topic-graph checks live inside it, so the core alone runs none of them. Copy both, or neither.
 - `ENFORCEMENT.md`: optional setup for CI and hooks.
 
 Read these files only when needed. `SKILL.md` is the operating contract; the support files are progressive resources.
@@ -46,7 +46,7 @@ Always classify the request before choosing the process. Declare the chosen leve
 | Level | Criteria | Required process |
 |---|---|---|
 | **L1 - Quick Fact / Snippet** | One claim row added to an existing topic; a typo; a preference update. No node created, no source entering the corpus, no frontmatter change. | Implement edit directly in existing note. No new documents. |
-| **L2 - Propagation of settled knowledge** | The fact is **already settled** in the corpus and the work carries it into existing documents — restating, correcting a stale copy, updating an SOP that quotes it. No node created or superseded, no hierarchy change, no node frontmatter change, no new source ingested. | Mini-analysis in message: objective, impact, sources, validation. Update existing document or create single SOP/note. |
+| **L2 - Propagation of settled knowledge** | The fact is **already settled** in the corpus and the work carries it into existing documents — restating, correcting a stale copy, updating an SOP that quotes it. No node created or superseded, no hierarchy change, no node frontmatter change, no new source ingested. | Mini-analysis in message: objective, impact, sources, validation. Update existing document (full re-read per `## Revision`) or create single SOP/note. |
 | **L3 - New knowledge unit / Corpus** | A source enters the corpus; a topic node is created or superseded; the hierarchy moves; a conflict must be reconciled; or what a claim asserts changes. | Full workflow: Vision Gate, Spec Elicitation, Taxonomy Pass, Knowledge Analysis, Distillation, Review, Indexing. |
 | **Spike - Exploration** | Time-boxed exploratory research or draft without merging into official KB. | Outcome in `ai_docs/solutions/SPIKE_[topic].md`. |
 
@@ -124,7 +124,7 @@ 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: do it on a branch or a worktree, never directly on the shared corpus, so a half-finished reconciliation is never what the next reader finds.
+- **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.
 - 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.
@@ -132,6 +132,10 @@ Use this mode when `devpnt_*` tools are available and point at the current proje
 
 ### 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>`.
@@ -243,7 +247,28 @@ exist — this section adds only the MOMENT.
 - **Silence stays legal where no one signed off**: no closing signal → no question,
   no ritual line.
 
+## Revision — the full re-read
+
+Incorporating new knowledge into an existing document is a rewrite, not an
+append: anchored edits are each correct while the global invariant — the body
+reads as CURRENT state — is never re-verified. The gesture:
+- Re-read the WHOLE document before editing; then rewrite the body so it reads
+  as written today — new knowledge fused, never quarantined in dated
+  sections — never append a delta.
+- History goes to the Diary/notes, never an inline chronicle — and past Diary
+  entries are never rewritten: a correction is a new entry.
+- A SUPERSEDED banner is a tombstone, never a revision device in a living doc.
+- Claim tables are EXEMPT (rows move only per `reconciliation.md`) and node
+  frontmatter moves only per `taxonomy.md` — a revision never re-parents; the
+  rewrite governs prose, never the ledger or the graph edges.
+- A multi-document pass re-reads PER DOCUMENT; set coverage is not integrity.
+- The re-read raises the probability of catching a false premise; it cannot
+  guarantee it — domain judgment stays the human's.
+
 ## Mechanical Enforcement
 - `scripts/sdlc_check.py index`: updates `ai_docs/INDEX.md` and `ai_docs/reference/INDEX.md`.
 - `scripts/sdlc_check.py validate`: validates YAML frontmatter (`status`, `description`).
 - `scripts/sdlc_check.py check`: checks dirty closures and missing indexes.
+- `scripts/sdlc_check.py stale`: spine staleness plus `## claims` --
+  superseded-cited documents, expired `valid` windows, superseded
+  derivation chains (the time cycle's consolidated view).

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

@@ -41,6 +41,15 @@ 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.
+
 **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
 practitioner knows nothing new, the set stays `CONTESTED` — a legitimate, permanent,
@@ -76,19 +85,19 @@ Whole documents keep the family lifecycle: a superseding note or guide marks the
 `status: SUPERSEDED`; `supersedes:` in the new one's frontmatter links them. Claims and
 documents move independently — superseding a document does not silently resolve the
 claims extracted from it; the `corpus` check reports claims resting on superseded
-originals for re-verification.
-
-## Rulings that came from another project
-
-An `IMPORTED` row is a ruling made by the owner of a different project
-(`portability.md`). Knowledge crosses a project boundary; authority does not.
-
-- It keeps its text, its span and its original `basis:` verbatim — the knowledge is not
-  lost, and relabelling it `DERIVED` would make the row lie about its origin.
-- Its note must carry `imported_from:`. Unnamed, the class says nothing and the row is a
-  `RULING` with the label filed off; the validator refuses it.
-- **It cannot settle anything here.** `SUPERSEDED <id>` pointing at an `IMPORTED` row is
-  an error: nobody in this project granted that decision its authority.
-
-Re-ratification is one act, and it is you deciding: read it, write your own note with
-your own `basis:`, set `prov` to `RULING`.
+originals for re-verification.
+
+## Rulings that came from another project
+
+An `IMPORTED` row is a ruling made by the owner of a different project
+(`portability.md`). Knowledge crosses a project boundary; authority does not.
+
+- It keeps its text, its span and its original `basis:` verbatim — the knowledge is not
+  lost, and relabelling it `DERIVED` would make the row lie about its origin.
+- Its note must carry `imported_from:`. Unnamed, the class says nothing and the row is a
+  `RULING` with the label filed off; the validator refuses it.
+- **It cannot settle anything here.** `SUPERSEDED <id>` pointing at an `IMPORTED` row is
+  an error: nobody in this project granted that decision its authority.
+
+Re-ratification is one act, and it is you deciding: read it, write your own note with
+your own `basis:`, set `prov` to `RULING`.

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

@@ -13,11 +13,14 @@ From the overlay:
   claim-id --fill <file>                    fill missing ids in a claim table
   graph    [--root R]                       topic-graph integrity checks
   corpus   [--root R]                       corpus checks (supersession, digests)
+  stale    [--root R] [--hybrid]            spine staleness PLUS `## claims`:
+                                            superseded-cited docs, expired
+                                            windows, superseded chains (F-044)
   index / validate / check                  spine behaviour PLUS the kb surface
                                             (byte-identical output on a tree
                                             with no topics/ or corpus/)
 
-Every other spine subcommand (stale, mark, gate, orient, plan, migrate, and any
+Every other spine subcommand (mark, gate, orient, plan, migrate, and any
 future one) is FORWARDED to the spine untouched: dispatch is "not intercepted ->
 forward", never a hand-copied command tuple, so a new spine command cannot be
 silently dropped here.
@@ -171,6 +174,18 @@ def kb_claim_id(source_path, locator, qty_key=""):
     return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:12]
 
 
+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
+    quoting, so value-consuming readers unquote at the point of use. Field
+    defect 2026-08-28: 102 false dangling original_path warns on one real
+    corpus, and a quoted supersedes: would silently MISS the supersession."""
+    v = (value or "").strip()
+    if len(v) >= 2 and v[0] == v[-1] and v[0] in ('"', "'"):
+        return v[1:-1].strip()
+    return v
+
+
 def kb_parse_scope(text):
     """'-' | 'from X' | 'until X' | 'from X until Y' | 'if <cond>' ->
     ('always',) | ('window', from, until) | ('if', cond). Raises on junk."""
@@ -891,7 +906,7 @@ def kb_build_corpus_index(root):
         for meta_p in sorted(given.glob("*.meta.md")):
             meta = sdlc_core.load_frontmatter(sdlc_core.read_text(meta_p).splitlines()) or {}
             orig = meta_p.name[:-len(".meta.md")]
-            sup = (meta.get("supersedes") or "").strip()
+            sup = kb_unquote(meta.get("supersedes"))
             lines.append("- `%s` — %s%s — %s" % (
                 orig, (meta.get("date") or "undated"),
                 (" — supersedes `%s`" % sup) if sup else "",
@@ -1050,7 +1065,7 @@ def kb_corpus_check(root):
             # reason does not extend to the PATH, which costs one exists(). A
             # corpus whose premise is "every provenance is a real file" cannot
             # let 16 sidecars go dangling behind a green run.
-            op = (meta.get("original_path") or "").strip()
+            op = kb_unquote(meta.get("original_path"))
             if op:
                 cands = _kb_original_candidates(op, root)
                 tried = [str(c) for c in cands]
@@ -1063,7 +1078,7 @@ def kb_corpus_check(root):
                         "artifacts and sidecars, never the originals, so after "
                         "an import this dangles legitimately"
                         % (rel, op, ", ".join(tried)))
-            sup = (meta.get("supersedes") or "").strip()
+            sup = kb_unquote(meta.get("supersedes"))
             if sup:
                 superseded.add(sup)
                 if not (given / sup).is_file():
@@ -1100,6 +1115,208 @@ def kb_sha256_bytes(path):
     return h.hexdigest()
 
 
+# -------------------------------------------------------- time cycle (F-044)
+# The three lists of the kb time cycle, computed ONCE per invocation and fed to
+# every surface (check/graph/corpus warn streams, `stale`, orient) -- never a
+# leaner re-implementation per surface, which is how under-counting is born.
+
+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
+
+
+def _kb_df_entries(value):
+    """A derived_from cell -> its entries: a single value or the inline list
+    `[a, b]`, each kb_unquote'd (quoted paths with spaces are legal YAML)."""
+    v = (value or "").strip()
+    if not v:
+        return []
+    if v.startswith("[") and v.endswith("]"):
+        return [kb_unquote(e) for e in v[1:-1].split(",") if kb_unquote(e)]
+    return [kb_unquote(v)]
+
+
+def kb_time_cycle(docs):
+    """-> {"cited":    [(doc_rel, old_id, missing_ids, succ_ids)],
+          "expired":  [(topic_rel, id, until, cited_by)],
+          "chain":    [(node_rel, ground_rel, via)],
+          "dangling": [(owner_rel, raw_entry)]}      -- each list sorted.
+
+    Read-only, tolerant per file: a malformed table or frontmatter drops that
+    file's contribution (the syntax finding belongs to the claims/corpus
+    checks). cited: a LIVING document containing a SUPERSEDED id without every
+    successor id visible in the same document -- the self-clearing condition,
+    so an append-only Diary correction naming the successors is a legal fix.
+    Living excludes corpus/given/ (+ sidecars: remedy-free), generated files
+    (header marker, ANY lens's entry point), and SUPERSEDED tombstones; the
+    OWNING topic self-clears by construction (its state cell carries every
+    successor id). expired: `valid` windows whose half-open `until` has
+    passed -- computed here, NEVER written back (state writes belong to
+    reconciliation). chain: transitive reverse derived_from closure from
+    superseded given/ artifacts, edges from BOTH carriers (note frontmatter
+    and given/*.meta.md sidecars). dangling: any derived_from entry that
+    resolves to nothing -- standing, supersession or not: a chain must be
+    walkable BEFORE anything falls."""
+    import datetime as _dt
+    import posixpath
+    cited, expired, chain, dangling = [], [], [], []
+    superseded = {}
+    windows = []
+    topics = docs / "topics"
+    if topics.is_dir():
+        for p in sorted(topics.glob("*.md")):
+            if p.name == "INDEX.md":
+                continue
+            try:
+                rows, _ = kb_parse_claims(sdlc_core.read_text(p))
+            except Exception:
+                continue
+            rel = "topics/" + p.name
+            for row in rows:
+                rid = (row.get("id") or "").strip()
+                if not KB_HEX12_RE.match(rid):
+                    continue
+                m = re.match(r"^SUPERSEDED ([0-9a-f, ]+)$",
+                             (row.get("state") or "").strip())
+                if m:
+                    succs = tuple(x.strip() for x in m.group(1).split(",")
+                                  if KB_HEX12_RE.match(x.strip()))
+                    if succs:
+                        superseded[rid] = succs
+                try:
+                    scope = kb_parse_scope(row.get("valid") or "-")
+                except Exception:
+                    continue
+                if scope[0] == "window" and scope[2]:
+                    windows.append((rel, rid, scope[2]))
+    living = []
+    for p in sorted(docs.rglob("*.md")):
+        rel = p.relative_to(docs).as_posix()
+        if rel.startswith("corpus/given/"):
+            continue
+        try:
+            text = sdlc_core.read_text(p)
+        except Exception:
+            continue
+        if KB_GENERATED_RE.search(text[:512]):
+            continue
+        meta = sdlc_core.load_frontmatter(text.splitlines()) or {}
+        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))
+    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))
+            expired.append((topic_rel, rid, until, by))
+    rev = {}
+    node_meta = {}
+    sup_arts = set()
+    notes_dir = docs / "corpus" / "notes"
+    given_dir = docs / "corpus" / "given"
+
+    def _resolve(entry):
+        # Normalize BEFORE resolving: `./x`, `a//b`, `a/../b` resolve on the
+        # filesystem but would never match the canonical node keys, so the
+        # walk would silently stop with neither a chain entry nor a dangling
+        # warn (closure-review WARN-1). Backslashed spellings stay loud: no
+        # `/` means the bare-name ladder, which dangles them visibly.
+        entry = posixpath.normpath(entry)
+        if "/" in entry:
+            return entry if (docs / entry).is_file() else None
+        for base in ("corpus/notes/", "corpus/given/"):
+            if (docs / (base + entry)).is_file():
+                return base + entry
+        return None
+
+    def _edges_of(owner_rel, meta):
+        for e in _kb_df_entries(meta.get("derived_from")):
+            target = _resolve(e)
+            if target is None:
+                dangling.append((owner_rel, e))
+            else:
+                rev.setdefault(target, set()).add(owner_rel)
+
+    if notes_dir.is_dir():
+        for p in sorted(notes_dir.glob("*.md")):
+            rel = "corpus/notes/" + p.name
+            try:
+                meta = sdlc_core.load_frontmatter(
+                    sdlc_core.read_text(p).splitlines()) or {}
+            except Exception:
+                continue
+            node_meta[rel] = meta
+            _edges_of(rel, meta)
+    if given_dir.is_dir():
+        for mp in sorted(given_dir.glob("*.meta.md")):
+            orig_rel = "corpus/given/" + mp.name[:-len(".meta.md")]
+            try:
+                meta = sdlc_core.load_frontmatter(
+                    sdlc_core.read_text(mp).splitlines()) or {}
+            except Exception:
+                continue
+            node_meta[orig_rel] = meta
+            _edges_of(orig_rel, meta)
+            sup = kb_unquote(meta.get("supersedes"))
+            if sup:
+                sup_arts.add("corpus/given/" + sup)
+    for ground in sorted(sup_arts):
+        seen = {ground}
+        frontier = [(ground, ())]
+        while frontier:
+            node, via = frontier.pop()
+            for owner in sorted(rev.get(node, ())):
+                if owner in seen:
+                    continue
+                seen.add(owner)
+                owner_via = via + (node,)
+                tomb = (node_meta.get(owner, {}).get("status")
+                        or "").strip() == "SUPERSEDED"
+                if owner not in sup_arts and not tomb:
+                    chain.append((owner, ground, owner_via))
+                frontier.append((owner, owner_via))
+    cited.sort()
+    expired.sort()
+    chain.sort()
+    dangling.sort()
+    return {"cited": cited, "expired": expired,
+            "chain": chain, "dangling": dangling}
+
+
+def kb_time_cycle_warns(cycle):
+    """-> (cited_lines, chain_lines, dangling_lines). ASCII only."""
+    cited = ["%s: cites %s, superseded by %s -- successor(s) %s not named; "
+             "revise per the Revision doctrine"
+             % (rel, old, ", ".join(succs), ", ".join(missing))
+             for rel, old, missing, succs in cycle["cited"]]
+    chain = []
+    for node, ground, via in cycle["chain"]:
+        tail = ("supersede the note" if node.startswith("corpus/notes/")
+                else "supersede the derivation")
+        chain.append("%s: derives (via %s) from %s, which a newer version "
+                     "supersedes -- re-derive from the successor or %s"
+                     % (node, " -> ".join(via), ground, tail))
+    dang = ["%s: derived_from %s resolves to nothing -- the chain is not "
+            "walkable" % (o, e) for o, e in cycle["dangling"]]
+    return cited, chain, dang
+
+
 # ------------------------------------------------------- portability (F-030)
 # Export a subgraph WITH the bytes its claims cite; import it additively.
 #
@@ -1272,7 +1489,7 @@ def kb_import_plan(bundle, docs):
 # ------------------------------------------------------------------ commands
 
 INTERCEPTED = {"index", "validate", "check", "graph", "corpus", "claim-id",
-               "anchor", "export", "import"}
+               "anchor", "export", "import", "stale"}
 
 
 def _kb_root(args):
@@ -1287,10 +1504,14 @@ def _kb_root(args):
     return root, root / name
 
 
-def kb_cmd_graph(docs):
+def kb_cmd_graph(docs, cycle=None):
     errors, warnings = kb_graph_check(docs)
     ce, cw, cn = kb_check_claims(docs)
-    for w in warnings + cw:
+    if cycle is None:
+        cycle = kb_time_cycle(docs)
+    tc_cited, _tc_chain, _tc_dang = kb_time_cycle_warns(cycle)
+    total_w = len(warnings) + len(cw) + len(tc_cited)
+    for w in warnings + cw + tc_cited:
         print("[warn]  %s" % w)
     for n in cn:
         print("[note]  %s" % n)
@@ -1298,18 +1519,22 @@ def kb_cmd_graph(docs):
         print("[ERROR] %s" % e)
     total_e = len(errors) + len(ce)
     if total_e:
-        print("Graph: %d errors, %d warnings." % (total_e, len(warnings) + len(cw)))
+        print("Graph: %d errors, %d warnings." % (total_e, total_w))
         return 1
     if not (docs / "topics").is_dir():
         print("[ok] no topics/ - nothing to check")
     else:
         print("[ok] topic graph and claim ledger consistent "
-              "(%d warnings)" % (len(warnings) + len(cw)))
+              "(%d warnings)" % total_w)
     return 0
 
 
-def kb_cmd_corpus(docs):
+def kb_cmd_corpus(docs, cycle=None):
     errors, warnings = kb_corpus_check(docs)
+    if cycle is None:
+        cycle = kb_time_cycle(docs)
+    _tc_cited, tc_chain, tc_dang = kb_time_cycle_warns(cycle)
+    warnings = warnings + tc_chain + tc_dang
     for w in warnings:
         print("[warn]  %s" % w)
     for e in errors:
@@ -1365,10 +1590,34 @@ def kb_cmd_check(root, docs, strict=False, hybrid=False):
     rc = sdlc_core.cmd_check(root, strict=strict, hybrid=hybrid)
     rc = max(rc, _kb_extra_validate(docs))
     if (docs / "topics").is_dir() or (docs / "corpus").is_dir():
+        cycle = kb_time_cycle(docs)
         print("===== graph =====")
-        rc = max(rc, kb_cmd_graph(docs))
+        rc = max(rc, kb_cmd_graph(docs, cycle))
         print("===== corpus =====")
-        rc = max(rc, kb_cmd_corpus(docs))
+        rc = max(rc, kb_cmd_corpus(docs, cycle))
+    return rc
+
+
+def kb_cmd_stale(root, docs, hybrid=False):
+    """F-044: the consolidation view. The spine's output and exit semantics
+    come first (--hybrid passed through untouched), then the `## claims`
+    section -- superseded-cited docs, expired windows, superseded chains.
+    Nothing is appended on a clean corpus, and the section NEVER moves the
+    spine's rc: the time cycle reports, the spine rules."""
+    rc = sdlc_core.cmd_stale(root, hybrid=hybrid)
+    cycle = kb_time_cycle(docs)
+    cited_w, chain_w, _dang = kb_time_cycle_warns(cycle)
+    lines = list(cited_w)
+    for topic_rel, rid, until, by in cycle["expired"]:
+        lines.append("%s: %s expired %s (%s)"
+                     % (topic_rel, rid, until,
+                        ("cited by: " + ", ".join(by)) if by else "uncited"))
+    lines += chain_w
+    if lines:
+        print("")
+        print("## claims")
+        for ln in lines:
+            print(ln)
     return rc
 
 
@@ -1563,17 +1812,22 @@ def kb_cmd_orient(argv):
         if notes_dir.is_dir():
             import datetime as _dt
             newest = None
+            newest_mtime = False
             for p in notes_dir.glob("*.md"):
                 stamp = None
+                from_mtime = False
                 try:
                     head = sdlc_core.read_text(p)[:600]
                     # `date:` counts only INSIDE the frontmatter block: a
                     # column-0 date: in a note's body must not misdate it.
+                    # The optional quote: YAML-quoted dates are legal and the
+                    # silent mtime fallback is exactly the clone-reset lie.
                     if head.startswith("---"):
                         end = head.find("\n---", 3)
                         if end != -1:
-                            m = re.search(r"^date:\s*(\d{4}-\d{2}-\d{2})",
-                                          head[:end], re.M)
+                            m = re.search(
+                                r"^date:\s*[\"']?(\d{4}-\d{2}-\d{2})",
+                                head[:end], re.M)
                             if m:
                                 stamp = _dt.date.fromisoformat(m.group(1))
                 except Exception:
@@ -1581,20 +1835,51 @@ def kb_cmd_orient(argv):
                 if stamp is None:
                     try:
                         stamp = _dt.date.fromtimestamp(p.stat().st_mtime)
+                        from_mtime = True
                     except Exception:
                         continue
-                if newest is None or stamp > newest:
+                # Strict newer wins; on a tie a DATED stamp beats an mtime one,
+                # so the disclosure below never fires beside a validated date
+                # proving the same day.
+                if (newest is None or stamp > newest
+                        or (stamp == newest and newest_mtime
+                            and not from_mtime)):
                     newest = stamp
+                    newest_mtime = from_mtime
             if newest is None:
                 print("\nno notes yet (corpus/notes)")
             else:
                 days = (_dt.date.today() - newest).days
-                print("\nnewest note: %d days old (corpus/notes)" % max(days, 0))
+                # The basis is disclosed when mtime decided the winner: the
+                # field-reported lie was a rewritten note reading "0 days old"
+                # against SKILL.md's date-first promise -- degraded, and mute.
+                basis = "; mtime -- date: not parsed" if newest_mtime else ""
+                print("\nnewest note: %d days old (corpus/notes%s)"
+                      % (max(days, 0), basis))
     except (Exception, SystemExit):
         # Fail-open: nothing in the recency append may break orient. (The
         # probe parser lives in the router try above; this guard covers the
         # date/mtime walk and the print itself.)
         pass
+    try:
+        # F-044: the time-cycle count line -- once per session at orient,
+        # fail-open, SILENT when clean (noise is failure one). It runs the
+        # shared collector, never a leaner walk: the counts must match what
+        # `stale` lists, or the line under-counts its way to false calm.
+        if root is not None:
+            docs = root / name
+            if (docs / "topics").is_dir() or (docs / "corpus").is_dir():
+                cycle = kb_time_cycle(docs)
+                n_docs = len({c[0] for c in cycle["cited"]})
+                m_exp = len(cycle["expired"])
+                k_chain = len(cycle["chain"])
+                if n_docs or m_exp or k_chain:
+                    print("\nkb time: %d docs cite superseded claims; "
+                          "%d claims expired; %d derivations on superseded "
+                          "sources -- run sdlc_check.py stale"
+                          % (n_docs, m_exp, k_chain))
+    except (Exception, SystemExit):
+        pass
     return rc
 
 
@@ -1602,7 +1887,7 @@ 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. Constant by
+    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
@@ -1614,7 +1899,7 @@ def kb_cmd_remind(_argv):
           "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.")
+          "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
 
 
@@ -1635,6 +1920,8 @@ def kb_cmd_help():
 knowledge overlay (kb-agentic) -- also available:
   graph                       topic-graph integrity: placement, edges, cycles
   corpus                      corpus integrity: digests, supersession, notes
+  stale                       spine staleness PLUS `## claims`: superseded-cited
+                              docs, expired windows, superseded chains
   claim-id <path> <locator>   compute a claim id (--fill to fill a whole table)
   anchor <path> <phrase>      resolve a phrase to a verified locator span
   export --out <dir>          bundle a subgraph WITH the bytes its claims cite
@@ -1679,6 +1966,10 @@ def main(argv=None):
         p.add_argument("--docs-dir")
         p.add_argument("--strict", action="store_true")
         p.add_argument("--hybrid", action="store_true")
+    p = sub.add_parser("stale")
+    p.add_argument("--root")
+    p.add_argument("--docs-dir")
+    p.add_argument("--hybrid", action="store_true")
     p = sub.add_parser("claim-id")
     p.add_argument("path")
     p.add_argument("locator", nargs="?")
@@ -1719,6 +2010,8 @@ def main(argv=None):
         return 1
     if args.cmd == "index":
         return kb_cmd_index(root, docs)
+    if args.cmd == "stale":
+        return kb_cmd_stale(root, docs, hybrid=args.hybrid)
     if args.cmd == "graph":
         return kb_cmd_graph(docs)
     if args.cmd == "corpus":

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

@@ -625,6 +625,9 @@ status: CURRENT
 
 - `id` empty when writing by hand: `sdlc_check.py claim-id --fill <file>` computes it.
 - `valid` half-open: `from` inclusive, `until` exclusive; `if <cond>` for conditionals.
+  Expiry against today is COMPUTED by the reports (`stale`'s `## claims`,
+  the orient count line) -- never written into `state`: state transitions
+  belong to reconciliation.
 - `qty`: `<value> <unit> <kind>` — effort in person-days (h/d/w/mo/fte-mo; 8h=1d, 1w=5d,
   1mo=21d), duration in calendar days (h/d/w/mo), cost within one currency, count unit-matched.
 - `about`: `<predicate> -> <slug>` for relationship claims; stored once, under the subject.