@sabaiway/agent-workflow-memory 3.2.0 → 4.1.0

package/CHANGELOG.md

@@ -4,6 +4,120 @@ All notable changes to the memory substrate. Versions are this **package's** npm
 they are distinct from the **deployment-lineage** stamp written into a project's
 `docs/ai/.memory-version` (which tracks the shared `agent-workflow` lineage, head `3.0.0`).
 
+## 4.1.0 — the ADR rotation carries your inbound links with it (AD-087)
+
+Rotating `decisions.md` used to be a link-breaking event: `archive-decisions.mjs` moved ADR
+blocks out of the HOT window into per-record `adr/` files while every `decisions.md#ad-NNN…`
+link elsewhere in your `docs/ai/` kept pointing at a heading that was no longer there — and
+neither `--check` nor `--dry-run` would say a word about it. One deployed project measured 114
+such inbound anchors (23 aimed at the first tier a rotation would move) and had raised its HOT
+cap twice specifically so the rotation never runs. A safety valve nobody dares open is not
+shipped; this release makes the crossing carry its links:
+
+- **Rotate and `--migrate --apply` rewrite inbound links.** Every non-fenced
+  `decisions.md#ad-NNN…` link under `docs/ai/` whose id is in the moved set is rewritten to the
+  record file. The heading-slug fragment is preserved — each record holds the verbatim
+  `## AD-NNN — title` block, so the same anchor resolves — and the leading relative prefix
+  survives (`adr/` is a sibling of `decisions.md`). Migrate additionally rewrites links into
+  the retired monolith archives it deletes, each target computed relative to its linking file.
+- **A conservation invariant guards every rewrite.** The rewrite set is computed and verified
+  before the run's first write: every moved-id link rewritten, every other byte identical,
+  per-file and total matched-link counts equal before and after — any mismatch exits 1 with
+  nothing written.
+- **The write order is pinned crash-safe:** records → inbound rewrites → HOT rewrite / monolith
+  removal. Every interrupted intermediate state re-runs to completion; previously a crash after
+  the HOT write re-ran as «nothing to rotate» with the orphans permanent.
+- **`--check` now proves reference integrity.** A `decisions.md#ad-NNN…` anchor whose id has
+  left the HOT window (stale even when the id exists as an archived record) and an
+  `adr/AD-NNN-….md` link naming no existing record file both fail exit 1, every violation
+  listed with `file:line`. A tree with matches but no ADR substrate fails too; the early SKIP
+  remains only for trees with zero matches.
+- **`--dry-run` prints the rewrite set** (`file:line`, old target → new target) alongside the
+  move set and writes nothing; plain `--migrate` prints the same summary, and
+  `--migrate --apply --dry-run` refuses loudly instead of silently writing.
+- **Fail-closed edges, each red-tested:** a rewrite-form link targeting a moved id inside the
+  ADR corpus itself (HOT preamble or block, a record, a monolith tier) refuses pre-write with
+  `file:line` — convert the link (e.g. to `[[AD-NNN]]`) and re-run; a HOT block ABOUT to move
+  that itself links a retained id or carries a record-form link refuses pre-write (the verbatim
+  move would silently break the link from inside the record); symlinked `.md` files and
+  directories in the scan scope refuse loudly; an unparseable scanned file (unclosed fence)
+  aborts either write path before any write; a stale two-pass snapshot refuses instead of
+  rewriting from old bytes.
+
+**Stated limitations:** the scan is line-scoped (a link hand-wrapped across a line break is not
+matched — the same accepted residual as the preamble contract), inline code is not tracked (a
+backtick-wrapped link counts as live), and YAML frontmatter is opaque metadata — a link inside
+it is neither rewritten nor checked, and is preserved byte-exactly on every write. The boundary
+is `docs/ai/` — links in README or agent entry points outside it are neither rewritten nor
+checked.
+
+**Upgrading:** the tool itself has nothing to reconfigure — the rewrite is additive, and on a
+healthy tree whose links resolve the new assertions stay green. **Reaching your deployment:** a
+fresh Node-project bootstrap through the memory 4.1.0 skill — or a clean-layout upgrade where
+the pair is entirely absent — copies the fixed pair from this package (a No-Node project skips
+the scripts; a legacy-monolith layout goes through the consented migration ask); a normal
+upgrade of an already-deployed pair preserves it byte-for-byte (local edits are never
+clobbered — drift repair belongs to a lineage migration), so an existing deployment is NOT
+auto-refreshed by this release; a verified drift-safe refresh lane is queued family work. If
+`--check` then reports a `dead ADR anchor` or `dead ADR record link`, those are real orphans it
+found — each line names the file, line and dead target; fix or remove the link, or re-point it
+at an existing `adr/` record (or the `[[AD-NNN]]` form); with the links live, rotation is safe
+to run again, so a cap raised only to avoid it can come back down. Any other `--check` red
+carries its own printed diagnosis.
+
+## 4.0.0 — the archivers stop reporting green on files they did not understand (AD-084)
+
+> ### ⚠ BREAKING — the rotation gates fail CLOSED now
+>
+> A `--check` that silently passed over unparseable content now **refuses with `file:line` and a
+> remedy**. If your changelog carries a malformed date heading, an issue claims resolution without
+> a recognisable date, or one section carries both an open `Status:` and a dated `Resolved:` line,
+> the gate goes red — that red is the fix arriving, not a regression. Every refusal message names
+> exactly what to change. Nothing is ever rewritten on a refused input.
+
+For years the failure mode of these scripts was a **green lie**: a changelog gate that printed
+`OK` over a file it parsed nothing from (one real deployment passed 36 consecutive sessions
+unparsed), and an issues gate that reported `archivable: 0` while nine resolved sections aged in
+place and the file crept to one line under its cap. This release ends the class, not the instance:
+
+- **One shared block tokenizer** (`references/scripts/markdown-blocks.mjs`, NEW): frontmatter,
+  fenced regions, heading tokens outside fences; CRLF-safe; an unclosed fence is a loud error.
+  All three archivers read through it — a structural test refuses any future raw-line scan.
+- **Fail-closed contract, all three archivers:** every unit-shaped heading either parses or
+  refuses naming `file:line`; every verdict names the counts it acted on; a zero-unit outcome is
+  a stated decision; every reading mode refuses identically and **writes nothing** on refusal.
+- **ISO dates are first-class:** `## YYYY-MM-DD — title` entry headings parse everywhere the
+  legacy dotted form does; each entry re-emits in its **source form, verbatim**. Write ISO; the
+  dotted archives keep working untouched.
+- **The issues marker contract:** a resolved issue is recognised by a line-leading
+  `- **Resolved:** YYYY-MM-DD …` or `- **Status:** … FIXED (YYYY-MM-DD) …` field — the shapes
+  real files use, list prefix optional, emphasis/emoji variants read, both separators, strict
+  calendar validation (the old code accepted `2026.02.30` — JS Date silently rolls it into
+  March). Strikethrough is cosmetic in BOTH directions: the dated marker decides alone, and an
+  explicit open `Status:` keeps a reopened-but-still-struck issue open. A resolution claim
+  **without** a recognisable date, a struck heading with an unrecognised status word, and
+  contradictory open+resolved state all refuse loudly instead of being skipped forever. The
+  exact pre-4.0.0 template example section stays inert, so a pristine legacy deployment never
+  reds its own gate.
+- **The issues section model conserves your file:** category headings (`## 🟢 Resolved`), the
+  preamble and the canonical closing footer belong to the FILE and survive rotation; an issue
+  section contains only its own issue; rewrites are verbatim, guarded by an element-wise
+  partition tripwire and a line-accounting conservation test. (Previously the first real
+  rotation would have carried the category heading and footer into the archive and deleted them
+  from your file.) Stated residual: a **reworded or localized** closing note is not recognised
+  as the footer and travels with the last archived issue into the archive — conserved and
+  recoverable, never lost.
+- **The templates stopped contradicting the parsers:** the changelog seed teaches ISO on both
+  `{{DATE}}` consumers; the known-issues template teaches ONE resolved shape inside a fenced
+  sample in the file preamble, so neither a fresh project nor a section inserted under a
+  category can ever red or lose the teaching text.
+
+**Upgrading:** run your three `--check` gates once. If they refuse, the message names the line
+and the remedy (typically: add the missing resolution date, repair a malformed date heading, or
+delete the stale half of an open+resolved contradiction). The new `markdown-blocks.mjs` rides
+every deploy path — old-layout projects get it companion-seeded by the kit's
+`migrate-adr-store --apply`.
+
 ## 3.2.0 — the ADR rotation can be asked whether a seed is safe, without seeding (AD-083)
 
 `archive-decisions.mjs --write-navigator` now honours `--dry-run`. It runs exactly the checks the

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-memory
 description: Deploy or upgrade a portable AI-agent memory substrate in any project — an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) and a structured `docs/ai/` context store with cap/archive/index enforcement. Use when the user wants to bootstrap `docs/ai/`, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-memory` / `/agent-workflow-memory upgrade`. Triggers on "set up the memory system", "deploy the AI memory here", "bootstrap docs/ai", "upgrade the memory substrate". This is the substrate only — the workflow methodology (plan→execute→review, queue, Cleanup) is owned elsewhere and injected into AGENTS.md by the family composition root.
 disable-model-invocation: true
 metadata:
-  version: '3.2.0'
+  version: '4.1.0'
 ---
 
 # agent-workflow-memory

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-memory",
   "kind": "memory-substrate",
-  "version": "3.2.0",
+  "version": "4.1.0",
   "provides": ["context"],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "3.2.0",
+  "version": "4.1.0",
   "description": "Portable, cross-agent memory substrate for AI coding agents — an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement, deployable standalone or as part of the agent-workflow family. The memory layer of the agent-workflow family.",
   "keywords": [
     "ai-agents",