@sabaiway/agent-workflow-memory 1.12.0 → 2.0.0

package/CHANGELOG.md

@@ -2,7 +2,58 @@
 
 All notable changes to the memory substrate. Versions are this **package's** npm versions;
 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 `1.3.0`).
+`docs/ai/.memory-version` (which tracks the shared `agent-workflow` lineage, head `2.0.0`).
+
+## 2.0.0 — One-file-per-ADR store: the 3-tier decisions cascade retired (AD-051)
+
+A **MAJOR** release (BREAKING; co-released with the workflow kit 1.42.0). The deployment-lineage
+head bumps `1.3.0` → `2.0.0` — the first structural `docs/ai` change (a new `docs/ai/adr/` tree;
+the WARM/COLD decisions-archive monolith tiers retired). **Nothing auto-migrates:** an existing
+deployment keeps working on its old layout, old rotator included, until it opts in (below).
+
+**Breaking.**
+- `references/scripts/archive-decisions.mjs` is REPURPOSED in place (same path, same pre-commit
+  hook slot, same `decisions-rotation` gate id): instead of rotating HOT `decisions.md` → WARM
+  `history/decisions-archive.md` → a single COLD monolith whose cap was raised release after
+  release, the rotator now EXPLODES the oldest ADRs beyond the HOT cap into one immutable MADR
+  record per ADR at `docs/ai/adr/AD-NNN-slug.md` (body verbatim; inline 6-field frontmatter +
+  `status`/`date`/`supersedes`/`supersededBy` lifecycle keys; slug frozen at creation). A record
+  is O(1) forever — no archive cap is ever raised again, and there is no COLD tier to exhaust.
+- A default or `--check` run that finds a legacy `history/decisions-archive*.md` monolith fails
+  LOUD ("run `--migrate` first") — the new rotator never half-explodes an un-migrated tree and
+  never reports green over one.
+- The ADR id grammar widens to `AD-\d{3,}` with NUMERIC ordering everywhere (AD-200 precedes
+  AD-1000 — never lexical).
+
+**Migration (opt-in, never automatic).**
+- The one-time `--migrate` (dry-run by default; `--migrate --apply` to write) explodes the
+  monolith tiers into `adr/` records under a fail-loud conservation check: the full ADR corpus —
+  the union HOT ∪ monolith tiers ∪ any already-written `adr/` records (the crash-resumable core;
+  a same-id BODY CONFLICT across sources is refused) — must repartition EXACTLY into retained-HOT
+  ∪ written records, nothing lost, added, double-counted, or edited. Before any destructive write
+  it stores a durable timestamped snapshot of `decisions.md` + both monoliths into the GIT DIR
+  (a stated out-of-tree fallback on a non-git deployment; fails loud if neither is writable).
+  `docs/ai` is commonly git-ignored, so git history alone can NOT recover a deleted monolith —
+  the snapshot is the recovery path. The apply is idempotent and crash-resumable; removal never
+  precedes conservation + the snapshot.
+- On an upgrade crossing this major, `bin/install.mjs` prints a GENERIC one-time advisory: run
+  your workflow toolkit's ADR-store migration command in each already-deployed project (it
+  snapshots, refreshes the enforcement scripts, and migrates in one consent-gated step). This
+  installer targets the global skill dir and never touches a project itself.
+
+**New.**
+- `docs/ai/adr/log.md` — the ON-DEMAND active-set navigator: currently-governing heads
+  (supersession COMPUTED corpus-wide from the two-way `supersedes`/`supersededBy` chain — a new
+  superseding ADR needs no predecessor-file edit) + a recent window; a superseded record drops out
+  of the list but stays reachable by filename, grep, and the chain. `--write-navigator`
+  regenerates it AND re-triggers the docs-index regen. No committed full O(n) ledger.
+- `references/scripts/check-docs-size.mjs` — `docs/ai/adr/` collapses to ONE aggregate `index.md`
+  row (`adr/ — N records (AD-001 … AD-NNN)`), while every record body stays individually
+  cap-checked; `docs/ai/index.md` stays bounded at O(1) as records accumulate.
+- Seeded templates: the new-scheme `decisions.md` HOT-window seed, the `adr-record.md` MADR
+  authoring reference (a skill-side reference — never copied into a project's `docs/ai/`), and a
+  seed `adr/log.md` byte-equal to the generator over the seeded HOT — a fresh bootstrap is
+  `--check`-green on its first commit.
 
 ## 1.12.0 — Verification-profile template + the docs-index-on-rotation regen (BUGFREE-3, AD-049)
 

package/README.md

@@ -7,7 +7,7 @@ future agent — including a fresh session of yourself — can reconstruct proje
 ~60 seconds, find the current task, and avoid repeating past mistakes.
 
 This is the **memory layer** of the `agent-workflow` family.
-It owns the substrate only — `docs/ai/`, the entry point, caps / 3-tier archive / index gate,
+It owns the substrate only — `docs/ai/`, the entry point, caps / rolling changelog archive / the one-file-per-ADR store / index gate,
 the Node enforcement scripts, the pre-commit hook, the templates, and the three setup
 contracts (visibility / conversational language / agent attribution). It deliberately **knows
 nobody else** in the `agent-workflow` family: the **workflow methodology** (plan → execute →
@@ -44,7 +44,7 @@ Open your agent inside a project and run the skill:
 
 Two independent axes: this package's **npm version** vs the **deployment-lineage** stamp the
 substrate writes into a project. They are not the same number. `.memory-version` tracks the
-shared `agent-workflow` deployment lineage (head `1.3.0` today), **not** this package's
+shared `agent-workflow` deployment lineage (head `2.0.0` today), **not** this package's
 version. A project bootstrapped by the kit's fallback carries a `.workflow-version`; when this
 substrate is later installed, `migrations/legacy-stamp-takeover.md` copies that value verbatim
 into `.memory-version` and never deletes the legacy stamp. See `migrations/README.md`.

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: '1.12.0'
+  version: '2.0.0'
 ---
 
 # agent-workflow-memory
@@ -14,7 +14,7 @@ reconstruct project context in ~60 seconds, find the current task, and avoid rep
 mistakes.
 
 The substrate is **stack-agnostic memory** — `docs/ai/` structure, entry-point doc, session
-protocols, frontmatter caps, 3-tier archive, index-freshness gate. Enforcement ships as **Node
+protocols, frontmatter caps, one-file-per-ADR archive, index-freshness gate. Enforcement ships as **Node
 `.mjs` scripts** (the reference implementation; non-Node stacks follow the same policy
 manually).
 
@@ -42,7 +42,7 @@ What this substrate owns vs what it only points at. The methodology + orchestrat
 | Concern | Owner | In the deployed `AGENTS.md` |
 |---|---|---|
 | Entry point, Memory Map, session protocols (Start / During / Complete) | **memory** (this skill) | authored from templates |
-| `docs/ai/` files, frontmatter caps, 3-tier archive, index-freshness gate | **memory** | `docs/ai/*` + scripts + hook |
+| `docs/ai/` files, frontmatter caps, one-file-per-ADR archive, index-freshness gate | **memory** | `docs/ai/*` + scripts + hook |
 | Visibility / conversational-language / agent-attribution contracts | **memory** | the three `AGENTS.md` blocks |
 | Deployment-lineage stamp | **memory** | `docs/ai/.memory-version` |
 | Plan→Phase→Step vocabulary, lifecycle, `queue.md`, mandatory Cleanup | **methodology** (not this skill) | the empty `workflow:methodology` slot — filled by the composition root |
@@ -99,15 +99,17 @@ bootstrapping over a live system, but the user makes the final call.
    from `${CLAUDE_SKILL_DIR}/references/templates/AGENTS.md` and symlink `CLAUDE.md -> AGENTS.md`
    (`ln -s AGENTS.md CLAUDE.md`). **Leave BOTH pointer slots (`workflow:methodology` +
    `workflow:orchestration`) exactly as shipped — empty.** Filling them is the composition root's job.
-6. **Deploy `docs/ai/`.** Create the files + `pages/` from
-   `${CLAUDE_SKILL_DIR}/references/templates/` (every non-`AGENTS.md` template, including the three
-   seeded, **user-editable** strict-JSON configs: `docs/ai/orchestration.json` — the per-project
-   recipe defaults the composition root's `procedures` advisor reads — `docs/ai/gates.json` —
-   the project's gate declaration, an empty list to fill with its own verification commands,
-   consumed by the composition root's gate runner — and `docs/ai/verification-profile.json` — the
-   OPTIONAL fold-completeness verification profile (the language-independence contract; the seeded
-   default reproduces the composition root's default V8 + node:test behaviour, delete it for exactly
-   that)). Keep each `.md` file's frontmatter.
+6. **Deploy `docs/ai/`.** Create the files + `pages/` + the seed `adr/` store from
+   `${CLAUDE_SKILL_DIR}/references/templates/` (every non-`AGENTS.md`, non-`adr-record.md` template —
+   the latter is a skill-home authoring reference, never deployed). This deploys the HOT ADR window
+   `docs/ai/decisions.md` **and** the seed navigator `docs/ai/adr/log.md` (its `adr/` subdir copies
+   in wholesale), plus the three seeded, **user-editable** strict-JSON configs:
+   `docs/ai/orchestration.json` — the per-project recipe defaults the composition root's `procedures`
+   advisor reads — `docs/ai/gates.json` — the project's gate declaration, an empty list to fill with
+   its own verification commands, consumed by the composition root's gate runner — and
+   `docs/ai/verification-profile.json` — the OPTIONAL fold-completeness verification profile (the
+   language-independence contract; the seeded default reproduces the composition root's default V8 +
+   node:test behaviour, delete it for exactly that). Keep each `.md` file's frontmatter.
 7. **Fill templates** per the table below.
 8. **Install enforcement (Node projects).** Copy `${CLAUDE_SKILL_DIR}/references/scripts/*.mjs`
    (+ `*.test.mjs`) into the project's `scripts/`. **No Node runtime** → skip this + the hook;
@@ -120,7 +122,7 @@ bootstrapping over a live system, but the user makes the final call.
    append-only (never duplicate an existing line), then **verify `git status` shows them ignored**.
    Never the machine-global excludes; never edit `package.json`.
 10. **Stamp the deployment lineage.** Write the **deployment-lineage head** into
-    `docs/ai/.memory-version` (one semver line). The lineage head is **`1.3.0`** (the
+    `docs/ai/.memory-version` (one semver line). The lineage head is **`2.0.0`** (the
     `LINEAGE_HEAD` constant in `scripts/stamp-takeover.mjs`) — the shared `agent-workflow`
     lineage, a **separate axis** from this package's npm version (the two may even coincide by
     accident; see *Stamp = lineage head, not package version*). Use the atomic writer in
@@ -146,7 +148,8 @@ Fill strategy:
 | `current_state.md`, `architecture.md`, `env_commands.md`, `technical_specification.md`, `pages/index.md` | Fill with **real** recon data. |
 | `tech_reference.md` | Carry over real configs/patterns found in deps. |
 | `active_plan.md`, `handover.md` | TODO seed. |
-| `decisions.md` | Seed `AD-001` (adopting this memory system). |
+| `decisions.md` | The HOT ADR window — seed `AD-001` (adopting this memory system), newest at the bottom. |
+| `adr/log.md` | The seed navigator — deployed as-is (the generator over the seeded HOT); regenerated by `archive-decisions.mjs`, never hand-edited. |
 | `known_issues.md`, `changelog.md`, `pages/shared-patterns.md` | Empty template / first bootstrap entry. |
 
 ### Mode: upgrade
@@ -158,7 +161,7 @@ Fill strategy:
    `scripts/stamp-takeover.mjs` decides the action per state; the Markdown migration is the
    no-Node manual fallback. If **no** stamp exists at all, offer a conservative re-bootstrap.
 2. **Never-downgrade gate FIRST, then the stamp-independent hidden-mode reconcile (D14).** Compare the
-   stamp to the **deployment-lineage head** (`LINEAGE_HEAD`, `1.3.0`). **Greater than the head, or
+   stamp to the **deployment-lineage head** (`LINEAGE_HEAD`, `2.0.0`). **Greater than the head, or
    unparseable → STOP and report immediately, before ANY write** (never downgrade or guess, and never
    touch `.git/info/exclude`). This STOP is one of the only two places the number is shown (see
    *Version disclosure* below): tell the user **the `docs/ai` structure version** their deployment
@@ -188,13 +191,23 @@ Fill strategy:
    orchestration `_README` note in place on an existing file is the **composition root's** job on
    its own reconcile — this substrate is standalone and only seeds-or-preserves; it owns no
    cross-package refresh helper. The gates declaration gets no note-refresh at all — authored
-   content, seed-or-preserve only.) This is why an equal-head (`1.3.0`) deployment still gains the
+   content, seed-or-preserve only.) This is why an equal-head (`2.0.0`) deployment still gains the
    config seeds **without a lineage-head bump or a migration file** (the
    stamp-independent-reconcile precedent — like the pointer slots + the hidden-mode footprint).
