@sabaiway/agent-workflow-memory 4.5.1 → 4.5.3

package/CHANGELOG.md

@@ -4,6 +4,36 @@ 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.5.3 — the bundled `agent_rules.md` template carries the finding-scope lens bullet (AD-110)
+
+The engine's agent-rules lens gained one bullet in **3.1.0** — the finding-scope rule, scoped to
+plan-execution — and this package's bundled `agent_rules.md` template carries its render. Nothing
+else in the substrate moves: no new template, no schema change, no migration.
+
+**Why this is its own release rather than a free ride.** The lens canon lives in the engine and a
+wording change is an engine-only release by contract, because a deployed region converges from the
+engine read on the next kit touch. That is true of a DEPLOYED project and says nothing about this
+PACKAGE: the publish workflow refuses to no-op a package whose subtree changed without a version
+bump, and it is right to — the existing 4.5.2 tag still points at exactly the bytes on npm, and it is
+the CHANGED subtree that no longer matches them, so a no-op would leave that change unversioned and
+unpublished.
+
+## 4.5.2 — the boundary sentence names the plan SHAPE, not the retired vocabulary (AD-104; ships with engine 3.0.0 / kit 6.0.0)
+
+**Wording only — no contract, no script, no gate changes.** This substrate records only *where* the
+workflow methodology lives, never the methodology itself, and the words it used to point with were
+the ones engine **3.0.0** retired. Nothing here refuses anything it used to accept, and nothing new
+is offered, so this stays a PATCH while its two siblings take a MAJOR each.
+
+- **`SKILL.md`** — the "knows nobody else in the family" boundary paragraph and the ownership table
+  say **plan shape** (goal and boundary, module ledger, verification) and **activity procedures**
+  where they used to say "plan → execute → review vocabulary" and "Plan→Phase→Step". The slots, the
+  owners and the composition-root contract are untouched.
+- **`references/templates/agent_rules.md`** — the rendered lens fragment picks up the same
+  re-render the kit template gets: the two per-Step clauses are per-row, and §5's plan-file summary
+  says "shape, lifecycle" instead of "vocabulary, lifecycle". The session-continuity sentence went
+  with the heuristic the canon dropped.
+
 ## 4.5.1 — the deployed scripts decide direct-run by real path, so a symlinked entry point stops silently doing nothing (AD-102; ships with kit 5.11.1)
 
 **A script invoked through a symlink ran nothing and exited 0.** The guard that decides "was I run

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: '4.5.1'
+  version: '4.5.3'
 ---
 
 # agent-workflow-memory
@@ -19,8 +19,8 @@ protocols, frontmatter caps, one-file-per-ADR archive, index-freshness gate. Enf
 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), **the
