@antoneeo/agentic-sdlc-skill 1.39.0 → 1.41.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.41.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.
+
+## [1.40.0] - 2026-10-17
+
+### Changed
+- F1: closing the last open workstream now empties the generated registry `audit/handoff.md` instead of leaving its stale row behind: with zero `HANDOFF_*.md` sources `index` rewrites it empty (keeping `project_notes.md`), and `validate` reports a generated registry that still has rows but no sources as an error.
+- F-069: `graph`, `check`, `stale` and the session-start count are faster on a mature knowledge base, with byte-identical output. Citations of superseded claim ids are found with one pass per living document instead of one scan per (document, id) pair, and one check run reads and resolves each cited extraction once instead of once per claim row. On a synthetic ledger of 2183 rows and 1000 living documents, `graph` drops from 14 s to 4 s. No new flag.
+
 ## [1.39.0] - 2026-10-13
 
 ### Changed

package/gemini-extension.json

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

package/package.json

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

package/scripts/init.js

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

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

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

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

@@ -1,6 +1,6 @@
 ---
 name: agentic-sdlc
-version: 1.39.0
+version: 1.41.0
 description: Documentation-First SDLC protocol with risk-proportional triage, Vision as a guide, a complete Standalone mode and optional symbiosis with devPNT. Use for features, significant bugs, refactors, audits and documented maintenance.
 author: Antonio Pinto (https://github.com/Antoneeo)
 copyright: (c) 2026 Antonio Pinto
@@ -90,7 +90,7 @@ Triage decides IF documentation is due; this table decides WHICH document each e
 | `solutions/MERGE_REVIEW_[feature].md` | Every L3, after the closure review: the integrator's brief — what to review (`sdlc_check.py review-map`), what was verified by which gate, what only a human can judge (`templates.md`). The PR description links it. | 5 |
 | `vision/features/VISION_[feature].md` | Feature known multi-milestone at analysis time, OR the retroactive trigger: you are about to create the SECOND `ANALYSIS_*` on the same theme — extract the shared feature vision first, then let both analyses reference it. | 3 |
 | `audit/handoff.md` (workstream registry) | **Never by hand — generated by `sdlc_check.py index` from the `HANDOFF_*.md` sources**, and `validate` errors when the two disagree. Regenerate at every L3 closure and at session end; the `Date:` header is derived, so no writer touches it. It is an inventory for lookup, not a work board: no assignment, no due dates, no ordering, no holder. | 5 / session end |
-| `audit/HANDOFF_[feature].md` | **One per OPEN workstream, with or without volatile state** — it is the authored home of that workstream's registry row (frontmatter `workstream`/`level`/`branch`/`status`/`since`/`next`/`details`/`updated`), so no file means no row. Also carries the resume logistics; **the ANALYSIS Diary keeps the durable narrative (DRY)**, and this file is DELETED at closure — deleting it *is* removing the row. | 4 / 5 / session end |
+| `audit/HANDOFF_[feature].md` | **One per OPEN workstream, with or without volatile state** — it is the authored home of that workstream's registry row (frontmatter `workstream`/`level`/`branch`/`status`/`since`/`next`/`details`/`updated`), so no file means no row. 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. Also carries the resume logistics; **the ANALYSIS Diary keeps the durable narrative (DRY)**, and this file is DELETED at closure — deleting it *is* removing the row. | 4 / 5 / session end |
 | `audit/project_notes.md` | A note true for the whole project rather than for one workstream (release pending, environment quirk). Appended verbatim to the generated registry; it exists so regenerating cannot destroy notes that belong to no workstream. | 5 / session end |
 | `audit/handoff.md` — converting an existing project (hand-written or pre-1.17 narrative) | **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 file exists nothing generates, nothing errors, and the file is read verbatim exactly as today. | 5 / session end |
 | `audit/audit_plan.md` (Standalone) | Bootstrap, and whenever a mapped area changes state (`sdlc_check.py mark` records the reference — git hash, else UTC timestamp). | 1 |
@@ -204,7 +204,7 @@ Hybrid L3:
 ### 4. Development and Testing
 
 - Implement only after the documentation gate required by the level. **Flip the ANALYSIS frontmatter `PLANNED` → `IN_PROGRESS` when implementation starts** — that flip is what `gate` and the handoff registry key on, and nothing else performs it.
-- Isolate the work: run an L3 change on its own branch. In Hybrid, prefer a git worktree from the start — a running devPNT server locks `.devpnt/*.db` and blocks in-place branch switches/merges in the primary worktree.
+- Isolate the work: run an L3 change on its own branch. In Hybrid, prefer a git worktree from the start — a running devPNT server locks `.devpnt/*.db` and blocks in-place branch switches/merges in the primary worktree. 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).
 - Modify surgically, consistently with the plan.
 - Implementation work follows the TDD discipline in `tdd.md` (RED/GREEN/REFACTOR — the L2/L3 default; record the reason when it does not apply).
 - Before implementing (L2/L3; L1 exempt), **consult the guide router** — the verdict already declared with the triage level (`## Operative Guides`). Re-run the lookup here only if the work has moved to a topic the first one did not cover, and say so if the verdict changes.

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

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

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

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