-   **Same gate, also stamp-independent: ensure the ADR-cascade enforcement pair** — copy
+   **Same gate, also stamp-independent: ensure the ADR-store enforcement pair** — copy
    `archive-decisions.mjs` + `archive-decisions.test.mjs` from
    `${CLAUDE_SKILL_DIR}/references/scripts/` into the project's `scripts/` **if missing**
-   (preserve an existing file byte-for-byte; skip on a No-Node project). The deployed pre-commit
+   (preserve an existing file byte-for-byte; skip on a No-Node project). **Legacy-monolith
+   gate:** if a retired `docs/ai/history/decisions-archive*.md` monolith is still on disk, do
+   **NOT** copy the pair as a silent ensure — the new-scheme rotator must **never sit beside
+   un-migrated monoliths** (its default/`--check` runs refuse such a tree). Instead ASK the
+   user; with their explicit consent copy the pair AND run the one-time conservation-checked
+   migration in the same step (`node scripts/archive-decisions.mjs --migrate` preview, then
+   `--migrate --apply` — it writes a durable pre-delete snapshot first); if the preview or the
+   apply FAILS, remove the just-copied pair (the pair was copied only because it was missing, so
+   removal restores the exact pre-ensure state) and report — the forbidden state (the new-scheme
+   rotator beside un-migrated monoliths) must never persist; without consent leave
+   the tree untouched and report the pending migration. The deployed pre-commit
    hook gains its `archive-decisions.mjs --check` line only when the hook is next refreshed via
    `node scripts/install-git-hooks.mjs`; an old hook without the line stays consistent-safe (the
    decisions gate is simply not enforced yet — never a broken hook). **Then**, if the stamp **equals** the head → the substrate is
