@sabaiway/agent-workflow-engine 3.3.0 → 4.1.0

package/CHANGELOG.md

@@ -4,6 +4,57 @@ All notable changes to the methodology engine. Versions are this **package's** n
 they are distinct from the **deployment-lineage** stamp written into a project's `docs/ai/`
 (which tracks the shared `agent-workflow` lineage, head `3.0.0`).
 
+## 4.1.0 — the queue is a named surface with a checker, not a prose promise
+
+`references/planning.md` gains **`## The queue`**: `docs/plans/queue.md` NAMES work and never holds
+the analysis of it — a row is one plain sentence saying what the work is and for whom, then its id,
+then a short body, while measurements and `file:line` citations belong to an ADR or the record the
+row points at. A row that goes terminal is DELETED in the same change that mints its closing
+artifact, and where the queue is gitignored the deleted text is first written to a purge archive,
+because there git history is no tombstone. Frozen work with a stated resume condition is not
+terminal and stays, in its own bucket; order inside a bucket IS priority.
+
+The canon names its own rung and the command that runs it, because a prose promise to trim later was
+measured failing — 62 dead rows had accumulated by the time anybody counted.
+
+`references/procedures.md` points at the new section by named anchor and stays the terse pointer it
+is meant to be (its own test asserts it stays smaller than the canon it binds to).
+
+## 4.0.0 — the scenario floor, and five answers the canon now states at its own points of use (AD-117)
+
+Slice 4 wrote the layer's first real specs and came back with six questions the canon had left for
+the next reader to rediscover. Five are answered here, IN `references/specs.md`, each at the point
+where it is needed — and four of the five answers are a refusal to add a mechanism.
+
+> ### ⚠ BREAKING — a spec written to the 3.3.0 canon can be invalid under this one
+>
+> `## Scenarios` gains a floor: at least one scenario line, with no empty-marker escape. A document
+> the 3.3.0 canon and its reader both accepted now refuses as `scenarios-empty`. Same class as
+> **3.0.0**, where deleting a vocabulary from the canon was already called MAJOR. The remedy is one
+> line per scenario — `- S<N> <name> :: unbound` while no test pins it.
+
+- **(1) No empty-marker escape on `## Scenarios`.** `*(empty)*` written there refuses as
+  `scenario-line`; `unbound` already covers a scenario no test pins yet. An empty exclusion list is a
+  claim, an empty scenario list is an absence. The refusal table gains the matching `scenarios-empty`
+  row, in the reader's own order.
+- **(2) A binding marker is an ORDINARY source line.** It counts toward the source-size practice like
+  any other line, and a pinning file already at its cap raises its recorded ratchet to host one. No
+  carve-out: the size judge counts bytes and must not learn spec vocabulary.
+- **(3) There is NO sidecar binding form.** Retroactive coverage of a PUBLISHED package rides a
+  release train, because the marker moves that package's subtree — a cost the family already pays
+  deliberately, against a second place a binding could live.
+- **(4) No `root` op verb.** The store root is the navigator, never an op target; it is judged as the
+  listing parent of its declared child. The canon says so where containment is defined.
+- **(5) The promoting event of a RETROACTIVE draft is PLAN APPROVAL.** `live` lands in the SAME slice
+  that authors the draft, once every scenario is bound — otherwise a slice whose whole deliverable IS
+  the specs has no later landing row, and the store's first contracts stay permanently provisional by
+  the canon's own wording.
+- `test/specs-canon.test.mjs` pins all five as prose assertions at their point of use, absorbs the
+  new rule in the rules-table deep-equal, and gains two refuse fixtures — the empty section and the
+  empty marker — each yielding exactly its one rule. The arm was red-proofed against the unchanged
+  canon.
+
+
 ## 3.3.0 — the feature-spec canon: `references/specs.md`, the `Spec-first` lens bullet, specs as plan rows (AD-112)
 
 - **`references/specs.md`** (NEW) — the canon of the feature-spec layer in the family's own

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-engine
 description: Canonical home of the agent-workflow planning methodology — the capped plan shape (goal and boundary, module ledger, verification), plan lifecycle, queue.md series index, mandatory Cleanup phase, the feature-spec canon (the durable per-feature contract layer with its frozen schema and Out-of-scope discipline), the bounded methodology slot fragment, the orchestration-recipe vocabulary (Solo / Reviewed / Council / Delegated), and the activity-procedures canon (plan-authoring / plan-execution, with typed recipe slots). A published, installable npm package (available:true) that *provides* the methodology text; it mutates nothing. The composition root (agent-workflow-kit) reads this canon LIVE from the installed engine and injects the bounded slots from it — one source of truth, no bundled mirror; `npx @sabaiway/agent-workflow-kit@latest init` installs the engine.
 disable-model-invocation: true
 metadata:
-  version: '3.3.0'
+  version: '4.1.0'
 ---
 
 # agent-workflow-engine

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-engine",
   "kind": "methodology-engine",
