@sabaiway/agent-workflow-memory 1.12.0 → 2.1.0

package/CHANGELOG.md

@@ -2,7 +2,71 @@
 
 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.1.0 — Autonomy template seed (AD-044 Plan 4)
+
+A **feature** release (ships with kit 1.45.0 / engine 1.15.0; the deployment lineage head stays
+`2.0.0` — the seed is ensure-if-missing, stamp-independent). `references/templates/autonomy.json`
+— the sparse, defaults-equivalent autonomy-policy seed (`_README` only): resolving it equals
+resolving no file at all, TEST-PINNED, so the seed can never drift from the computed defaults
+(commit/push/publish `ask`; network/credentials/fs-outside-repo `deny`; absent activities floor at
+`prompt`); it is STRUCTURALLY a seed (meta keys only) — an explicit policy declaring the same
+values reads as a real declaration on every kit surface. Lifecycle follows gates.json: bootstrap
+seeds it, upgrade ensures-if-missing (byte-preserving), hand-editable; the kit mirrors it via the
+template manifest. Tarball sentinel 43→44. Deliberately NOT a delegated-bootstrap required asset
+(the AD-044 Plan-3 no-gate decision holds).
+
+## 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 →
@@ -33,18 +33,19 @@ Open your agent inside a project and run the skill:
 - **`/agent-workflow-memory`** — bootstrap a new or empty project. Asks the three setup
   questions (visibility, conversational language, agent attribution), then writes `docs/ai/`,
   `AGENTS.md`, the enforcement scripts + pre-commit hook, and stamps
-  `docs/ai/.memory-version`. The two pointer slots in `AGENTS.md` (the **methodology** and
-  **orchestration** pointers, filled later by the family composition root) are left **empty**.
+  `docs/ai/.memory-version`. The three pointer slots in `AGENTS.md` (the **methodology**,
+  **orchestration** and **autonomy** pointers, filled later by the family composition root) are
+  left **empty**.
 - **`/agent-workflow-memory upgrade`** — migrate an existing deployment to the skill's current
   version. Reads `docs/ai/.memory-version`, runs only newer migrations in semver order, and
-  **preserves** anything already in either pointer slot (extract-and-reinsert — it never
+  **preserves** anything already in every pointer slot (extract-and-reinsert — it never
   regenerates `AGENTS.md` wholesale).
 
 ## Stamps & lineage
 
 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.1.0'
 ---
 
 # agent-workflow-memory
@@ -14,18 +14,19 @@ 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).
 
 This skill is the **memory layer** of the `agent-workflow` family. It **knows nobody else** in
 the family. In particular it does **not** own the **workflow methodology** (plan → execute →
-review vocabulary, lifecycle, `docs/plans/queue.md`, mandatory Cleanup, plan-then-execute) **or the
-orchestration recipes** — those are injected into **two delimited pointer slots** in `AGENTS.md`
-(`workflow:methodology` + `workflow:orchestration`) by the family **composition root**, never by this
+review vocabulary, lifecycle, `docs/plans/queue.md`, mandatory Cleanup, plan-then-execute), **the
+orchestration recipes, or the autonomy-policy contract** — those are injected into **three delimited
+pointer slots** in `AGENTS.md` (`workflow:methodology` + `workflow:orchestration` +
+`workflow:autonomy`) by the family **composition root**, never by this
 skill. (This substrate does not name or depend on any specific sibling — it only honours the slot
-contract.) This skill only ever ships **both** slots **empty** and **preserves** whatever is already
-in them on upgrade.
+contract.) This skill only ever ships **all three** slots **empty** and **preserves** whatever is
+already in them on upgrade.
 
 The substrate **artifacts** (this skill, the templates, the deployed `docs/ai/` files) stay in
 their **source language** — for cross-agent and cross-team portability. That is separate from the
@@ -36,20 +37,22 @@ contents).
 
 ## Ownership table
 
