@antoneeo/kb-agentic-skill 1.23.0 → 1.24.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 Every significant change to this skill is recorded here.
 
+## [1.24.0] - 2026-10-17
+
+### Changed
+- F-073: one written form for a dated entry, `**YYYY-MM-DD — label.**`, is taught for Diary entries, spike outcomes and project notes that record an event, and shared readers (`entry_openers`, `request_entries`, `adr_date`, `frontmatter_date`) let a chronology list those events the same way the validator reads them. Three new advisories, which never fail a build, not even `--strict`: undated text in the Diary of an L3 analysis started on or after 2026-10-18; a HANDOFF `next:` longer than 240 characters on an L3 file updated on or after that date (`next:` now holds only the next step, and the state of the work goes to the Diary); and, in `check` only, an open L3 unit whose id another branch or tag uses for a different analysis (one `git grep` over local refs, silent without git). The doctrine now says to choose a new unit's id after fetching, and that a session sharing a checkout with another session works in its own git worktree. A source sidecar's `date:` is now stated to be the day the source was received.
+
 ## [1.23.0] - 2026-10-17
 
 ### Changed

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "kb-agentic-skill",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "Knowledge-Base & Document-First protocol with risk triage, Vision governance, signal distillation and optional devPNT integration.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/kb-agentic-skill",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "Knowledge-Base & Document-First protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, signal distillation and optional devPNT integration.",
   "keywords": [
     "claude-code",

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

@@ -1,6 +1,6 @@
 ---
 name: kb-agentic
-version: 1.23.0
+version: 1.24.0
 description: Knowledge-Base & Document-First protocol with risk-proportional triage, Vision as a guide, Signal Distillation, a complete Standalone mode and optional symbiosis with devPNT. Use for user documentation, knowledge extraction, SOPs, research notes, decision logs, knowledge management — and for answering project questions from the claim ledger and topic graph.
 author: Antonio Pinto (https://github.com/Antoneeo)
 copyright: (c) 2026 Antonio Pinto
@@ -87,7 +87,7 @@ Triage decides IF documentation is due; this table decides WHICH document each e
 | `solutions/SPIKE_[topic].md` | Closing any Spike — including a negative outcome. | — |
 | `vision/features/VISION_[feature].md` | Multi-milestone topic at analysis time, or retroactive trigger (second ANALYSIS on same theme). | 3 |
 | `audit/handoff.md` (workstream registry) | **Never by hand — generated by `sdlc_check.py index` from the `HANDOFF_*.md` sources**, and `validate` errors when the two disagree. Regenerate at every L3 closure (alignment or unit, Phase 5) and at session end — never at an ingestion step; the `Date:` header is derived, so no writer touches it. Inventory for lookup, never a work board. | 5 / session end |
-| `audit/HANDOFF_[topic].md` | **One per OPEN workstream, with or without volatile state** — it is the authored home of that workstream's registry row (frontmatter `workstream`/`level`/`branch`/`status`/`since`/`next`/`details`/`updated`, plus `scope` for a unit that absorbs ingestion steps), so no file means no row. Carries the resume logistics too; the ANALYSIS Diary keeps the durable narrative (DRY). Frontmatter updated at a closure or session end, never at an ingestion step (a step adds only its body resume line). DELETED at unit closure — deleting it *is* removing the row. | 4 / 5 / session end |
+| `audit/HANDOFF_[topic].md` | **One per OPEN workstream, with or without volatile state** — it is the authored home of that workstream's registry row (frontmatter `workstream`/`level`/`branch`/`status`/`since`/`next`/`details`/`updated`, plus `scope` for a unit that absorbs ingestion steps), so no file means no row. Its `next:` is the next concrete step in one sentence; what happened, and the state of the work, go to the Diary as a dated entry. Carries the resume logistics too; the ANALYSIS Diary keeps the durable narrative (DRY). Frontmatter updated at a closure or session end, never at an ingestion step (a step adds only its body resume line). DELETED at unit closure — deleting it *is* removing the row. | 4 / 5 / session end |
 | `audit/project_notes.md` | A note true for the whole project rather than one workstream. Appended verbatim to the generated registry, so regenerating cannot destroy notes that belong to no workstream. | 5 / session end |
 | `audit/handoff.md` — converting an existing project | **Lazily, at the first write — and then ALL AT ONCE.** Converting one row at a time is the state that loses the others, so `index` refuses to write while anything in the file is unaccounted for and names it. Until the first source exists nothing generates and nothing errors. | 5 / session end |
 | `audit/audit_plan.md` (Standalone) | Bootstrap, and whenever a mapped area changes state (`sdlc_check.py mark`). | 1 |
@@ -141,7 +141,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 — full re-read per `## Revision` — and does it on a branch or a worktree, never directly on the shared corpus, so a half-finished reconciliation is never what the next reader finds. Where a project does not isolate (one shared checkout), that is a departure from this rule, not a second mode: Rule Zero's step save commit and its declared residual apply.
+- **Isolate the work (Branch/worktree hygiene).** Distillation rewrites existing notes — full re-read per `## Revision` — and does it on a branch or a worktree, never directly on the shared corpus, so a half-finished reconciliation is never what the next reader finds. Where a project does not isolate (one shared checkout), that is a departure from this rule, not a second mode: Rule Zero's step save commit and its declared residual apply. A session that may run while another session uses the same checkout works in its **own git worktree**, and never switches branch, stashes, resets or runs `index` in a checkout another session may be using. Parallel work also shares ids: choose a new unit's id **after fetching**, as the first id free on every branch and tag the checkout can see (`check` names a collision while the unit is open).
 - Before drafting (L2/L3; L1 exempt), **consult the guide router** for a guide covering the task and read it first (the consult trigger, `guides.md` §0). A targeted description match, not a blanket read. Its result is the router verdict already declared with the triage level (Rule Zero).
 - Execute knowledge extraction using **Signal Distillation** (`distillation.md`).
 - **Opt-in subagent execution**: for an L3 with an approved analysis, the work MAY be executed via subagents per `dispatch.md`; default stays same-session. `dispatch.md` also carries the family-wide **delegation boundary** (what may be delegated at all, and what never may) — that section is not gated by the opt-in trigger and applies at any level, dispatch or no dispatch.

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

@@ -125,6 +125,21 @@ def kb_unquote(value):
     return v
 
 
+def frontmatter_date(meta):
+    """A note's or a sidecar's `date:` as `YYYY-MM-DD`, or None (F-073).
+    Quotes stripped, a datetime suffix tolerated, an impossible date refused --
+    the one parser behind orient's recency probe and any chronology reader."""
+    m = re.match(r"(\d{4}-\d{2}-\d{2})", kb_unquote((meta or {}).get("date")))
+    if not m:
+        return None
+    try:
+        import datetime as _dt
+        _dt.date.fromisoformat(m.group(1))
+    except ValueError:
+        return None
+    return m.group(1)
+
+
 def kb_parse_scope(text):
     """'-' | 'from X' | 'until X' | 'from X until Y' | 'if <cond>' ->
     ('always',) | ('window', from, until) | ('if', cond). Raises on junk."""
@@ -1945,14 +1960,13 @@ def kb_cmd_orient(argv):
                     # it -- the file was already fully read, so the cap bought
                     # only failure. load_frontmatter is the authoritative
                     # reader (fence-bounded, so a column-0 date: in the body
-                    # still cannot misdate the note); kb_unquote covers quoted
-                    # dates; the prefix match tolerates a datetime suffix.
+                    # still cannot misdate the note); frontmatter_date covers
+                    # quoted dates and tolerates a datetime suffix.
                     meta = sdlc_core.load_frontmatter(
                         sdlc_core.read_text(p).splitlines()) or {}
-                    m = re.match(r"(\d{4}-\d{2}-\d{2})",
-                                 kb_unquote(meta.get("date")))
-                    if m:
-                        stamp = _dt.date.fromisoformat(m.group(1))
+                    day = frontmatter_date(meta)
+                    if day:
+                        stamp = _dt.date.fromisoformat(day)
                 except Exception:
                     pass
                 if stamp is None:

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

@@ -89,6 +89,14 @@ ARCHITECT_PASS_EPOCH = "2026-07-28"
 # row. Same grandfathering discipline as the pass above -- never nag work that
 # predates the rule.
 DESIGN_REVIEW_EPOCH = "2026-07-28"
+# Chronology (F-073): an L3 ANALYSIS started, or an L3 HANDOFF updated, on/after
+# this date is read for undated Diary text and a multi-step `next:`. Advisories,
+# like the two gates above: a fixed epoch cannot protect a late upgrader, so a
+# warning here would redden --strict CI on work written before the upgrade.
+CHRONOLOGY_EPOCH = "2026-10-18"
+NEXT_MAX_CHARS = 240        # this repository's longest `next:` was 214 at the epoch
+ID_SCAN_MAX_REFS = 300      # A3 is skipped above it (one advisory says so, T9)
+ID_SCAN_REFS_PER_CALL = 50  # keeps one git command line far below 32k chars
 def review_log_rel():
     return f"{docs_dir()}/audit/reviews/REVIEW_LOG.md"
 # Component Map 'Where' refs: a dotted token counts as a path only with one of
@@ -1101,6 +1109,298 @@ def section_body(text, aliases):
     return None
 
 
+def section_lines(text, aliases):
+    """(heading_line, body) for the first matching `## ` section, or None: the
+    body NOT stripped, so body line n is file line heading_line + n, and an
+    indented first line keeps its indentation. The readers below use it; a
+    stripped body would shift every line number and move `  - DATE` to column 0."""
+    lines = (text or "").splitlines()
+    for i, line in enumerate(lines):
+        if any(line.startswith(a) for a in aliases):
+            body = []
+            for nxt in lines[i + 1:]:
+                if nxt.startswith("## "):
+                    break
+                body.append(nxt)
+            return i + 1, "\n".join(body)
+    return None
+
+
+# ---------------------------------------------------------------- chronology
+# One grammar for a dated entry (F-073), read by the validator and by any
+# consumer that lists events (F-072's chronology): both call these readers, so
+# they cannot disagree on what an event is. The readers return openers only --
+# date, label, line -- and format nothing for display.
+
+DIARY_SECTION = next(s for s in ANALYSIS_SECTIONS if s[0] == "## Diary")
+_ISO = r"\d{4}-\d{2}-\d{2}"
+# At column 0: optional list marker, optional `###`/`####`, optional bold, then
+# the ISO date and a word boundary. The date FIRST is the rule; markup is
+# tolerated so the dated forms already written stay readable with no migration.
+ENTRY_OPENER = re.compile(r"^(?:([-*]) |(#{3,4}) )?(\*\*)?(" + _ISO + r")\b(.*)$")
+_LABEL_SEP = re.compile(r"^(?:\*\*)?\s*(?:[—–:-])?\s*")
+_REQUEST_HEADING = re.compile(r"^### (R\d+) [—–-] (" + _ISO + r") [—–-] (.+)$")
+_ADR_BODY_DATE = re.compile(r"^\**Date:\**\s*(" + _ISO + r")\b", re.M)
+_ADR_NAME_DATE = re.compile(r"^ADR_(" + _ISO + r")_", re.I)
+UNIT_ID_RE = re.compile(r"\b([A-Z]-\d{3,})\b")
+
+
+def _entry_label(bold, rest):
+    rest = _LABEL_SEP.sub("", rest, count=1)
+    if bold and "**" in rest:
+        rest = rest.split("**", 1)[0]
+    else:
+        rest = re.split(r"(?<=[.!?])\s", rest, maxsplit=1)[0]
+    return rest.strip(" .:—–-*")[:120]
+
+
+def _opener_at(lines, i):
+    """The match when lines[i] opens an entry. It must also START A BLOCK -- the
+    line above is blank, absent or a heading, or the line is itself a list item
+    or a heading -- so a hard-wrapped prose line that happens to begin with a
+    date is never an event. (A separator after the date is NOT required: real
+    openers read `DATE (qualifier)` and `DATE word`.)"""
+    m = ENTRY_OPENER.match(lines[i])
+    if not m:
+        return None
+    prev = lines[i - 1] if i else ""
+    if not prev.strip() or prev.startswith("#") or m.group(1) or m.group(2):
+        return m
+    return None
+
+
+def entry_openers(body):
+    """[(date, label, line)] -- one per dated entry opener; line is 1-based
+    within `body`. An undated paragraph belongs to the entry above it. Comments
+    are blanked first, exactly as `undated_diary_lines` does, so an entry
+    written under the template's comment is an event to both."""
+    lines = _blank_comments(body).splitlines()
+    out = []
+    for i in range(len(lines)):
+        m = _opener_at(lines, i)
+        if m:
+            out.append((m.group(4), _entry_label(m.group(3), m.group(5)), i + 1))
+    return out
+
+
+def _blank_comments(text):
+    # comments become blank lines, so line numbers still point at the file's lines
+    return re.sub(r"<!--.*?-->", lambda m: "\n" * m.group(0).count("\n"), text or "",
+                  flags=re.S)
+
+
+def undated_diary_lines(body):
+    """[(line, text)] a Diary body cannot date: text before the first opener,
+    and any `### ` heading that is not an opener. `####` and deeper headings are
+    sub-structure of an entry and stay legal. Comments are ignored."""
+    lines = _blank_comments(body).splitlines()
+    out, seen_opener = [], False
+    for i, line in enumerate(lines):
+        if _opener_at(lines, i):
+            seen_opener = True
+        elif line.startswith("### "):
+            out.append((i + 1, line.strip()))
+        elif not seen_opener and line.strip():
+            out.append((i + 1, line.strip()))
+    return out
+
+
+def request_entries(text):
+    """(entries, unparsed) for a request record: entries are
+    [(rid, date, label, line)]; a `### ` heading that does not match
+    `### R<n> — YYYY-MM-DD — <label>` is returned in unparsed as (line, text),
+    never dropped."""
+    entries, unparsed = [], []
+    for i, line in enumerate((text or "").splitlines()):
+        if not line.startswith("### "):
+            continue
+        m = _REQUEST_HEADING.match(line.rstrip())
+        if m:
+            entries.append((m.group(1), m.group(2), m.group(3).strip(), i + 1))
+        else:
+            unparsed.append((i + 1, line.rstrip()))
+    return entries, unparsed
+
+
+def adr_date(name, text):
+    """An ADR's date: `**Date:** YYYY-MM-DD` in the body, else the
+    `ADR_YYYY-MM-DD_*` file name, else None."""
+    m = _ADR_BODY_DATE.search(text or "") or _ADR_NAME_DATE.match(name or "")
+    return m.group(1) if m else None
+
+
+def _meta_date(meta, key):
+    return parse_iso(str(meta.get(key) or "").strip().strip("'\"")[:10])
+
+
+def chronology_advisories(root):
+    """A1 (undated Diary text) and A2 (`next:` is not one step), as advisory
+    strings. Gated on `level: L3` and on a date the file carries -- never an
+    mtime -- so L1/L2 work and anything written before the epoch see nothing."""
+    epoch = parse_iso(CHRONOLOGY_EPOCH)
+    out = []
+    for p, meta, text in list_analyses(root):
+        started = _meta_date(meta, "start_date")
+        if str(meta.get("level", "")).upper() != "L3" or not started or started < epoch:
+            continue
+        section = section_lines(text, DIARY_SECTION)
+        if section is None:
+            continue
+        head, body = section
+        rel = "solutions/" + p.name
+        lines = undated_diary_lines(body)
+        preface = [(n, t) for n, t in lines if not t.startswith("### ")]
+        if preface:
+            out.append(f"{rel}: line {head + preface[0][0]}: Diary text '{preface[0][1][:60]}' "
+                       "comes before the first dated entry -- open entries with "
+                       "**YYYY-MM-DD — label.**, and write the current state as the latest "
+                       "dated entry")
+        for n, t in lines:
+            if t.startswith("### "):
+                out.append(f"{rel}: line {head + n}: Diary heading '{t[:60]}' is not a dated "
+                           "entry -- open entries with **YYYY-MM-DD — label.**")
+    for p, meta in list_workstreams(root):
+        updated = _meta_date(meta, "updated")
+        if str(meta.get("level", "")).upper() != "L3" or not updated or updated < epoch:
+            continue
+        nxt = str(meta.get("next") or "").strip()
+        if len(nxt) > NEXT_MAX_CHARS:
+            out.append(f"audit/{p.name}: next: is {len(nxt)} chars (> {NEXT_MAX_CHARS}): one "
+                       "next step here, the state goes to the Diary as a dated entry")
+    return out
+
+
+def _open_units(root):
+    """{id: {analysis name}} for the tree's open L3 units: an L3 ANALYSIS that is
+    PLANNED or IN_PROGRESS, or a request record (L3 only, r26) whose `analysis:`
+    is absent from the tree or names such an open ANALYSIS. A closed unit's
+    record, kept forever, does not count."""
+    units, present, open_names = {}, set(), set()
+    for p, meta, _ in list_analyses(root):
+        present.add(p.name)
+        if (str(meta.get("level", "")).upper() == "L3"
+                and meta.get("status") in ("PLANNED", "IN_PROGRESS")):
+            m = UNIT_ID_RE.search(str(meta.get("id") or ""))
+            if m:
+                open_names.add(p.name)
+                units.setdefault(m.group(1), set()).add(p.name)
+    req = ai_path(root, "audit", "requests")
+    if req.is_dir():
+        for p in sorted(req.glob("REQUEST_*.md")):
+            meta = load_frontmatter(read_text(p).splitlines())
+            name = str(meta.get("analysis") or "").strip().strip("'\"`")
+            m = UNIT_ID_RE.search(str(meta.get("unit") or meta.get("id") or ""))
+            if m and name and (name not in present or name in open_names):
+                units.setdefault(m.group(1), set()).add(name)
+    return units
+
+
+def _git_out(root, *args, timeout=30):
+    r = subprocess.run(["git", *args], cwd=str(root), capture_output=True, text=True,
+                       encoding="utf-8", errors="replace", timeout=timeout)
+    return r.stdout if r.returncode == 0 else None
+
+
+def ids_on_other_refs(root, max_refs=ID_SCAN_MAX_REFS):
+    """[(id, mine, theirs, [refs])] -- an open unit's id that another ref (heads,
+    remotes, tags) uses for a DIFFERENT analysis. Identity is the ANALYSIS file
+    name, declared by the ANALYSIS or announced by a request record's
+    `analysis:`. One `git grep` over local refs, fixed arguments only (T8);
+    as fresh as the last fetch. [] with no open L3 unit or no git; None when
+    skipped -- above `max_refs` refs, or git failed or timed out -- so the
+    caller can say the check did not run instead of reporting it clean."""
+    mine = _open_units(root)
+    if not mine or not git_available(root):
+        return []
+    try:
+        head = (_git_out(root, "rev-parse", "HEAD") or "").strip()
+        listing = _git_out(root, "for-each-ref",
+                           "--format=%(objectname) %(objecttype) %(*objecttype) %(refname)",
+                           "refs/heads", "refs/remotes", "refs/tags")
+        if listing is None:
+            return None
+        refs = []
+        for line in listing.split("\n"):
+            parts = line.split(" ")
+            if len(parts) == 3:                     # %(*objecttype) empty: not a tag
+                parts.insert(2, "")
+            if len(parts) != 4:
+                continue
+            sha, kind, peeled, ref = parts
+            # only refs that resolve to a commit can be grepped (a tag on a blob
+            # would fail the whole batch); the tree's own commit is not "another
+            # ref"; symbolic HEADs repeat a branch
+            if "commit" not in (kind, peeled) or ref.endswith("/HEAD") or sha == head:
+                continue
+            refs.append(ref)
+        if not refs:
+            return []
+        if len(refs) > max_refs:
+            return None
+        # Pathspecs are relative to cwd=root, so a docs root inside a monorepo
+        # subdirectory is found. -z keeps a path with ':' or non-ASCII intact
+        # (quotePath off); -n plus the fence lines confine hits to frontmatter.
+        docs = docs_dir()
+        chunks = []
+        for i in range(0, len(refs), ID_SCAN_REFS_PER_CALL):   # command-line length
+            r = subprocess.run(
+                ["git", "-c", "core.quotePath=false", "grep", "-z", "-n", "-I", "-E",
+                 r"^(id|unit|analysis):|^---\s*$", *refs[i:i + ID_SCAN_REFS_PER_CALL],
+                 "--", f"{docs}/solutions/ANALYSIS_*.md", f"{docs}/audit/requests/REQUEST_*.md"],
+                cwd=str(root), capture_output=True, text=True, encoding="utf-8",
+                errors="replace", timeout=60)
+            if r.returncode not in (0, 1):                     # 1 = no match
+                return None
+            chunks.append(r.stdout)
+    except Exception:
+        return None
+    per = {}
+    for line in "".join(chunks).split("\n"):     # not splitlines: \x1c.. are content
+        parts = line.split("\0")
+        if len(parts) != 3 or ":" not in parts[0] or not parts[1].isdigit():
+            continue
+        ref, path = parts[0].split(":", 1)          # a ref name cannot hold ':'
+        content = parts[2].rstrip("\r")
+        st = per.setdefault((ref, path), {"fences": 0, "kv": {}})
+        if int(parts[1]) == 1 and content.strip() == "---":
+            st["fences"] = 1                        # frontmatter opens on line 1
+        elif st["fences"] == 1 and content.strip() == "---":
+            st["fences"] = 2                        # ...and closes here
+        elif st["fences"] == 1:
+            key, _, val = content.partition(":")
+            st["kv"].setdefault(key, val.strip())
+    found = {}
+    for (ref, path), st in per.items():
+        kv = st["kv"]
+        fname = path.replace("\\", "/").rsplit("/", 1)[-1]
+        name = fname if fname.startswith("ANALYSIS_") else kv.get("analysis", "").strip("'\"`")
+        m = UNIT_ID_RE.search(kv.get("id") or kv.get("unit") or "")
+        if not (m and name) or m.group(1) not in mine or name in mine[m.group(1)]:
+            continue
+        short = re.sub(r"^refs/(heads|remotes|tags)/", "", ref)
+        found.setdefault((m.group(1), name), [])
+        if short not in found[(m.group(1), name)]:
+            found[(m.group(1), name)].append(short)
+    return sorted((fid, ", ".join(sorted(mine[fid])), theirs, sorted(refs_))
+                  for (fid, theirs), refs_ in found.items())
+
+
+def id_advisories(root):
+    """A3 as advisory strings, for every entry point's `check`."""
+    hits = ids_on_other_refs(root)
+    if hits is None:
+        return [f"id check skipped (more than {ID_SCAN_MAX_REFS} refs, or git grep failed "
+                "or timed out) -- choose a new unit's id after fetching, as the first id "
+                "free on every ref"]
+    out = []
+    for fid, mine, theirs, refs in hits:
+        more = f" (+{len(refs) - 1} more)" if len(refs) > 1 else ""
+        out.append(f"id {fid} ({mine}) is also used by {theirs} on {refs[0]}{more}: choose "
+                   "the first id free on every ref -- if this is the same unit under its "
+                   "old name, ignore it")
+    return out
+
+
 def design_review_due(meta):
     """True when an L3 ANALYSIS owes a design-review row (review.md moment 1):
     implementation has started or finished, and it began on/after the gate
@@ -1556,6 +1856,7 @@ def cmd_validate(root, strict=False, hybrid=False):
             except ValueError:
                 warnings.append("audit/handoff.md: date not parseable")
 
+    advisories.extend(chronology_advisories(root))   # A1, A2 (F-073)
     for a in advisories:
         print(f"[note]  {a}")
     for w in warnings:
@@ -1925,6 +2226,10 @@ def cmd_check(root, strict=False, hybrid=False, extra_validate=None, extra_secti
     rc_v = cmd_validate(root, strict=strict, hybrid=hybrid)
     if extra_validate is not None:
         rc_v = max(rc_v, extra_validate())
+    # A3 (F-073): check only -- it reads git refs, and validate stays file-local.
+    # Advisory: printed, never part of any rc.
+    for a in id_advisories(root):
+        print(f"[note]  {a}")
     print("\n===== stale =====")
     rc_s = cmd_stale(root, hybrid=hybrid)
     rcs = [("validate", rc_v), ("stale", rc_s)]

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

@@ -255,7 +255,7 @@ Context (agent): "the question it answered, quoted"
 
 ## ai_docs/solutions/ANALYSIS_[feature_name].md
 
-The frontmatter is the source of truth for the feature state (the `features_history.md` index is generated from it).
+The frontmatter is the source of truth for the feature state (the `features_history.md` index is generated from it). Choose a new unit's `id:` **after fetching**, as the first id free on every branch and tag the checkout can see: `check` names an open L3 unit whose id another ref uses for a different analysis.
 
 ```markdown
 ---
@@ -334,8 +334,13 @@ CONTESTED: none.
      explicit alternative verification and reason. -->
 
 ## Diary / Current State
-<!-- updated at every milestone: where I am, last problem, next step.
-     It is the handoff source for this feature. -->
+<!-- One dated entry per event, newest last. Open every entry with its date, once:
+       **YYYY-MM-DD — label.** body
+     The latest entry IS the current state (where I am, last problem, next step),
+     dated the day it was written. An undated paragraph is read as part of the
+     dated entry above it, so a new event never starts undated; `####`
+     sub-headings inside an entry are fine. It is the handoff source for this
+     feature. -->
 ```
 
 Allowed frontmatter states: `PLANNED` | `IN_PROGRESS` | `COMPLETED` | `CANCELLED`. `COMPLETED` requires `end_date`. (The validator also accepts the deprecated Italian keys `stato`/`livello`/`data_inizio`/`data_fine` in existing projects.)
@@ -349,6 +354,7 @@ Allowed frontmatter states: `PLANNED` | `IN_PROGRESS` | `COMPLETED` | `CANCELLED
 ## Time-box
 ## What was tried
 ## Answer / Outcome
+<!-- open with **YYYY-MM-DD — label.**, dated the day the answer was reached -->
 ## Consequences
 <!-- max 1 page. Spike code is NOT mergeable: for production reclassify L2/L3. -->
 ```
@@ -599,6 +605,12 @@ tested against (`SKILL.md` Rule Zero, *An open unit absorbs*): the topics, front
 counterpart the unit covers — on a live front, front-wide ("K-02: every source and
 statement on X"). The registry does not show it.
 
+`next:` is **the next concrete step, in one sentence** (at most 240 characters;
+`validate` notes a longer one on an L3 file updated under the rule). What happened,
+and the state of the work, go to the Diary as a dated entry: the registry is what
+`orient` shows at every session start, cut at a fixed size, so a paragraph here
+costs the next agent the rows below it.
+
 ## ai_docs/audit/project_notes.md — the registry's project-wide notes (source)
 
 Plain lines, no frontmatter, appended verbatim to the generated registry under
@@ -606,6 +618,10 @@ Plain lines, no frontmatter, appended verbatim to the generated registry under
 everyone rather than for one workstream. It exists so that generating the registry
 cannot destroy notes that belong to no workstream.
 
+A note that records an **event** (a release, a migration, an incident) opens with its
+date — `**YYYY-MM-DD — label.**` — so it is read as one; a **standing** note (an
+environment quirk) stays undated, and is not an event.
+
 ## ai_docs/strategic/architecture.md and existing_features.md
 
 Canonical docs: they open with the header (`description:`/`status:`) so they enter the `INDEX.md` manifest cleanly.
@@ -708,6 +724,8 @@ extracted_through: p=212
 Handed over by <who>, <context in one line>.
 ```
 
+`date:` is **the day the source was received** — the date a chronology reads for it.
+
 `supersedes:` is what makes "which claims rest on a superseded version" answerable —
 without it the two content-addressed files are unrelated. `extractor:` pins the stored
 canonical extraction (`<name>-<hash8>.txt`) that offset locators address.