-  "version": "3.3.0",
+  "version": "4.1.0",
   "available": true,
   "provides": ["plan"],
   "roles": {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-engine",
-  "version": "3.3.0",
+  "version": "4.1.0",
   "description": "Canonical home of the agent-workflow planning methodology — the capped plan shape (goal and boundary, module ledger, verification), plan lifecycle, queue.md series index, and mandatory Cleanup phase, consumed by the kit (composition root). The methodology engine of the agent-workflow family.",
   "keywords": [
     "ai-agents",

package/references/planning.md

@@ -118,6 +118,20 @@ plan file, and plan paths inside committed docs, are forbidden.
 and the docs cap-validator is green. An aborted plan still runs Cleanup — partial outputs land in
 `known_issues.md`.
 
+## The queue
+
+`docs/plans/queue.md` NAMES work; it never holds the analysis of it. A row is one plain sentence
+saying what the work is and for whom, then its id, then a short body — measurements, `file:line`
+citations and fix direction belong to an ADR or the record the row points at. A row that goes
+terminal is DELETED in the same change that mints its closing artifact — and where the queue is
+gitignored, the deleted text is first written to a purge archive beside the history docs, because
+there git history is no tombstone. In a hidden deployment that archive is machine-local like the rest
+of the substrate: its guarantee is the working copy, not git. Frozen work with a stated resume
+condition is not terminal and stays, in its own bucket. Order inside a bucket IS priority.
+A prose promise to trim later has been measured failing: a checker over the file is the rung, and it
+is runnable — `node <kit>/tools/queue-audit-cli.mjs --check docs/plans/queue.md --section '<bucket
+heading>' --max-rows <n> --max-row-lines <n>`, declared as a project gate once the queue has migrated.
+
 ## The plan must read cold
 
 The executing session sees the plan file and the repository, never the authoring conversation.

package/references/procedures.md

@@ -38,7 +38,7 @@ Slots: review
    a `create` row and a revision of a governed contract a `modify` row, both written here so they
    exist AT review.
 3. **Self-review** — apply *What gets cut*; fold by code (read and cite the `file:line`); update
-   `queue.md` for a series.
+   `queue.md` for a series, to the shape *The queue* fixes.
 4. **review {recipe}** — Solo (self-review only) / Reviewed (one backend) / Council (both; you
    synthesize), as the resolved `review` recipe selects.
 5. **Fold + loop** — fold every finding and re-review; CLEAN is **0 blockers + 0 majors** from every

package/references/specs.md

@@ -46,6 +46,9 @@ against it.
   `^[a-z0-9]+(-[a-z0-9]+)*$`. Every path segment under the store is a slug.
 - **Scenario line** — `- S<N> <name> :: <repo-relative test path> :: spec:<slug>/S<N>` or
   `- S<N> <name> :: unbound`; N runs contiguously from 1; the marker equals the line's own id.
+- **`## Scenarios`** — at least one scenario line; `*(empty)*` is NOT an escape here (it refuses as
+  `scenario-line`), because an `unbound` line already covers a scenario no test pins yet. A contract
+  that pins nothing is the one shape the layer exists to refuse.
 - **`## Module`** — bullets of repo-relative paths: ONE `dir/` root OR a literal file list. `..`,
   an absolute path, a backslash, a glob, and a dir + file mix each REFUSE. A retired spec may carry
   `*(empty)*`.
@@ -99,6 +102,7 @@ refuse case per rule and an accept case per kind; a refuse fixture yields exactl
 | `scenario-number` | scenario ids not contiguous from 1 |
 | `scenario-marker` | a marker whose slug or id differs from its own line |
 | `scenario-path` | a binding's test path that is not a repo-relative file |
+| `scenarios-empty` | a `## Scenarios` section carrying no scenario line |
 | `out-of-scope` | no non-blank bullet and not exactly `*(empty)*` |
 | `module-line` | a `## Module` line that is not a `- <path>` bullet |
 | `module-empty` | no module path and not exactly `*(empty)*` (a retired spec may carry the marker instead of a path) |
@@ -129,12 +133,17 @@ refuse case per rule and an accept case per kind; a refuse fixture yields exactl
   scenario on a live spec is individually `unbound` until its test lands within the same plan — the
   spec's status never regresses for an extension. The binding is literal and language-agnostic: the
   marker `spec:<slug>/S<N>` must occur exactly once in the named file. The honest claim is an
-  advisory structural pin; runnability and greenness stay the test suite's own gate.
+  advisory structural pin; runnability and greenness stay the test suite's own gate. A marker is an
+  ORDINARY source line — it counts toward the source-size practice like any other, and a pinning file
+  already at its cap raises the recorded ratchet to host one. There is NO sidecar binding form:
+  retroactive coverage of a PUBLISHED package rides a release train, because the marker moves that
+  package's subtree.
 - **Containment** is lexical AND realpath on every path-bearing field (bindings, child links, module
   roots). The reader judges the lexical half; realpath and symlink escapes are the structural
   checker's duty (`spec-check`, a later slice), together with marker existence and uniqueness, link
   resolution and the global invariants (slug uniqueness, module-root overlap, tree acyclicity) that
-  only a full-tree sweep can prove.
+  only a full-tree sweep can prove. The store ROOT is never an op target and needs no `root` verb: it
+  is the navigator, judged as the listing parent of its declared child.
 
 ## Precedence — feature spec and page spec
 
@@ -176,8 +185,11 @@ that changes a contract triggers a spec revision.
 
 The onboarding path for an existing feature: read the code, author a `draft` spec from it (the
 contract it actually keeps, the scenarios its tests already pin, the Out of scope its boundaries
-imply), then human review promotes it to `live` through a plan. Used to dogfood the family's own
-subsystems; a legacy module binds through a declared file set, never a refactor ride-along.
+imply), then human review promotes it to `live` through a plan. The promoting event of a retroactive
+draft is PLAN APPROVAL — `live` lands in the SAME slice that authors the draft, once every scenario
+is bound; a slice whose whole deliverable is the specs needs no later plan to leave them provisional.
+Used to dogfood the family's own subsystems; a legacy module binds through a declared file set, never
+a refactor ride-along.
 
 ## Scale