-What this substrate owns vs what it only points at. The methodology + orchestration pointers are the
-**two empty slots** the composition root fills — never author that text here.
+What this substrate owns vs what it only points at. The methodology + orchestration + autonomy
+pointers are the **three empty slots** the composition root fills — never author that text here.
 
 | 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 |
 | Orchestration recipes (Solo / Reviewed / Council / Delegated) | **methodology engine** (not this skill) | the empty `workflow:orchestration` slot — filled by the composition root |
+| Autonomy-policy read contract (`docs/ai/autonomy.json`) | **methodology engine** (not this skill) | the empty `workflow:autonomy` slot — filled by the composition root |
 | Per-project recipe **CONFIG** (which recipe each activity/slot uses) | **memory** seeds an *editable default* | `docs/ai/orchestration.json` (agent-writable via the composition root's `set-recipe` writer, or hand-edited; the recipe **canon** + the slot **vocabulary** live in the engine / composition root, never here) |
 | Per-project **gate declaration** (which verification commands must be green) | **memory** seeds an *editable default* | `docs/ai/gates.json` (hand-editable; an empty list as shipped — the project declares its own commands; the **runner** lives in the composition root, never here) |
 | Per-project **verification profile** (optional; the fold-completeness language-independence contract) | **memory** seeds an *editable default* | `docs/ai/verification-profile.json` (hand-editable; the seeded default reproduces the composition root's default V8 + node:test behaviour — delete it for exactly that; declares coverage source / single-test format / optional SARIF path; the **runner** lives in the composition root, never here) |
+| Per-project **autonomy policy** (red-lines + per-activity autonomy level) | **memory** seeds an *editable default* | `docs/ai/autonomy.json` (hand-editable, or agent-writable via the composition root's `set-autonomy` writer; the seed is SPARSE — the onboarding note only, defaults-equivalent, so deploying it never changes behavior; the policy **canon** + the render live in the engine / composition root, never here) |
 
 ---
 
@@ -97,17 +100,22 @@ bootstrapping over a live system, but the user makes the final call.
 5. **Entry-point doc.** If `AGENTS.md` / `CLAUDE.md` already exist (recon), do **not**
    overwrite — show the user and ask whether to merge or replace. Otherwise create `AGENTS.md`
    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.
+   (`ln -s AGENTS.md CLAUDE.md`). **Leave ALL THREE pointer slots (`workflow:methodology` +
+   `workflow:orchestration` + `workflow:autonomy`) exactly as shipped — empty.** Filling them is the
+   composition root's job.
+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 four 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 —
+   `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) — and `docs/ai/autonomy.json` — the per-project
+   autonomy policy, seeded SPARSE (the onboarding note only, defaults-equivalent — behavior changes
+   only when the user declares levels). 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 +128,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
@@ -134,7 +142,7 @@ bootstrapping over a live system, but the user makes the final call.
 > upgrade**, do the write steps (bootstrap 1–10 / upgrade 1–7: write `docs/ai/` + `AGENTS.md` +
 > `.memory-version`, **including seeding / stamp-independently ensuring `docs/ai/orchestration.json`**)
 > but **do NOT** run **any** commit gate and **do NOT** ask to commit — the
-> composition root owns the **single** commit gate, raised after it injects the two pointer slots.
+> composition root owns the **single** commit gate, raised after it injects the three pointer slots.
 > The three setup answers and the target dir are passed in by the composition root; you perform no
 > commit and no slot injection. **Standalone** invocation keeps its own commit gate (bootstrap step
 > 11 / upgrade step 7).
@@ -146,7 +154,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 +167,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
@@ -175,8 +184,9 @@ Fill strategy:
    **untracked AND not ignored** → **AMBIGUOUS** → **ASK** the user before writing. This visibility check
    runs on **every** in-range upgrade, even at head — it is not gated by the stamp delta, but it is gated
    **behind** the never-downgrade STOP above. **Also stamp-independent (same gate, before the equal-head
-   short-circuit): ensure the THREE seeded `.json` configs** — for `docs/ai/orchestration.json`,
-   `docs/ai/gates.json`, AND `docs/ai/verification-profile.json`, **create the file from its
+   short-circuit): ensure the FOUR seeded `.json` configs** — for `docs/ai/orchestration.json`,
+   `docs/ai/gates.json`, `docs/ai/verification-profile.json`, AND `docs/ai/autonomy.json`,
+   **create the file from its
    `${CLAUDE_SKILL_DIR}/references/templates/` template if missing**, **preserve it byte-for-byte
    if it already exists** (a user may have edited it; never clobber it). The shipped
    `orchestration.json` template's `_README` already frames that config as agent-writable (set it
@@ -184,17 +194,29 @@ Fill strategy:
    declaration (what to verify — consumed by the composition root's gate runner);
    `verification-profile.json` is the OPTIONAL fold-completeness verification profile — the seeded
    default reproduces the composition root's default V8 + node:test behaviour, so a project deletes
-   it to fall back to exactly that, or edits it for another language/runner. (Refreshing the
+   it to fall back to exactly that, or edits it for another language/runner; `autonomy.json` is the
+   per-project autonomy policy, seeded SPARSE (the onboarding note only, defaults-equivalent —
+   agent-writable via the composition root's `set-autonomy` writer, hand-editing supported). (Refreshing the
    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
@@ -219,12 +241,13 @@ Fill strategy:
    (`migrations/1.1.0-communication-language.md`); pre-1.2.0 with no *Attribution* block, ask +
    insert defaulting to `off` (`migrations/1.2.0-agent-attribution.md`). (An answer already
    collected by the step-4 batched prompt is carried in — never re-asked here.)
-6. **Preserve BOTH pointer slots.** If `AGENTS.md` has the `workflow:methodology` and/or
-   `workflow:orchestration` markers, **never regenerate the file wholesale** — extract any bytes
-   between each pair and reinsert them unchanged. If a pair is absent (a legacy `AGENTS.md`),
-   gracefully **no-op** on that slot (adding a slot to already-deployed files is the composition
-   root's reconcile, not this substrate's job). On any malformed marker state (single, reversed,
-   nested, or duplicate pair), **no-op with an error** — never edit.
+6. **Preserve ALL pointer slots.** If `AGENTS.md` has the `workflow:methodology`,
+   `workflow:orchestration` and/or `workflow:autonomy` markers, **never regenerate the file
+   wholesale** — extract any bytes between each pair and reinsert them unchanged. If a pair is
+   absent (a legacy `AGENTS.md`), gracefully **no-op** on that slot (adding a slot to
+   already-deployed files is the composition root's reconcile, not this substrate's job). On any
+   malformed marker state (single, reversed, nested, or duplicate pair), **no-op with an error** —
+   never edit.
 7. **Re-stamp** `docs/ai/.memory-version` to the lineage head (atomic write — mechanics unchanged).
    Report changes **in plain human terms** (which parts of the deployment are now different);
    **omit the raw structure number**, and do not recite the two-axes note here (it belongs to
@@ -264,11 +287,11 @@ 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
-  writer.
+- **All three pointer slots ship empty and stay the user's.** Never author methodology,
+  orchestration or autonomy text into them; on upgrade, preserve their content byte-for-byte. The
+  composition root is their only writer.
 - **The `Co-Authored-By` trailer is added by the harness, not by prose.** When attribution is
   `off` + Claude Code, also set `"includeCoAuthoredBy": false` in `.claude/settings.json`.
 - **Hidden mode is project-local, never machine-global.** Memory's hide writes to the repo's
@@ -294,11 +317,12 @@ The three setup choices each have a full contract in
 ## References
 
 - [`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.
+- [`references/templates/`](references/templates/) — stack-agnostic `AGENTS.md` (with the three empty
+  pointer slots — methodology + orchestration + autonomy), `agent_rules.md`, the seeded user-editable
+  `orchestration.json` + `autonomy.json` configs, 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.1.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.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",