@sabaiway/agent-workflow-memory 8.0.1 → 8.1.0

package/CHANGELOG.md

@@ -2,7 +2,25 @@
 
 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 `3.0.0`).
+`docs/ai/.memory-version` (which tracks the shared `agent-workflow` lineage, head `4.0.0`).
+
+## 8.1.0 — the deployment-lineage head moves to 4.0.0 (AD-157)
+
+`scripts/stamp-takeover.mjs`: `LINEAGE_HEAD` is `4.0.0`, so a memory bootstrap stamps `docs/ai/.memory-version` with
+`4.0.0`, and a stamp of `4.0.0` is no longer refused as newer than the head. The kit's step `4.0.0` offers the epic
+and task settings and the epic store (kit 14.11.0); this package gains no `4.0.0` migration note, since its own
+re-stamp needs none. `SKILL.md`, `README.md`, `migrations/README.md` and `migrations/legacy-stamp-takeover.md` name
+the new head. MINOR: the stamp a bootstrap writes changes.
+
+## 8.0.2 — the rules template gains the Story sessions section (AD-152)
+
+`references/templates/agent_rules.md`: the new section `### 2.7. Story sessions` is added after §2.6 and before the
+`---` that closes §2, byte-identical to the kit's copy, which is the section's one source. It says a story runs as
+five sessions — spec, plan, tests, code, and diff review + release + record — each ending at its own review
+checkpoint, and that a split is one session. A deployment whose rules file lacks the section is offered the insert
+by the kit's upgrade (`tools/rules-insert.mjs`); a file that already carries a Story sessions heading keeps its own
+wording. No script changed.
+
 
 ## 8.0.1 — the orchestration seed's note names six activities (AD-147)
 

package/README.md

@@ -45,7 +45,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 `3.0.0` today), **not** this package's
+shared `agent-workflow` deployment lineage (head `4.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: '8.0.1'
+  version: '8.1.0'
 ---
 
 # agent-workflow-memory
@@ -146,7 +146,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 **`3.0.0`** (the
+    `docs/ai/.memory-version` (one semver line). The lineage head is **`4.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
@@ -185,7 +185,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`, `3.0.0`). **Greater than the head, or
+   stamp to the **deployment-lineage head** (`LINEAGE_HEAD`, `4.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
@@ -216,7 +216,7 @@ 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 (`3.0.0`) deployment still gains the
+   content, seed-or-preserve only.) This is why an equal-head (`4.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-store enforcement pair** — copy
@@ -330,7 +330,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** (`3.0.0`, the shared `agent-workflow` lineage) — a **separate axis** from this package's npm
+  head** (`4.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.
 - **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

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-memory",
   "kind": "memory-substrate",
-  "version": "8.0.1",
+  "version": "8.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 (`3.0.0` today — the shared
+4. Re-stamp `docs/ai/.memory-version` to the deployment-lineage head (`4.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 **`3.0.0`** (`LINEAGE_HEAD`). This migration
+their package versions. The current lineage head is **`4.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` = `3.0.0`.
+Look at `docs/ai/` and act by row. `V` is the legacy stamp's value; `head` = `4.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` = `3.
    done
    ```
 2. **Validate** each value that exists: it must be `MAJOR.MINOR.PATCH`, non-empty, and **not** greater
-   than `3.0.0`. If any present stamp is empty, unparseable, or in the future → **STOP and report**;
+   than `4.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": "8.0.1",
+  "version": "8.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",

package/references/templates/agent_rules.md

@@ -94,6 +94,9 @@ Apply these when authoring a plan, reviewing, folding a finding, or editing code
 - **ExitPlanMode ≠ execute.** A harness "approved — start coding" prompt authorizes the PLAN only; this methodology overrides it. Continue into execution only as a DELIBERATE transition after the plan + cold-start prompt exist, never an implicit slide.
 - **Cost lanes.** Route every step to the **cheapest adequate executor** — L0 deterministic script (the batched gate matrix over `gates.json`, the rotation `--check`s) · L1 cheap subagent (extraction/drafting only; the orchestrator verifies) · L2 subscription bridge · L3 frontier judgment. A step with **no named guardrail does not move down** a lane, and the **red lines never move down** (council review models · real code · ADR/handover/changelog-entry wording · persuasive copy · go/no-go · the approval asks). Own-error repair: salvage recorded state first (L0/L1, batched), never frontier re-derivation. **Prompt economy:** read-only fan-out (research/sweeps/extraction) runs ONLY on restricted-tool vehicles — a full-tool subagent for read-only work is a forbidden lane downgrade (invisible prompt-flood + blast radius), and a subagent is never told to shell out for facts obtainable read-only; the orchestrator's own shell form is ONE plain pipeline per call (a `;`/`&&` chain or env-prefixed invocation never matches a prefix allow rule); a fan-out launcher that gates per call yields to the agent-spawn lane — capability-gated: without restricted-tool vehicles (generic full-tool spawning does not count), read-only research stays in the orchestrator's own context, never a vehicle mandate a host cannot satisfy. Judgment, code, synthesis stay at the frontier lane (a task that genuinely runs/writes keeps a full-tool subagent); honest limit: no deterministic gate classifies a dispatch — canon at the point of use + placed vehicles + the retro loop. **Writer economy:** a stage's repeated WRITER commands batch — evidence declarations ride consecutive plain invocations of ONE allow-listed tool, other stage writers combine via one launcher per stage; never an unbatched writer scatter (each gated write is its own prompt).
 
+### 2.7. Story sessions
+A story — one row of an epic's ledger, carried by one plan — runs as five sessions, each ending at its own review checkpoint: **spec** (the contract under `docs/ai/specs/`, drafted and reviewed on the `plan-authoring` recipe), **plan** (the ledger, same recipe), **tests** (one task per ledger row, red first), **code** (one task per row, to green), and **diff review, release and record** (the review of the staged tree on the `plan-execution` recipe, the release where the story ships one, then the changelog and handover entries and the plan's Phase: Cleanup). Tests and code never share a session, and a spec and its plan never share one either. A storyless plan runs the same five. **Exception — a split:** moving code and its existing cases into modules, with no new logic and no new case, is one session: a short spec (the Module list), the split, the diff review, the release, Cleanup.
+
 ---
 
 ## 3. Token & Session Optimization

package/scripts/stamp-takeover.mjs

@@ -6,7 +6,7 @@
 // The deployment lineage is a SINGLE shared sequence; its current head is LINEAGE_HEAD.
 // Both `.memory-version` and the kit-fallback `.workflow-version` track THAT sequence —
 // never their package versions. So this substrate's package may be 1.0.0 while the stamp
-// it writes is the lineage head (3.0.0 today).
+// it writes is the lineage head (4.0.0 today).
 //
 // `decideTakeover` is a PURE function (stamp state in → action out) so the state machine is
 // unit-testable per row. `applyTakeover` is the thin fs wrapper; stamp writes are ATOMIC
@@ -23,7 +23,7 @@ import { fileURLToPath } from 'node:url';
 
 // The shared agent-workflow deployment-lineage head. Bumped only when a project-migration
 // changes the deployed docs/ai structure — NOT on a packaging-only release.
-export const LINEAGE_HEAD = '3.0.0';
+export const LINEAGE_HEAD = '4.0.0';
 
 const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)$/;