+the family. In particular it does **not** own the **workflow methodology** (the plan shape,
+lifecycle, `docs/plans/queue.md`, mandatory Cleanup, the activity procedures), **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
@@ -46,7 +46,7 @@ pointers are the **three empty slots** the composition root fills — never auth
 | `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 |
+| Plan shape (goal and boundary, module ledger, verification), 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) |

package/capability.json

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

package/package.json

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

@@ -78,12 +78,13 @@ Apply this as part of §2 before any user-facing summary:
 ### 2.6. Planning, review & process-fidelity invariants
 Apply these when authoring a plan, reviewing, folding a finding, or editing code — the layer read **before any code change**. (Full canon: the project's planning / workflow-methodology + orchestration canon. This section is rendered from that canon and refreshed on upgrade; a custom edit is preserved verbatim, but flagged.)
 - **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
+- **Finding scope (plan-execution) — name the invariant BEFORE the edit.** During EXECUTION only — a plan under authoring has no shipped behaviour to call a live defect in, so plan-review carries none of this. Every finding names the invariant its fix would enforce, and where that invariant already lives decides the disposition: already an acceptance criterion of the phase → **fold here**; it would have to be ADDED → ship the **narrow fix** for the found site (red first, then green) and queue ONLY the generalization — a deferral row carries the invariant, the origin `file:line`, the narrow fix, its proof and a residual exposure declared NOT live; no correct narrow fix → **blocking**: the phase does not close, and it is **never queued**. Two bars declared before each round: a finding counts only if it changes a **WRITE/REMOVE decision** or is a false statement in shipped text; a repeat finding in one subarea **routes to SUBTRACTION**, not a fourth patch.
 - **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
-- **No code-mechanics in the plan.** A Step still carries its exact paths + commands (the plan-structure / self-review canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.
+- **No code-mechanics in the plan.** A ledger row carries its path and anchor, and Verification carries the exact commands (the plan-shape canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.
 - **Test-as-spec.** Fold a code-touching finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker; a paragraph cannot self-check.
 - **Characterize-first.** Before editing UNCOVERED code, pin its current behavior in a green test, then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible; prefer SUBTRACTIVE folds.
 - **Fold minimally — prose has no checker.** An ephemeral, gitignored plan is prose with no executable checker; fold **minimally, in ONE place** and run a **self-consistency** read across the plan before every re-review — a fold that drifts several prose spots is what turns a 2-round review into churn.
-- **Heavy review at the diff.** Plan-review settles architecture only (≤2 rounds, stop at the pre-existing→fold-induced crossover); the exhaustive per-Step review runs against real compiling code + the full suite, where a regression fails a gate immediately. **Backend divergence** (one backend grounded-ships while another keeps revising mechanics) IS that crossover — resolve at altitude, don't exhaust the strictest backend; route an all-mechanics/CI or prose-only artifact to a **thin plan + diff-review**.
+- **Heavy review at the diff.** Plan-review settles architecture only (≤2 rounds, stop at the pre-existing→fold-induced crossover); the exhaustive per-row review runs against real compiling code + the full suite, where a regression fails a gate immediately. **Backend divergence** (one backend grounded-ships while another keeps revising mechanics) IS that crossover — resolve at altitude, don't exhaust the strictest backend; route an all-mechanics/CI or prose-only artifact to a **thin plan + diff-review**.
 - **Convergence bar.** A review loop is CLEAN only when one round returns **0 blockers + 0 majors** from EVERY backend the recipe names (nits + a ship verdict is the stop). Folding ≠ convergence — re-review after folding.
 - **Per-round emission.** Every review round emits **{round N · finding-origin tally · per-backend verdict}** so the crossover is a computed, visible signal, not a remembered rule.
 - **Recipe fidelity.** Council runs every backend the recipe names, **every round**; silently dropping a ready backend for quota/convenience is a forbidden downgrade — an unavailable backend is a LOUD, stated degrade, never a quiet drop.
@@ -98,8 +99,7 @@ Split a complex task across sessions for **focus and review hygiene**, not becau
 
 - **Split (separate sessions)** when the *change* is large enough to deserve an isolated review checkpoint: creates/deletes a source or test file, touches several files, alters a dependency / core config / data model / routes, or needs new E2E tests. These are review-hygiene triggers, independent of context size.
 - **Run inline** for small, self-contained work: a few files, no new files, no dependency/schema/route change, light discussion (typos, tweaks, single-line fixes, test additions).
-- **Context size is a soft, secondary signal** — split only when the working context is genuinely large *relative to the window* or you notice degraded recall, never at a fixed token count. Prefer the planning skill's **session-continuity heuristic**: keep going in-session when the accumulated context IS the execution payload (targeted-deep reads of the exact files you'll edit); split when it was broad fan-out noise.
-
+- **Context size is a soft, secondary signal** — split only when the working context is genuinely large *relative to the window* or you notice degraded recall, never at a fixed token count.
 ---
 
 ## 4. User Interaction
@@ -111,4 +111,4 @@ Split a complex task across sessions for **focus and review hygiene**, not becau
 
 ## 5. Planning Workflow
 
-Plan-file rules — vocabulary, lifecycle (`docs/plans/<slug>.md`, gitignored, never committed), the mandatory final **Phase: Cleanup**, the `docs/plans/queue.md` series-index, "all work in plans", the plan-then-execute split — are **workflow methodology**, owned by the project's planning skill, not by this memory substrate. The methodology block in `AGENTS.md` (between the `workflow:methodology` markers) points to it; the planning skill is the single source of truth and overrides the generic `writing-plans` skill. This substrate records only *where* the methodology lives, never the methodology itself.
+Plan-file rules — shape, lifecycle (`docs/plans/<slug>.md`, gitignored, never committed), the mandatory final **Phase: Cleanup**, the `docs/plans/queue.md` series-index, "all work in plans" — are **workflow methodology**, owned by the project's planning skill, not by this memory substrate. The methodology block in `AGENTS.md` (between the `workflow:methodology` markers) points to it; the planning skill is the single source of truth and overrides the generic `writing-plans` skill. This substrate records only *where* the methodology lives, never the methodology itself.