@sabaiway/agent-workflow-memory 1.2.2 → 1.4.0

package/CHANGELOG.md

@@ -4,6 +4,38 @@ 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 `1.3.0`).
 
+## 1.4.0 — §2.6 right-altitude & code-grounded lens (memory)
+
+A **feature** release. The `agent_rules.md` substrate gains a **§2.6 Right-altitude & code-grounded
+(planning + review)** self-review subsection — fold by code (read + cite the `file:line`), pin
+intent/invariants/acceptance, and the convergence heuristic. Wording is **path-neutral** (the substrate
+"knows nobody": it points at "the project's planning methodology / workflow-methodology canon", never a
+sibling/engine path). The deployment-lineage head stays **`1.3.0`** (no `docs/ai` structural change, no
+migration file); the npm package version is a separate axis.
+
+- **Seed-or-preserve only (unchanged contract).** A NEW deployment gets the §2.6 lens from the seed;
+  refreshing an already-deployed file is the composition root's job.
+- **Template parity preserved** — the §2.6 block body stays byte-identical to the kit fallback template
+  (only the heading number differs), pinned by the kit's cross-package `lens-mirror.test.mjs`.
+
+## 1.3.0 — Agent-writable config note; §2.5 Communication (memory)
+
+A **feature** release. The seeded `docs/ai/orchestration.json` note now frames the config as
+agent-writable (via the `set-recipe` writer) **and** still hand-editable — the old "never written for
+you" wording is gone. The `agent_rules.md` substrate gains a **§2.5 Communication** self-review item
+(deliver the artifact inline; lead with the result; large-artifact carve-out). The deployment-lineage
+head stays **`1.3.0`** (no `docs/ai` structural change, no migration file); the npm package version is a
+separate axis.
+
+- **Seed-or-preserve only (unchanged contract).** This substrate still only **seeds** the config from its
+  template when missing and **preserves** an existing one byte-for-byte — a NEW deployment gets the updated
+  note from the seed. Refreshing the note *in place* on an already-deployed file is the **composition
+  root's** job (memory stays standalone and owns no cross-package refresh helper).
+- **Template parity preserved** — the seeded `orchestration.json` stays byte-identical to the composition
+  root's fallback copy; the new note is identical across both.
+- **Knows-nobody invariant intact** — the note + SKILL.md refer to the writer generically, never naming a
+  specific sibling skill.
+
 ## 1.2.2 — Strip the package's own tests from the npm tarball (memory)
 
 Packaging only — no API/behaviour change; removed the package's own colocated tests from 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: '1.2.2'
+  version: '1.4.0'
 ---
 
 # agent-workflow-memory
@@ -47,7 +47,7 @@ What this substrate owns vs what it only points at. The methodology + orchestrat
 | 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 |
-| Per-project recipe **CONFIG** (which recipe each activity/slot uses) | **memory** seeds an *editable default* | `docs/ai/orchestration.json` (hand-edited; the recipe **canon** + the slot **vocabulary** live in the engine / composition root, never here) |
+| 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) |
 
 ---
 
@@ -113,7 +113,8 @@ bootstrapping over a live system, but the user makes the final call.
 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
     `LINEAGE_HEAD` constant in `scripts/stamp-takeover.mjs`) — the shared `agent-workflow`
-    lineage, **not** this package's npm version (`1.2.0`). Use the atomic writer in
+    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
     `scripts/stamp-takeover.mjs` (write-temp + rename).
 11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on filled-vs-TODO, then **ask before
     committing** — never auto-commit. **Exception — delegated mode (below): skip this gate.**
@@ -163,11 +164,14 @@ Fill strategy:
    **behind** the never-downgrade STOP above. **Also stamp-independent (same gate, before the equal-head
    short-circuit): ensure `docs/ai/orchestration.json`** — **create it from
    `${CLAUDE_SKILL_DIR}/references/templates/orchestration.json` if missing**, **preserve it byte-for-byte
