@antoneeo/kb-agentic-skill 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 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.

package/README.md

@@ -37,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.10.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.10.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)
 

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

@@ -1,6 +1,6 @@
 ---
 name: kb-agentic
-version: 1.10.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.
@@ -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>`.
@@ -265,3 +269,6 @@ reads as CURRENT state — is never re-verified. The gesture:
 - `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
 
 
@@ -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.