@@ -264,7 +277,7 @@ memory substrate has none, so it relies on the STOP + the explicit ask — never
 - **Source vs target directory.** Templates/scripts are read from the skill's own dir; the
   **working directory is the target project** — never write substrate files back into the skill.
 - **Stamp = lineage head, not package version.** `.memory-version` carries the **deployment-lineage
-  head** (`1.3.0`, the shared `agent-workflow` lineage) — a **separate axis** from this package's npm
+  head** (`2.0.0`, the shared `agent-workflow` lineage) — a **separate axis** from this package's npm
   version (the two may even coincide by accident). They move independently.
 - **Both pointer slots ship empty and stay the user's.** Never author methodology or orchestration
   text into them; on upgrade, preserve their content byte-for-byte. The composition root is their only
@@ -296,9 +309,10 @@ The three setup choices each have a full contract in
 - [`references/contracts.md`](references/contracts.md) — the three setup contracts in full.
 - [`references/templates/`](references/templates/) — stack-agnostic `AGENTS.md` (with the two empty
   pointer slots — methodology + orchestration), `agent_rules.md`, the seeded user-editable
-  `orchestration.json` config, and all `docs/ai/` files to deploy.
+  `orchestration.json` config, the `adr-record.md` ADR authoring reference + the seed `adr/log.md`
+  navigator, and all `docs/ai/` files to deploy.
 - [`references/scripts/`](references/scripts/) — the Node enforcement scripts (caps + staleness +
-  index-freshness gate, 3-tier archive, hook installer) and their unit tests.
+  index-freshness gate, one-file-per-ADR archive, hook installer) and their unit tests.
 - [`scripts/stamp-takeover.mjs`](scripts/stamp-takeover.mjs) — the upgrade-time lineage state
   machine (`LINEAGE_HEAD`, atomic stamp writes) + tests.
 - [`migrations/`](migrations/) — per-version upgrade steps, incl. `legacy-stamp-takeover.md`;