-   if it already exists** (a user may have edited it; never clobber it). This is why an equal-head (`1.3.0`)
-   deployment still gains the config seed **without a lineage-head bump or a migration file** (the
-   stamp-independent-reconcile precedent — like the pointer slots + the hidden-mode footprint). **Then**,
-   if the stamp **equals** the head → report "up to date" (plus any footprint move / config seed just
-   made) and stop.
+   if it already exists** (a user may have edited it; never clobber it). The shipped template's `_README`
+   already frames the config as agent-writable (set it with the `set-recipe` writer) and still
+   hand-editable. (Refreshing that 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.) This is why an equal-head (`1.3.0`) deployment still gains the config seed **without a
+   lineage-head bump or a migration file** (the stamp-independent-reconcile precedent — like the pointer
+   slots + the hidden-mode footprint). **Then**, if the stamp **equals** the head → report "up to date"
+   (plus any footprint move / config seed just made) and stop.
 3. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` context (entries newer than the stamp).
 4. Apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those
    newer than the stamp. Migrations are **idempotent**.
@@ -192,8 +196,9 @@ Fill strategy:
 
 - **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 `1.3.0` (the shared
-  `agent-workflow` lineage), not the npm `1.2.0`. They are independent axes.
+- **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
+  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.

package/capability.json

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

package/package.json

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

@@ -63,6 +63,18 @@ Before proposing changes or committing, review against:
 ### 2.4. Quality Gates
 - Always run type-checker, linter, and all tests before committing.
 
+### 2.5. Communication (user-facing messages)
+Apply this as part of §2 before any user-facing summary:
+- **Deliver the artifact IN the message** — paste the prompt / diff / version / command inline; never "see §X / open the file / run it and you'll see" as a *substitute* for showing what was asked.
+- **Lead with the result**, then the details; show exactly what was asked — no deflection, no "almost done" when the ask was the finished thing.
+- **No condescension, no filler.** Own a miss plainly and fix it in the same message.
+- **Large artifact (≈>100 lines):** deliver a real summary or the key excerpt inline **and** link the file — never flood the reader with a 2000-line paste, never hide the answer behind a bare pointer.
+
+### 2.6. Right-altitude & code-grounded (planning + review)
+- **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.
+- **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
+- **Convergence heuristic.** When a review round keeps finding mechanism issues on a stable architecture, stop refining prose — raise the altitude or hand it to Execute. (Full canon: the project's planning methodology / workflow-methodology canon.)
+
 ---
 
 ## 3. Token & Session Optimization

package/references/templates/orchestration.json

@@ -1,5 +1,10 @@
 {
-  "_README": "Per-project orchestration config: the recipe used at each step (slot) of each named activity. Hand-edit this file — it is never written for you. Each activity is configured independently (e.g. plan-authoring, plan-execution), and so is each slot within it. A slot's value is a recipe: a 'review' slot accepts solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize); an 'execute' slot accepts solo | delegated (you implement / a backend runs a bounded sub-task). The default below is 'solo' everywhere — no execution backend required. Raise a slot to reviewed or council for a second opinion, or to delegated to hand off execution; those need an execution backend set up first. Remove a slot's line to fall back to the computed default (reviewed when a review backend is ready, otherwise solo). Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for your environment, and pass a per-run override to change one slot just once. Strict JSON — no comments.",
-  "plan-authoring": { "review": "solo" },
-  "plan-execution": { "execute": "solo", "review": "solo" }
+  "_README": "Per-project orchestration config: the recipe used at each step (slot) of each named activity. Easiest: tell the agent in plain language and run the `set-recipe` writer — it interprets your intent, previews the change, and writes valid JSON for you. You can still hand-edit this file directly whenever you prefer; that option never goes away. Each activity is configured independently (e.g. plan-authoring, plan-execution), and so is each slot within it. A slot's value is a recipe: a 'review' slot accepts solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize); an 'execute' slot accepts solo | delegated (you implement / a backend runs a bounded sub-task). The default below is 'solo' everywhere — no execution backend required. Raise a slot to reviewed or council for a second opinion, or to delegated to hand off execution; those need an execution backend set up first. Remove a slot's line (or run `set-recipe --unset <activity>.<slot>`) to fall back to the computed default (reviewed when a review backend is ready, otherwise solo). Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for your environment. Strict JSON — no comments.",
+  "plan-authoring": {
+    "review": "solo"
+  },
+  "plan-execution": {
+    "execute": "solo",
+    "review": "solo"
+  }
 }