package/bin/install.mjs

@@ -71,6 +71,36 @@ const compareSemver = (a, b) => {
   return firstDiff ?? 0;
 };
 
+// The memory major that retired the 3-tier ADR cascade for the one-file-per-ADR store (AD-051).
+const ADR_STORE_MAJOR = 2;
+
+// A GENERIC, project-agnostic advisory is printed exactly once — when this runner crosses UP through
+// the ADR-store major (installed below it → runner at or above it). The memory installer targets the
+// GLOBAL skill dir and knows nothing about any project (the knows-nobody DAG), so it can never DETECT
+// an old-layout deployment and must NEVER name a sibling package or a kit command — the kit's
+// project-dir-aware surfaces (status / upgrade / the migration mode) own detection + the concrete
+// command. A fresh install (installed === null) advises nothing (no prior deployment to migrate).
+export const shouldAdviseAdrMigration = (installedVersion, runnerVersion) => {
+  const from = parseSemver(installedVersion);
+  const to = parseSemver(runnerVersion);
+  if (!from || !to) return false;
+  return from[0] < ADR_STORE_MAJOR && to[0] >= ADR_STORE_MAJOR;
+};
+
+// The advisory text is GENERIC and names NO sibling package or kit command (the knows-nobody DAG);
+// the kit's project-aware surfaces own old-layout detection + the concrete migration command.
+const ADR_MIGRATION_ADVISORY =
+  `[agent-workflow-memory] note: this major retired the 3-tier ADR archive for a one-file-per-ADR store.\n` +
+  `  A project you already deployed on the OLDER decisions-archive layout must be migrated before its\n` +
+  `  ADR rotation works again — run your workflow toolkit's ADR-store migration command in that project\n` +
+  `  (its status/upgrade points you at it). New deployments already seed the new store.`;
+
+// Print the advisory exactly on a major-crossing update (AD-051). Pure over an injectable log so the
+// crossing path is unit-testable in-process (main runs only as a subprocess).
+export const maybeAdviseAdrMigration = (installedVersion, runnerVersion, log = console.log) => {
+  if (shouldAdviseAdrMigration(installedVersion, runnerVersion)) log(ADR_MIGRATION_ADVISORY);
+};
+
 // Extract the version that is a DIRECT child of the top-level `metadata:` key — never a top-level or
 // deeper-nested decoy `version:` (mirrors the manifest validator + the kit installer). Pure walk.
 const metadataVersion = (frontmatter) => {
@@ -256,6 +286,8 @@ const main = async () => {
     : 'installed';
   console.log(`[agent-workflow-memory] ${verb} v${version} -> ${tildify(target)}`);
 
+  maybeAdviseAdrMigration(installedVersion, version); // generic major-crossing ADR-store advisory (AD-051)
+
   // Same-version re-run: state observable facts only. The copy DID run (repair-on-rerun is a feature —
   // it restores locally modified/deleted files), and whether npx served a cached build is NOT
   // observable here (no network), so the note never claims it; the @latest hint is conditional.

package/capability.json

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

package/migrations/README.md

@@ -13,7 +13,7 @@ releases add files/templates, which `upgrade` reconciles without a migration.
    `.memory-version` verbatim — see that migration.
 2. Select every migration whose `<version>` is **strictly newer** than the stamp.
 3. Apply them in **ascending semver order**.
-4. Re-stamp `docs/ai/.memory-version` to the deployment-lineage head (`1.3.0` today — the shared
+4. Re-stamp `docs/ai/.memory-version` to the deployment-lineage head (`2.0.0` today — the shared
    lineage sequence, **not** this package's npm version). The legacy `.workflow-version`, if present,
    is never deleted.
 

package/migrations/legacy-stamp-takeover.md

@@ -13,13 +13,13 @@ any other migration.
 
 The deployment stamp moved from `.workflow-version` (owned by the kit) to `.memory-version`
 (owned by this substrate). They track the **same** shared deployment-lineage sequence — never
-their package versions. The current lineage head is **`1.3.0`** (`LINEAGE_HEAD`). This migration
+their package versions. The current lineage head is **`2.0.0`** (`LINEAGE_HEAD`). This migration
 adopts an existing legacy stamp into the new file **without** changing the lineage value and
 **without** deleting the legacy stamp (both may coexist; each tool migrates from its own stamp).
 
 ## State table (idempotent)
 
-Look at `docs/ai/` and act by row. `V` is the legacy stamp's value; `head` = `1.3.0`.
+Look at `docs/ai/` and act by row. `V` is the legacy stamp's value; `head` = `2.0.0`.
 
 | `docs/ai/` state | Action |
 |---|---|
@@ -42,7 +42,7 @@ Look at `docs/ai/` and act by row. `V` is the legacy stamp's value; `head` = `1.
    done
    ```
 2. **Validate** each value that exists: it must be `MAJOR.MINOR.PATCH`, non-empty, and **not** greater
-   than `1.3.0`. If any present stamp is empty, unparseable, or in the future → **STOP and report**;
+   than `2.0.0`. If any present stamp is empty, unparseable, or in the future → **STOP and report**;
    do nothing else.
 3. **Apply** the matching row above. For the "only `.workflow-version=V`" row, copy verbatim and
    write **atomically** — create an exclusive randomized temp in `docs/ai/` (so a planted temp-name

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "1.12.0",
+  "version": "2.0.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",