@sabaiway/agent-workflow-kit 14.12.0 → 14.14.0

package/CHANGELOG.md

@@ -4,6 +4,61 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 14.14.0 — the Recommendations screen lists each step of the reference setup you have not taken or declined, with its preview command or the reason it has none (AD-160)
+
+**`/agent-workflow-kit recommendations` now shows what your project still lacks of the full flow.** Until 14.14.0
+only the upgrade's `tier` step judged the reference profile: the Recommendations screen, run on its own or at the end
+of an upgrade, read no profile, and a fresh bootstrap was never shown the offer. 14.14.0 puts each remaining difference
+the kit can detect on that screen, and bootstrap now shows the screen too. Story S6 of the epic
+`CONSUMERS-MOVE-ONTO-THE-FULL-FLOW`, its last; contract `docs/ai/specs/kit/tier/gap-screen/` (new).
+
+- **One optional item per gap.** For every entry of the profile-gap registry that your project lacks, has not
+  declined at the current lineage and can close with a command, the screen shows a `profile-gap` item: the step's id
+  and the profile's own sentence for it, and as its apply the same preview line the upgrade's `tier` step prints. A present step, or one you declined, shows
+  no item. A step the screen cannot close with a command — the session-close rules in an older wording, which the
+  upgrade's `lens` step refreshes, or a rules region you customized — is a stated skip with its reason, so the
+  screen does not claim `flow optimal` while it stands.
+- **Consent takes two steps.** The mode doc gains one posture note: the confirmed pick runs the preview and your
+  agent relays its lines; the same line with `--apply` runs only on a second yes. Items whose apply lines are equal
+  share one writer and one answer. A decline runs `tier-preview.mjs --decline` only when you refuse every item the tier
+  preview then reports offered, and a declined item stays off the screen until a lineage step changes the profile.
+- **Bootstrap renders the screen.** Step 11 of bootstrap runs the advisor and presents its section before the report
+  footer, as the upgrade does, so a new project is offered the same steps through the same writers. The accelerators
+  block after the footer keeps its entries; the gates bullet now points at the screen's `gates-declaration` item.
+- **The offer and the screen judge the same way.** `tools/profile-gaps.mjs` now exports the judgement the `tier`
+  step used privately, and both the offer and the new read-only module `tools/profile-gap-screen.mjs` call it, so the
+  two cannot disagree. Every line the `tier` step prints is unchanged. The `4.0.0` migration note now says an item
+  left `offered` stays on the Recommendations section that ends the upgrade, rather than waiting for the next one.
+
+
+## 14.13.0 — every session close tells you what was done and what comes next, and a project without a work queue is offered one (AD-159)
+
+**Your agent now ends a session with two short blocks written for you, and the handover keeps them.** Until 14.13.0
+the rules file did not ask for these two blocks, no memory template had a place for them, and a
+project with no `docs/plans/queue.md` had to write one by hand. 14.13.0 adds the rule, the slot, a checker for the
+slot, and a queue seed on the upgrade's existing one yes. Story S5 of the epic `CONSUMERS-MOVE-ONTO-THE-FULL-FLOW`;
+contract `docs/ai/specs/kit/tier/session-rules/` (new).
+
+- **Two rules in the rules template.** §2.5 Communication gains the bullet `Two blocks for the user`: at a plan's
+  approval, at a release and at every session close the message body carries *What was done, and for what* and
+  *What is next, and why*, in the dialogue language, with no internal ids and no review-round tallies. §2.7 Story
+  sessions gains one sentence: inside the tests and code sessions each task runs as its own carrier session. The
+  upgrade's `lens` step refreshes a region still equal to the text an earlier kit shipped, without an ask; a region
+  you edited is kept and flagged, as before.
+- **A `For the user` slot.** The handover template gains a `## For the user` section with the two labels, and the
+  changelog template's entry a `**For the user:**` line after its Goal. A project bootstrapped from now on starts with
+  them.
+- **`tools/session-close-check.mjs --check [--cwd <project>]`.** Read-only: it judges the `## For the user` section of
+  `docs/ai/handover.md`. Exit 0 prints one accept line; 1 prints every refusal found, one per line, each by its name; 2 is a usage error or a state it cannot judge,
+  named. It checks that both labels carry text, never what language the text is in or what it says. It is not
+  offered as a gate: a session close is not a commit.
+- **The upgrade offers a work queue.** The `tier` step's registry gains two entries after `checker-gates-declared`.
+  `named-queue-row-seed` offers to seed a missing `docs/plans/queue.md`; on the same one yes,
+  `tools/tier-preview.mjs --apply` writes it, create-only, from the kit's `references/authoring/QUEUE_TEMPLATE.md`:
+  the named-row rule, the purge archive, priority order and the check line, and four empty buckets. An existing queue
+  is never touched, and `queue-audit-cli`'s `--require-names` stays opt-in. `session-close-rules` only reports whether
+  both rules are current in your rules file; it never offers a write.
+
 ## 14.12.0 — the upgrade offers the kit's own checkers as gates of your project, each only where it can run (AD-158)
 
 **The kit's own checkers can now be declared as gates of your project without a hand edit.** Until 14.12.0 no

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow". New to the epic, story and task tier? Run `/agent-workflow-kit tier`.
 disable-model-invocation: true
 metadata:
-  version: '14.12.0'
+  version: '14.14.0'
 ---
 
 # agent-workflow-kit

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "14.12.0",
+  "version": "14.14.0",
   "provides": [],
   "roles": {},
   "detect": {

package/migrations/4.0.0-full-flow-offer.md

@@ -16,7 +16,8 @@ store `docs/ai/epics/`.
    "Before you upgrade" paragraph of the installed kit's `CHANGELOG.md` entry 14.2.0.
 2. **The offer:** it already ran as this upgrade's step-3 `tier` item. Re-run the preview
    `node <installed-kit>/tools/tier-preview.mjs --cwd <project>` to verify, and relay its lines;
-   never ask again. An item still `offered` waits for the next upgrade.
+   never ask again here. An item still `offered` stays on the Recommendations section that ends this
+   upgrade, under that item's two-step consent.
 3. **Re-stamp:** the upgrade re-stamps `docs/ai/.workflow-version` to 4.0.0.
 
 ## Verification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "14.12.0",
+  "version": "14.14.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/authoring/QUEUE_TEMPLATE.md

@@ -0,0 +1,19 @@
+# Work queue
+
+> This file names work; it never holds the analysis of it. A row opens with one plain sentence
+> saying what the work is for, then its ALL-CAPS id, then a short body.
+> A row that goes terminal leaves the queue in the change that mints its closing artifact; where
+> this file is gitignored, first snapshot the section to a purge archive with
+> `queue-purge-cli.mjs snapshot`, because git history keeps no tombstone.
+> Order inside a bucket is priority.
+> Check: `node <kit>/tools/queue-audit-cli.mjs --check docs/plans/queue.md --require-names`
+
+## Queue
+
+### Now
+
+### Next
+
+### Later
+
+### Frozen

package/references/modes/bootstrap.md

@@ -43,11 +43,11 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
     independent axes: a packaging-only release bumps the package but leaves the lineage head until a
     migration actually changes the deployed `docs/ai` structure. A stamp greater than the head →
     STOP (never downgrade).
-11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on what was filled with real data vs left as TODO, then print the **report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`, rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat closes on **one** caveat-aware next step (a behind member first, else `setup` / `recipes` / `velocity` / `agents` / `hook`). **After the footer, present ONE compact optional-accelerators block** — a one-line why each; every writer previews first, and nothing runs without a yes:
+11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on what was filled with real data vs left as TODO, then render the mandatory Recommendations section: run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root>` and PRESENT its output — from the `## Recommendations (agent-workflow)` header — in the user's conversational language: every fact, count and item from the tool, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; present-even-when-empty and verdict-first; then OFFER the consent-gated applies per `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`; then print the **report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`, rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat closes on **one** caveat-aware next step (a behind member first, else `setup` / `recipes` / `velocity` / `agents` / `hook`). **After the footer, present ONE compact optional-accelerators block** — a one-line why each; every writer previews first, and nothing runs without a yes:
     - `/agent-workflow-kit tier` — read-only: explains the epic, story and task tier and names the next step of the walk;
     - `/agent-workflow-kit velocity` — routine read-only commands stop prompting (incl. the `--kit-tools` tier for the kit's own read-only tools; `${CLAUDE_SKILL_DIR}/references/modes/velocity.md`);
     - `/agent-workflow-kit agents` — cheap-model subagents take the mechanical work (sweeps, changelog skeletons, gate triage; `${CLAUDE_SKILL_DIR}/references/modes/agents.md`);
-    - **gates seeding + hook** — offer to seed `docs/ai/gates.json` from the commands recon already recorded (step 1), via the consent-gated preview in `${CLAUDE_SKILL_DIR}/references/modes/gates.md` — this block is where that offer fires; then, once gates are declared, `/agent-workflow-kit hook` auto-approves exactly those declared commands (`${CLAUDE_SKILL_DIR}/references/modes/hook.md`);
+    - **gates seeding + hook** — offer to seed `docs/ai/gates.json` from the commands recon already recorded (step 1), via the consent-gated preview in `${CLAUDE_SKILL_DIR}/references/modes/gates.md` — the Recommendations section's `gates-declaration` item renders that offer first; then, once gates are declared, `/agent-workflow-kit hook` auto-approves exactly those declared commands (`${CLAUDE_SKILL_DIR}/references/modes/hook.md`);
     - `/agent-workflow-kit set-recipe` — put a ready review backend to work on plans and diffs (`${CLAUDE_SKILL_DIR}/references/modes/set-recipe.md`).
     Then **ask before committing** — never auto-commit.
 

package/references/modes/recommendations.md

@@ -4,7 +4,7 @@
 
 Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md
 
-The **read-only deployment advisor** — the deterministic section every `upgrade` run ends with, also invocable on its own. It computes what in THIS deployment is configured sub-optimally (allowlist not seeded, autonomy render drifted, sandbox unavailable, gates undeclared, a declared gate matrix that verifies nothing, bridge friction, sandbox-mask clutter, an unacknowledged sandbox recipe, a configured `subagent` carrier whose executor vehicle cannot carry it) and renders **verdict-first**: one composed verdict line, then each item as **{severity · what is sub-optimal · the benefit in ONE plain line · an optional `recipe:` line (the `sandbox-lane` live recipe — egress hosts + resolved writable dirs — the `worktrees-dir` hand-apply-first grant advice, or the `agents` / `executor-vehicle` hidden-mode reconcile follow-up) · the exact consent-gated apply one-liner}**. The tool computes deterministic English DATA; **you PRESENT the section in the user's conversational language** — every fact, count and item from the tool, nothing added or dropped; commands, paths, hosts and rule strings stay **byte-exact**; show the raw tool block on request (the AD-032 report-contract lane — the tool cannot know the dialogue language, so the language rendering is your presentation layer).
+The **read-only deployment advisor** — the deterministic section every `upgrade` run ends with, also invocable on its own. It computes what in THIS deployment is configured sub-optimally (allowlist not seeded, autonomy render drifted, sandbox unavailable, gates undeclared, a declared gate matrix that verifies nothing, bridge friction, sandbox-mask clutter, an unacknowledged sandbox recipe, a configured `subagent` carrier whose executor vehicle cannot carry it, a difference from the reference profile the project has not declined) and renders **verdict-first**: one composed verdict line, then each item as **{severity · what is sub-optimal · the benefit in ONE plain line · an optional `recipe:` line (the `sandbox-lane` live recipe — egress hosts + resolved writable dirs — the `worktrees-dir` hand-apply-first grant advice, or the `agents` / `executor-vehicle` hidden-mode reconcile follow-up) · the exact consent-gated apply one-liner}**. The tool computes deterministic English DATA; **you PRESENT the section in the user's conversational language** — every fact, count and item from the tool, nothing added or dropped; commands, paths, hosts and rule strings stay **byte-exact**; show the raw tool block on request (the AD-032 report-contract lane — the tool cannot know the dialogue language, so the language rendering is your presentation layer).
 
 **Live host/session facts are tool-composed only.** Every fact this section states about the current
 host or session — prompts fired, sandbox scope, whether a bypass was needed, network reachability,
@@ -37,6 +37,7 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root> [--
 - `mcp-channel` — the offer is to REGISTER the kit's read-only stdio MCP server in this project, which is a different kind of consent from the other velocity items: a registration is a command your MCP client will RUN, so the apply here is the mode's own **flagless preview**, which prints the exact entry and writes nothing — the `--apply` that follows is a SEPARATE step you run after reading that entry, and the consent flow never carries it. What the registration buys: path questions and literal searches become typed tool calls whose arguments are named JSON fields instead of a string handed to a shell, so a pipe, a redirect or a quote inside a pattern or a path stays DATA and is never interpreted — they are perfectly legal bytes to search for, there is simply no shell to read them as operators. Posture: the server is a **read-only child of your client** (path/type/size/line facts and literal search over this project root; no write and no exec API), and like the client itself it runs **outside the Bash sandbox** — the sandbox is not what bounds it, the server's own root containment is. The two allow rules it adds make those two tools promptless and nothing else. Two arms are **HAND-APPLY** and never run for you: **`.differing`** — an `agent-workflow` entry already stands in `.mcp.json` and **structurally differs** from what this kit copy would write (another kit copy, a hand-edited path, an added `env`; the comparison ignores key order, so re-serialized identical bytes are the same registration), and silently changing what an MCP server launches is exactly what consent must not slide past, so the remedy is your edit; and the **masked** arm, where an OS sandbox hides `.mcp.json` behind a device node — the kit cannot write there, so it hands you the text to paste from outside the sandbox. When the file is masked but the settings half is already complete, the item **does not render at all**: what is unobservable becomes a stated SKIP, so optimality is withheld rather than a registration you already made being offered again. Stated limit: this item does **not** detect a `disabledMcpjsonServers` veto, so a converged `mcp-channel` means *what the mode writes is in place*, not *the client will load it* — see `${CLAUDE_SKILL_DIR}/references/modes/mcp.md` for why that check was subtracted rather than half-built. Risk profile: a new read-only channel your client will launch; no write or exec exposure, and no existing declaration is touched.
 - ADDITIONAL `gates-inert` arms (the third outcomes) — two further arms, and they differ in whether anything is BROKEN. **`producer-unrecognized`** — a checker with no producer anywhere in the declaration, on a tracked tree the changed-line coverage domain cannot reach (`.ts`/`.tsx`/`.jsx`/`.mts`/`.cts` strictly outnumber `.mjs`/`.cjs`/`.js`): the dead pair is real, so this arm is **HAND-APPLY** and the two remedies are marking the real producer with `"lcovProducer": true` or dropping the checker. Never a `node --test` prescription over a project that has no such suite, never the fill preview, and never an acknowledgement — a dead pair is broken, not narrow, and removing a producer after an acknowledgement lands right back in this arm. **`coverage-domain-narrow`** — the producer/checker pair IS live and the tree is still dominated by what the domain excludes: nothing is broken, and the honest sentence is that certification covers the assessable minority. Its apply is the consent-gated **ack writer** preview (a NEUTRAL fingerprint into `docs/ai/acks.json` as `coverageDomainAck`, never a security key); after the SAME confirmation you run the `--apply` it prints. The fingerprint binds the FACT — the verdict plus the unsupported extensions present, never the file counts — so an acknowledged project stays quiet as it grows and re-fires when a new unsupported language arrives or the verdict flips. The census reads the TRACKED tree with a read-only `git ls-files`; a tree it cannot read (a non-git deployment) becomes a stated skip, so optimality is withheld rather than assumed. Risk profile: no enforcement change of any kind — one acknowledgement recorded in a family-owned file, and one hand edit that stays the maintainer's.
 - `spec-adoption` — the feature-spec layer's ADOPTION STATE, judged from `docs/ai/specs/` alone through the same census `spec-check --all` runs, so a store the checker would refuse to observe is never counted here either. Both arms are OFFERS (`optional`) — the layer is opt-in, and `attention` stays reserved for a configured declaration that is broken. **`not-adopted`** (no store): every plan then cites zero governing specs by default and nothing says adoption never started; its apply is the spec-layer ensure one-liner (`ensure-configs --reconcile --only specs`, the same seed `upgrade` runs — it writes the reader/checker pairs and the store root, create-only, and skips with a stated reason where no Node evidence exists), and its `recipe:` line carries a NAMED **HAND-APPLY alternative** — the DECLINE preview (`ack-write --lane spec-adoption`, a dry-run that prints the exact `--apply`), which records `specAdoptionAck` in the family-owned `docs/ai/acks.json`. **The two are exclusive, and the order is part of the contract:** ask which the maintainer wants BEFORE the confirmation; on "seed" run the apply; on "decline" run NOTHING — hand over the preview line and let them run it and its printed `--apply`; never run the seed after a decline was chosen, and never run the decline preview for them. **`adopting`** (a store with no live contract): an optional item naming the draft count; its apply is that same decline preview (a dry-run; after the SAME confirmation you run the `--apply` it prints), and the honest remedy is authoring a contract from the skill's `SPEC_TEMPLATE.md`. A recorded decline silences BOTH arms and shows on `status` as ` — declined`; one live contract makes the decline moot. An unreadable store is a stated skip, never `flow optimal`. Risk profile: the seed writes only create-only files under `scripts/` and `docs/ai/specs/`; the decline writes one key into the ack store; nothing here authors a spec or blocks a plan.
+- `profile-gap` — each item's apply is a PREVIEW that writes nothing, and consent takes two steps: the confirmed pick runs the preview and you relay every line it prints (the environment-resolved slot values, each checker `entry:` line with its trust-chain disclosure, a Communication region the insert plans in the same run); the same line with ` --apply` appended runs only on a SECOND yes over those lines, never carried by the first. Items whose apply lines are byte-equal are one writer and take one answer: the tier preview's `--apply` writes the absent slots, the store seed and the queue seed together; the checker verb writes only its own entries; the insert writes every region it plans, all or nothing, so a `communication-absent` skip beside a declined `story-sessions-section` gets its own ask after the insert's full preview. A no records nothing and the item stays on the screen. A DECLINE is asked apart from later, before anything runs, and runs `node ${CLAUDE_SKILL_DIR}/tools/tier-preview.mjs --decline --cwd <project-root>` only when the user refuses EVERY item the tier preview then reports offered: it records each of them at the shipped lineage, and a declined item leaves the screen until a lineage step changes the profile. An undecidable entry is a stated skip naming its reason, the remedy by reason: a prior → the upgrade's `lens` reconcile; an absent region → the insert; a customized region → a hand edit only (the lens preserves it), so that skip stands and withholds `flow optimal`. Risk profile: the tier preview's `--apply` rewrites `docs/ai/orchestration.json` in canonical form with the `_README` note and creates `docs/ai/epics/.gitkeep` and `docs/plans/queue.md` create-only; the insert adds regions to `docs/ai/agent_rules.md`; the checker verb adds entries to the PRIVILEGED `docs/ai/gates.json`; the decline writes `docs/ai/profile-declines.json`; nothing here commits.
 - `adr-store-migration` — other items write project files too; what is unique here is that the crossing **overwrites and deletes files the project already has**: it replaces the deployed enforcement scripts in `scripts/` (the directional subset — only basenames the project already has; a locally-edited copy is snapshotted first, never silently clobbered) and, where a retired archive file exists, DELETES it once conservation has been proven. That is why it is **HAND-APPLY** and why the command shown in the apply slot is a **`--dry-run`** — it writes nothing and prints the whole plan. `--apply` is a SEPARATE step, run only after that plan has been shown and **fresh consent** obtained for it; the consent flow executes only the apply slot, so an item that needs consent AFTER its preview cannot use that lane at all. Every write is idempotent and the run is re-runnable to completion after any interruption, so a re-run repairs rather than double-applies. It never commits. Risk profile: overwrite + delete of existing project files, gated on a preview you have actually read.
 
 **Sandbox lanes (what to DO with the `sandbox-lane` recipe, per host class):**

package/references/modes/upgrade.md

@@ -2,6 +2,7 @@
 
 <!-- opt-in-capability: family-freshness -->
 <!-- opt-in-capability: spec-adoption -->
+<!-- opt-in-capability: full-flow-profile -->
 
 Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKILL_DIR}/references/shared/composition-handoff.md · ${CLAUDE_SKILL_DIR}/references/shared/deploy-tail.md · ${CLAUDE_SKILL_DIR}/references/shared/command-shapes.md
 

package/references/templates/agent_rules.md

@@ -73,6 +73,7 @@ Apply this as part of §2 before any user-facing summary:
 - **Live host/session facts are tool-composed only.** Any claim about the current host or session state (prompts fired, sandbox scope, whether a bypass was needed, network reachability, approval counts) must trace to **live tool output** from **this session**; a memory/handover snapshot is **context, never report facts**, and a claim with no live signal is **omitted or explicitly marked unverified** — never asserted from recollection.
 - **The closing state block answers three DIFFERENT questions.** Close a user-facing message with three labelled slots — *now* · *what I need from you* · *what's next*. The slot LABELS stay ENGLISH — an English label is what lets a state-block checker FIND the block and its slots at all; everything written INTO a slot is in the project's dialogue language; when that language is not English, the checker's English phrase sets do not judge those values. **Now** = the state at this instant: what is RUNNING, or what the work is stopped on. It is **never a report of finished work** — what you completed goes in the message BODY, above the block. **From you** = the real unblocker, named; a turn that is ENDING always has one. **Next** = what follows. A *now* slot that opens with what was completed buries the one fact the reader opened the message for, and the three slots collapse into one restatement.
 - **A skip that contradicts the tree is a finding.** A tool-composed `skipped-*` line whose stated reason the observed tree disproves (a "no Node" skip beside deployed Node scripts) is raised as a FINDING in the report, never pasted as a neutral outcome — and a tool may not emit a skip whose reason it could itself disprove.
+- **Two blocks for the user.** At a plan's approval, at a release and at every session close, the message BODY — above the closing state block — carries two short blocks in the dialogue language. *What was done, and for what*: per item the user-facing problem, then what now exists; a command name is allowed, an internal id is not. *What is next, and why*: each proposal names its benefit, plus the one hand step if any. No internal ids, no review-round tallies. The same two blocks are the handover's `## For the user` section, which the kit's `session-close-check` checker judges at the close, where the kit is installed.
 
 ### 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.)
@@ -93,7 +94,7 @@ Apply these when authoring a plan, reviewing, folding a finding, or editing code
 - **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.
+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. Inside the tests and code sessions it is one task per session: each task runs as its own carrier session — one brief, one run, never one run for a whole wave — and the orchestrator's session briefs, checks, verifies and folds.
 
 ---
 

package/references/templates/changelog.md

@@ -17,6 +17,7 @@ maxLines: 700
 ## {{DATE}} — Bootstrap
 
 **Goal:** Initialise the AI-agent memory system.
+**For the user:** what was done, and for what — the project now has an AI-agent memory, so each session starts from the last one's record; what is next, and why — the first real task, whose entry says what it did for you.
 **Changes:**
 - Created `AGENTS.md` (entry point) + `CLAUDE.md` symlink.
 - Created `docs/ai/` with the spec files + `pages/`.

package/references/templates/handover.md

@@ -16,6 +16,14 @@ maxLines: 80
 **Branch:** {{BRANCH}}
 **Active recipes:** not recorded yet — paste the configured-recipe line (composed from `docs/ai/orchestration.json`) and refresh it whenever the config changes.
 
+## For the user
+
+**What was done, and for what:**
+- Bootstrap — the project now has an AI-agent memory, so each session starts from what the last one left.
+
+**What is next, and why:**
+- The first real task — its close replaces these two lines with what it did for you and what comes next.
+
 ## What was done last session
 
 - Bootstrap — AI-agent memory system initialised.

package/tools/direct-run.mjs

@@ -69,6 +69,7 @@ export const LIBRARY_ONLY_MODULES = Object.freeze({
   'reference-profile.mjs': '/agent-workflow-kit upgrade',
   // The read half of the checker-gates verb: the same step-3 `tier` item runs the verb that uses it.
   'checker-gates-read.mjs': '/agent-workflow-kit upgrade',
+  'profile-gap-screen.mjs': '/agent-workflow-kit recommendations',
 });
 
 // The frozen refusal line. One line, names the module, names the command.

package/tools/profile-gap-screen.mjs

@@ -0,0 +1,42 @@
+import { lstatSync, readFileSync } from 'node:fs';
+import { refuseDirectRun } from './direct-run.mjs';
+import { GAP_STATES, NO_COMMAND_SENTENCE, STORY_REGION_ABSENT, judgeProfileGaps } from './profile-gaps.mjs';
+import { readDeclines, readShippedProfile } from './reference-profile.mjs';
+
+const SESSION_RULES_ID = 'session-close-rules';
+const NOT_IN_PROFILE = 'not in the shipped profile';
+
+const refused = (reason) => ({ gaps: [], skips: [reason] });
+
+const disposeOf = ({ entry, state, reason }, root, hasById) => {
+  if (state === GAP_STATES.present || state === GAP_STATES.declined) return {};
+  if (state === GAP_STATES.undecidable) {
+    if (entry.id === SESSION_RULES_ID && reason === STORY_REGION_ABSENT) return {};
+    return { skip: `${entry.id}: ${reason}` };
+  }
+  const has = hasById.get(entry.id);
+  if (has === undefined) return { skip: `${entry.id}: ${NOT_IN_PROFILE}` };
+  const apply = entry.apply(root);
+  if (!apply) return { skip: `${entry.id}: ${NO_COMMAND_SENTENCE}` };
+  return { gap: { id: entry.id, what: `${entry.id}: ${has}`, apply } };
+};
+
+export const composeProfileGapScreen = ({ root, deps = {} }) => {
+  const io = { readFileSync, lstatSync, ...deps };
+  const shipped = readShippedProfile(io);
+  if (shipped.refusal) return refused(shipped.refusal);
+  const record = readDeclines(root, io);
+  if (record.refusal) return refused(record.refusal);
+  const hasById = new Map(shipped.profile.items.map(({ id, has }) => [id, has]));
+  const judged = judgeProfileGaps({ root, deps: io, lineage: shipped.profile.lineage, declined: record.declined });
+  const gaps = [];
+  const skips = [];
+  for (const item of judged) {
+    const { gap, skip } = disposeOf(item, root, hasById);
+    if (gap) gaps.push(gap);
+    if (skip) skips.push(skip);
+  }
+  return { gaps, skips };
+};
+
+refuseDirectRun(import.meta.url);

package/tools/profile-gaps.mjs

@@ -1,8 +1,9 @@
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CANDIDATE_STATES, isDeployed, judgeCheckerGates } from './checker-gates-read.mjs';
+import { normalizeLensBody, reconcileCommsText, reconcileStoryText } from './lens-region.mjs';
 import { CONFIG_REL, validateConfig } from './orchestration-config.mjs';
-import { TIER_TARGETS } from './reference-profile.mjs';
+import { TIER_TARGETS, isDeclineCurrent } from './reference-profile.mjs';
 import {
   RULES_REGIONS,
   extractRegionBy,
@@ -18,6 +19,14 @@ const SLOTS_ID = 'epic-task-slots';
 const STORE_ID = 'epic-store-seeded';
 const STORE_PATH = 'docs/ai/epics';
 const CHECKER_GATES_ID = 'checker-gates-declared';
+const SESSION_RULES_ID = 'session-close-rules';
+const QUEUE_SEED_ID = 'named-queue-row-seed';
+const PLANS_PATH = 'docs/plans';
+const QUEUE_PATH = 'docs/plans/queue.md';
+const QUEUE_SEED_PATH = fileURLToPath(new URL('../references/authoring/QUEUE_TEMPLATE.md', import.meta.url));
+const ABSENT_ARM_CODES = new Set(['ENOENT', 'ENOTDIR']);
+const CURRENT_STATUS = 'current';
+const REFRESHED_STATUS = 'refreshed';
 const TIER_PREVIEW_PATH = fileURLToPath(new URL('./tier-preview.mjs', import.meta.url));
 const CHECKER_GATES_PATH = fileURLToPath(new URL('./checker-gates.mjs', import.meta.url));
 const UNDECIDED_STATES = [CANDIDATE_STATES.idTaken, CANDIDATE_STATES.probeUnreadable, CANDIDATE_STATES.withheld];
@@ -47,7 +56,20 @@ const REASONS = Object.freeze({
   storeNotDirectory: 'store-not-directory',
   storeSymlink: 'store-symlink',
   storeUnreadable: 'store-unreadable',
+  headingTwice: 'heading-twice',
+  regionPrior: 'region-prior',
+  regionCustomized: 'region-customized',
+  plansSymlink: 'plans-symlink',
+  plansNotDirectory: 'plans-not-directory',
+  plansUnreadable: 'plans-unreadable',
+  queueSymlink: 'queue-symlink',
+  queueNotRegular: 'queue-not-regular',
+  queueUnreadable: 'queue-unreadable',
+  seedUnreadable: 'seed-unreadable',
 });
+export const STORY_REGION_ABSENT = 'story-sessions-absent';
+const REGION_ABSENT = Object.freeze({ communication: 'communication-absent', 'story-sessions': STORY_REGION_ABSENT });
+const JUDGEMENTS = Object.freeze({ communication: reconcileCommsText, 'story-sessions': reconcileStoryText });
 const TEMPLATE_REGIONS = RULES_REGIONS.filter(({ canon }) => canon === TEMPLATE_CANON);
 const STORY_REGION = RULES_REGIONS.find(({ id }) => id === STORY_ID);
 
@@ -162,6 +184,63 @@ const detectCheckerGates = ({ root, deps }) => {
   return undecided ? reportUndecidable(undecided.state) : { verdict: VERDICTS.present };
 };
 
+// A region is judged by the reconcile's own pure judgement, so this entry and the lens step agree.
+const judgeRegion = (text, spans, { id, headingRe, priors }) => {
+  if (!extractRegionBy(text, headingRe).found) return REGION_ABSENT[id];
+  const { status } = JUDGEMENTS[id](text, normalizeLensBody(spans[id].span), priors);
+  if (status === CURRENT_STATUS) return null;
+  return status === REFRESHED_STATUS ? REASONS.regionPrior : REASONS.regionCustomized;
+};
+
+const detectSessionRules = ({ root, deps }) => {
+  const template = readSpans(deps);
+  if (template.verdict) return template;
+  const target = readTarget(root, deps);
+  if (target.verdict) return target;
+  const { text } = target;
+  if (TEMPLATE_REGIONS.some(({ headingRe }) => extractRegionBy(text, headingRe).count > SINGLE_HEADING)) {
+    return reportUndecidable(REASONS.headingTwice);
+  }
+  for (const region of TEMPLATE_REGIONS) {
+    const reason = judgeRegion(text, template.spans, region);
+    if (reason) return reportUndecidable(reason);
+  }
+  return { verdict: VERDICTS.present };
+};
+
+export const readQueueSeed = (deps) => {
+  try {
+    return { bytes: deps.readFileSync(QUEUE_SEED_PATH) };
+  } catch {
+    return { reason: REASONS.seedUnreadable };
+  }
+};
+
+const absentUnlessSeedUnreadable = (deps) => {
+  const seed = readQueueSeed(deps);
+  return seed.reason ? reportUndecidable(seed.reason) : { verdict: VERDICTS.absent };
+};
+
+const detectQueueSeed = ({ root, deps }) => {
+  if (!isDeployed(root, deps)) return reportUndecidable(REASONS.noDeployment);
+  let plans;
+  try {
+    plans = deps.lstatSync(resolve(root, PLANS_PATH));
+  } catch (error) {
+    return ABSENT_ARM_CODES.has(error?.code) ? absentUnlessSeedUnreadable(deps) : reportUndecidable(REASONS.plansUnreadable);
+  }
+  if (plans.isSymbolicLink()) return reportUndecidable(REASONS.plansSymlink);
+  if (!plans.isDirectory()) return reportUndecidable(REASONS.plansNotDirectory);
+  let queue;
+  try {
+    queue = deps.lstatSync(resolve(root, QUEUE_PATH));
+  } catch (error) {
+    return error?.code === MISSING_FILE_CODE ? absentUnlessSeedUnreadable(deps) : reportUndecidable(REASONS.queueUnreadable);
+  }
+  if (queue.isSymbolicLink()) return reportUndecidable(REASONS.queueSymlink);
+  return queue.isFile() ? { verdict: VERDICTS.present } : reportUndecidable(REASONS.queueNotRegular);
+};
+
 const tierPreview = (root) => buildInsertPreview(root, TIER_PREVIEW_PATH);
 
 export const PROFILE_GAPS = Object.freeze([
@@ -169,4 +248,25 @@ export const PROFILE_GAPS = Object.freeze([
   Object.freeze({ id: SLOTS_ID, detect: detectSlots, apply: tierPreview }),
   Object.freeze({ id: STORE_ID, detect: detectStore, apply: tierPreview }),
   Object.freeze({ id: CHECKER_GATES_ID, detect: detectCheckerGates, apply: (root) => buildInsertPreview(root, CHECKER_GATES_PATH) }),
+  Object.freeze({ id: SESSION_RULES_ID, detect: detectSessionRules, apply: (root) => buildInsertPreview(root) }),
+  Object.freeze({ id: QUEUE_SEED_ID, detect: detectQueueSeed, apply: tierPreview }),
 ]);
+
+export const GAP_STATES = Object.freeze({
+  present: 'present',
+  offered: 'offered',
+  declined: 'declined',
+  undecidable: 'undecidable',
+});
+
+export const NO_COMMAND_SENTENCE = 'no runnable command — the root or the kit path carries a control byte or a backtick';
+
+export const judgeProfileGaps = ({ root, deps, lineage, declined }) => PROFILE_GAPS.map((entry) => {
+  const detected = entry.detect({ root, deps });
+  if (detected.verdict === VERDICTS.present) return { entry, state: GAP_STATES.present };
+  if (detected.verdict !== VERDICTS.absent) return { entry, state: GAP_STATES.undecidable, reason: detected.reason };
+  if (isDeclineCurrent(declined, entry.id, lineage)) {
+    return { entry, state: GAP_STATES.declined, lineage: declined[entry.id] };
+  }
+  return { entry, state: GAP_STATES.offered };
+});

package/tools/recommendations.mjs

@@ -100,6 +100,7 @@ import {
 } from './ack-store.mjs';
 import { ADOPTION, STORE_DIR_REL as SPEC_STORE_DIR_REL, SPEC_ADOPTION_LANE, declineFingerprint, readDeclineAck, surveySpecAdoption } from './spec-adoption.mjs';
 import { ENSURE_OPS } from './ensure-vocabulary.mjs';
+import { composeProfileGapScreen } from './profile-gap-screen.mjs';
 
 // The upgrade ensure that seeds the spec store — the not-adopted item's apply; pinned to the vocabulary.
 const SPEC_LAYER_ENSURE = ENSURE_OPS.includes('specs') ? 'specs' : null;
@@ -198,6 +199,7 @@ export const SEVERITIES = Object.freeze({
   // declaration that is broken): an absent store offers the seed, a store with no live contract offers
   // the decline. Neither arm can leave the flow-optimal line standing — an offer is still an item.
   'spec-adoption': SEVERITY_OPTIONAL,
+  'profile-gap': SEVERITY_OPTIONAL,
   'spec-adoption.adopting': SEVERITY_OPTIONAL,
 });
 // The per-item render tags (frozen presentation data, same language contract as the templates).
@@ -234,7 +236,8 @@ export const composeVerdict = ({ attention, optional, skipped }) => {
 // Every static WHAT template lives here — `<key>` is the item key, `<key>.<variant>` a per-site
 // variant of the same item — so ALL variants are assertable at build time (single line, char cap,
 // banned tokens), never a fixture-coverage gamble. A pure-placeholder template marks a WHAT whose
-// content is fully dynamic (capped at composition by truncation-with-count).
+// content is fully dynamic (capped at composition by truncation-with-count) — except `profile-gap`, whose
+// WHAT is never truncated: the leaf's suite pins every composed WHAT under the cap.
 export const WHATS = Object.freeze({
   'velocity-core': 'routine read-only commands still prompt — {n} audited read-only allowlist entr(ies) not seeded',
   'kit-tools-tier': "the kit's own read-only tools still prompt — {n} kit-tools tier entr(ies) not seeded",
@@ -273,6 +276,7 @@ export const WHATS = Object.freeze({
   'sandbox-lane': 'the wired review wrappers declare a session-sandbox recipe (egress hosts + writable state dirs) not yet acknowledged for this project',
   'worktrees-dir': 'write access to the worktrees parent dir {dir} is not confirmed — provision may still stop',
   'spec-adoption': 'feature-spec store absent (docs/ai/specs) — no feature contract can govern a plan here yet; seed the store, or record the decline',
+  'profile-gap': '{what}',
   'spec-adoption.adopting': 'feature-spec store: {n} draft spec(s), no live contract — nothing governs a plan through it yet; land a live contract, or record the decline',
 });
 
@@ -333,6 +337,7 @@ export const BENEFITS = Object.freeze({
   'sandbox-lane': 'discoverability — the manifest-declared observed sandbox recipe for bridge runs surfaces itself instead of waiting to be asked',
   'worktrees-dir': 'parallel features — the host-specific write allowance or terminal fallback is surfaced before provision',
   'spec-adoption': 'contracts — a plan names the contract it builds to, and a change to a governed slice is visible at review instead of after it',
+  'profile-gap': 'full flow — each difference from the reference profile is previewed by its own writer; a declined one returns only at a lineage step',
 });
 
 // ── the CLOSED opt-in capability registry (OPT-IN-SHIPS-INVISIBLE) ──────────────────────────────
@@ -379,6 +384,7 @@ export const OPT_IN_CAPABILITIES = Object.freeze([
   // The feature-spec layer is delivered by upgrade's spec-layer ensure (there is no specs mode), so
   // its adoption state is declared where the store is seeded.
   { id: 'spec-adoption', mode: 'upgrade', advisorKey: 'spec-adoption' },
+  { id: 'full-flow-profile', mode: 'upgrade', advisorKey: 'profile-gap' },
   { id: 'adr-store-migration', mode: 'migrate-adr-store', advisorKey: 'adr-store-migration' },
   { id: 'review-recipe', mode: 'set-recipe', advisorKey: 'review-recipe' },
   // The execute slot is a DISTINCT opt-in from the review slot, and the same probe reports both —
@@ -1297,7 +1303,7 @@ const readReadLaneToggle = (root, deps) => {
 // D3: the risk-marked keys — every key here has a per-item posture note in the mode doc, surfaced
 // at the consent moment; the static contract test asserts EXACT bidirectional coverage
 // (risk-marked keys == mode-doc note keys — a dropped note goes red, not silent).
-export const RISK_NOTED_KEYS = Object.freeze(['sandbox-lane', 'read-lane', 'worktrees-dir', 'adr-store-migration', 'gates-inert', 'source-size', 'gate-hook', 'mcp-channel', 'spec-adoption', 'enforcement']);
+export const RISK_NOTED_KEYS = Object.freeze(['sandbox-lane', 'read-lane', 'worktrees-dir', 'adr-store-migration', 'gates-inert', 'source-size', 'gate-hook', 'mcp-channel', 'spec-adoption', 'enforcement', 'profile-gap']);
 
 // The feature-spec layer's adoption state (contract: kit/spec-adoption). The canon lets a plan cite
 // zero governing specs while a project adopts the layer, and nothing ever said whether adoption had
@@ -1592,6 +1598,16 @@ const probeMcpChannel = ({ root, deps, add, skip }) => {
   }
 };
 
+export const probeProfileGaps = ({ root, deps, add, skip }) => {
+  try {
+    const { gaps, skips } = composeProfileGapScreen({ root, deps });
+    for (const { what, apply } of gaps) add('profile-gap', what, apply);
+    for (const reason of skips) skip('profile-gap', new Error(reason));
+  } catch (err) {
+    skip('profile-gap', err);
+  }
+};
+
 // ── assembly (frozen presentation order) ─────────────────────────────────────────────────────────
 const PROBES = Object.freeze([
   probeVelocityItems,
@@ -1614,6 +1630,7 @@ const PROBES = Object.freeze([
   probeWorktreesDir,
   probeMcpChannel,
   probeSpecAdoption,
+  probeProfileGaps,
 ]);
 
 export const buildRecommendations = ({ cwd, deps = {} } = {}) => {

package/tools/rules-regions.mjs

@@ -27,7 +27,7 @@ const SINGLE_QUOTE = "'";
 const QUOTE_ESCAPE = "'\\''";
 
 // Append the OUTGOING canon here in the same release that changes the template
-// §2.5 region — the fragment-or-prior reconcile depends on it.
+// §2.5 or §2.7 region — the fragment-or-prior reconcile depends on it.
 const COMMS_PRIOR_PRE_AD054 = `### 2.x. 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.
@@ -46,7 +46,13 @@ Apply this as part of §2 before any user-facing summary:
 - **Live host/session facts are tool-composed only.** Any claim about the current host or session state (prompts fired, sandbox scope, whether a bypass was needed, network reachability, approval counts) must trace to **live tool output** from **this session**; a memory/handover snapshot is **context, never report facts**, and a claim with no live signal is **omitted or explicitly marked unverified** — never asserted from recollection.`;
 const COMMS_PRIOR_STATE_BLOCK = `${COMMS_PRIOR_PLAIN_LANGUAGE}
 - **The closing state block answers three DIFFERENT questions.** Close a user-facing message with three labelled slots — *now* · *what I need from you* · *what's next*. The slot LABELS stay ENGLISH — an English label is what lets a state-block checker FIND the block and its slots at all; everything written INTO a slot is in the project's dialogue language; when that language is not English, the checker's English phrase sets do not judge those values. **Now** = the state at this instant: what is RUNNING, or what the work is stopped on. It is **never a report of finished work** — what you completed goes in the message BODY, above the block. **From you** = the real unblocker, named; a turn that is ENDING always has one. **Next** = what follows. A *now* slot that opens with what was completed buries the one fact the reader opened the message for, and the three slots collapse into one restatement.`;
-const COMMS_PRIORS = [COMMS_PRIOR_PRE_AD054, COMMS_PRIOR_AD054, COMMS_PRIOR_PLAIN_LANGUAGE, COMMS_PRIOR_STATE_BLOCK];
+const COMMS_PRIOR_SKIP_FINDING = `${COMMS_PRIOR_STATE_BLOCK}
+- **A skip that contradicts the tree is a finding.** A tool-composed \`skipped-*\` line whose stated reason the observed tree disproves (a "no Node" skip beside deployed Node scripts) is raised as a FINDING in the report, never pasted as a neutral outcome — and a tool may not emit a skip whose reason it could itself disprove.`;
+const COMMS_PRIORS = [
+  COMMS_PRIOR_PRE_AD054, COMMS_PRIOR_AD054, COMMS_PRIOR_PLAIN_LANGUAGE, COMMS_PRIOR_STATE_BLOCK, COMMS_PRIOR_SKIP_FINDING,
+];
+const STORY_PRIOR_FIVE_SESSIONS = `### 2.x. 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.`;
 
 export const RULES_REGIONS = Object.freeze([
   Object.freeze({
@@ -61,7 +67,7 @@ export const RULES_REGIONS = Object.freeze([
     headingRe: /^### 2[.]([0-9]+)[.] Story sessions/,
     label: '### 2.x. Story sessions',
     canon: TEMPLATE_CANON,
-    priors: [],
+    priors: [STORY_PRIOR_FIVE_SESSIONS],
   }),
   Object.freeze({
     id: 'lens',

package/tools/session-close-check.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// session-close-check.mjs — the read-only checker of a session close: judges the `## For the user`
+// section of docs/ai/handover.md and its two labels. Governing contract:
+// docs/ai/specs/kit/tier/session-rules/ (part session-close-check). Not a gate: a session close is
+// not a commit boundary. main(argv, deps) returns, never exits, never asks; every read goes through deps.
+import { resolve } from 'node:path';
+import { safeLine } from './carriers.mjs';
+import { isDeployed } from './checker-gates-read.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+
+const LF = String.fromCharCode(10);
+const CR = String.fromCharCode(13);
+const BOM_CHAR = String.fromCharCode(65279);
+const ARGV_OFFSET = 2;
+const EXIT_ACCEPT = 0;
+const EXIT_REFUSAL = 1;
+const EXIT_CANNOT_JUDGE = 2;
+const CHECK_FLAG = '--check';
+const CWD_FLAG = '--cwd';
+const HELP_FLAG = '--help';
+const HANDOVER_REL = 'docs/ai/handover.md';
+const SECTION_HEADING = '## For the user';
+const SECTION_BOUNDARY = '## ';
+const LABELS = Object.freeze(['**What was done, and for what:**', '**What is next, and why:**']);
+const SINGLE = 1;
+const SYMLINK_CLASS = 'symlink';
+
+const STATES = Object.freeze({
+  noDeployment: 'no-deployment',
+  handoverSymlink: 'handover-symlink',
+  handoverNotRegular: 'handover-not-regular',
+  handoverUnreadable: 'handover-unreadable',
+  handoverAbsent: 'handover-absent',
+  sectionAbsent: 'section-absent',
+  sectionTwice: 'section-twice',
+  labelAbsent: 'label-absent',
+  labelTwice: 'label-twice',
+  labelOrder: 'label-order',
+  labelEmpty: 'label-empty',
+});
+
+export const OUTCOME_LINES = Object.freeze({
+  accept: () => 'session-close-check: accept — the handover carries the For the user section with both labels and their text',
+  state: (name) => safeLine(name),
+  labelState: (name, label) => `${safeLine(name)}: ${safeLine(label)}`,
+  usage: (problem) => `usage: session-close-check.mjs --check [--cwd DIR] — ${safeLine(problem)}`,
+  help: () => [
+    'session-close-check.mjs --check [--cwd DIR]',
+    'Judges the For the user section of docs/ai/handover.md in DIR (default: the current directory); writes nothing.',
+    'Exit codes: 0 accept, 1 one refusal per line, 2 usage or cannot judge.',
+  ].join(LF),
+});
+
+const result = (code, stdout = '', stderr = '') => ({ code, stdout, stderr });
+const cannotJudge = (name) => result(EXIT_CANNOT_JUDGE, '', OUTCOME_LINES.state(name));
+
+const parseArgs = (argv) => {
+  if (argv.length === 1 && argv[0] === HELP_FLAG) return { help: true };
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    if (flag === HELP_FLAG) return { problem: `${HELP_FLAG} takes no other argument` };
+    if (flag === CHECK_FLAG) {
+      if (options.check) return { problem: `${CHECK_FLAG} given twice` };
+      options.check = true;
+    } else if (flag === CWD_FLAG) {
+      if (options.cwd !== undefined) return { problem: `${CWD_FLAG} given twice` };
+      const value = argv[index + 1];
+      if (value === undefined || value.startsWith('-')) return { problem: `${CWD_FLAG} needs a directory` };
+      options.cwd = value;
+      index += 1;
+    } else {
+      return { problem: `unknown argument ${flag}` };
+    }
+  }
+  if (!options.check) return { problem: `${CHECK_FLAG} is required` };
+  return { cwd: options.cwd ?? '.' };
+};
+
+const stripCr = (line) => (line.endsWith(CR) ? line.slice(0, -1) : line);
+const isBlank = (text) => text.trim() === '';
+
+const sectionLines = (text) => {
+  const lines = text.split(LF).map(stripCr);
+  if (lines[0].startsWith(BOM_CHAR)) lines[0] = lines[0].slice(BOM_CHAR.length);
+  const starts = lines.flatMap((line, index) => (line === SECTION_HEADING ? [index] : []));
+  if (starts.length !== SINGLE) return { state: starts.length === 0 ? STATES.sectionAbsent : STATES.sectionTwice };
+  const body = lines.slice(starts[0] + 1);
+  const end = body.findIndex((line) => line.startsWith(SECTION_BOUNDARY));
+  return { lines: end === -1 ? body : body.slice(0, end) };
+};
+
+const isLabelLine = (line) => LABELS.some((label) => line.startsWith(label));
+
+const hasText = (lines, index, label) => {
+  if (!isBlank(lines[index].slice(label.length))) return true;
+  const after = lines.slice(index + 1);
+  const next = after.findIndex(isLabelLine);
+  return (next === -1 ? after : after.slice(0, next)).some((line) => !isBlank(line));
+};
+
+const judgeLabels = (lines) => {
+  const found = LABELS.map((label) => ({
+    label,
+    at: lines.flatMap((line, index) => (line.startsWith(label) ? [index] : [])),
+  }));
+  const once = found.filter(({ at }) => at.length === SINGLE);
+  const refusals = [
+    ...found.filter(({ at }) => at.length === 0).map(({ label }) => OUTCOME_LINES.labelState(STATES.labelAbsent, label)),
+    ...found.filter(({ at }) => at.length > SINGLE).map(({ label }) => OUTCOME_LINES.labelState(STATES.labelTwice, label)),
+  ];
+  if (once.length === LABELS.length && once[1].at[0] < once[0].at[0]) refusals.push(OUTCOME_LINES.state(STATES.labelOrder));
+  for (const { label, at } of once) {
+    if (!hasText(lines, at[0], label)) refusals.push(OUTCOME_LINES.labelState(STATES.labelEmpty, label));
+  }
+  return refusals;
+};
+
+const judgeHandover = (content) => {
+  const section = sectionLines(content);
+  if (section.state) return [OUTCOME_LINES.state(section.state)];
+  return judgeLabels(section.lines);
+};
+
+const runCheck = (options, deps) => {
+  const root = resolve(options.cwd);
+  if (!isDeployed(root, deps)) return cannotJudge(STATES.noDeployment);
+  const read = readRegularFileNoFollow(resolve(root, HANDOVER_REL), deps);
+  if (read.outcome === 'absent') return result(EXIT_REFUSAL, '', OUTCOME_LINES.state(STATES.handoverAbsent));
+  if (read.outcome === 'foreign') {
+    return cannotJudge(read.className === SYMLINK_CLASS ? STATES.handoverSymlink : STATES.handoverNotRegular);
+  }
+  if (read.outcome !== 'ok') return cannotJudge(STATES.handoverUnreadable);
+  const refusals = judgeHandover(read.content);
+  if (refusals.length > 0) return result(EXIT_REFUSAL, '', refusals.join(LF));
+  return result(EXIT_ACCEPT, OUTCOME_LINES.accept());
+};
+
+export const main = (argv, deps = {}) => {
+  const parsed = parseArgs(argv);
+  if (parsed.help) return result(EXIT_ACCEPT, OUTCOME_LINES.help());
+  if (parsed.problem) return result(EXIT_CANNOT_JUDGE, '', OUTCOME_LINES.usage(parsed.problem));
+  return runCheck(parsed, deps);
+};
+
+if (isDirectRun(import.meta.url)) {
+  const outcome = main(process.argv.slice(ARGV_OFFSET));
+  if (outcome.stdout) console.log(outcome.stdout);
+  if (outcome.stderr) console.error(outcome.stderr);
+  process.exitCode = outcome.code;
+}

package/tools/tier-preview.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // tier-preview.mjs — the offer of lineage step 4.0.0: one preview over the whole profile-gap
-// registry; on an explicit yes (--apply) the absent epic and task slots and the epic store seed;
+// registry; on an explicit yes (--apply) the absent epic and task slots, the epic store seed and the queue seed;
 // on an explicit no (--decline) the decline record. Governing contract:
 // docs/ai/specs/kit/tier/tier-offer/ (part tier-preview). main(argv, deps) returns, never exits,
 // never asks; every read and write goes through deps.
@@ -12,9 +12,9 @@ import { isDirectRun } from './direct-run.mjs';
 import { tmpNote } from './ensure-ops.mjs';
 import { CANON_README, applySetOps, refreshReadme } from './orchestration-config.mjs';
 import { writeConfig } from './orchestration-write.mjs';
-import { PROFILE_GAPS, readTierConfig } from './profile-gaps.mjs';
+import { GAP_STATES, NO_COMMAND_SENTENCE, judgeProfileGaps, readQueueSeed, readTierConfig } from './profile-gaps.mjs';
 import { composeReadiness, planRecipe } from './recipes.mjs';
-import { TIER_TARGETS, isDeclineCurrent, readDeclines, readShippedProfile } from './reference-profile.mjs';
+import { TIER_TARGETS, readDeclines, readShippedProfile } from './reference-profile.mjs';
 
 const LF = String.fromCharCode(10);
 const ARGV_OFFSET = 2;
@@ -30,30 +30,28 @@ const SLOTS_ID = 'epic-task-slots';
 const STORE_ID = 'epic-store-seeded';
 const STORE_DIR = 'docs/ai/epics';
 const STORE_SEED = 'docs/ai/epics/.gitkeep';
+const QUEUE_ID = 'named-queue-row-seed';
+const PLANS_DIR = 'docs/plans';
+const QUEUE_SEED = 'docs/plans/queue.md';
+const MISSING_CODE = 'ENOENT';
 const CONFIG_WRITTEN = 'docs/ai/orchestration.json';
 const DECLINES_REL = 'docs/ai/profile-declines.json';
 const SCHEMA = 1;
 const INDENT = '  ';
 const WORDS = Object.freeze({
-  present: 'present',
-  offered: 'offered',
-  declined: 'declined',
-  undecidable: 'undecidable',
   applied: 'applied',
   recorded: 'recorded',
 });
-const ABSENT_VERDICT = 'absent';
-const PRESENT_VERDICT = 'present';
 
 export const OUTCOME_LINES = Object.freeze({
   entry: (id, word, detail) => `${id}: ${word}${detail ? ` — ${detail}` : ''}`,
   declinedAt: (lineage) => `at lineage ${lineage}`,
   applyLine: (command) => `${INDENT}apply: ${command}`,
-  noCommand: () => `${INDENT}apply: no runnable command — the root or the kit path carries a control byte or a backtick`,
+  noCommand: () => `${INDENT}apply: ${NO_COMMAND_SENTENCE}`,
   slotValue: (activity, slot, value, skipped = []) => `${INDENT}${activity}.${slot} = ${value}`
     + skipped.map(({ candidate, reason }) => ` — ${candidate} skipped: ${reason}`).join(''),
   slotPresent: (activity, slot) => `${INDENT}${activity}.${slot}: present`,
-  tmpLeft: (tmp) => tmpNote(STORE_SEED, tmp)[0],
+  tmpLeft: (rel, tmp) => tmpNote(rel, tmp)[0],
   nothingOffered: () => 'nothing offered — nothing recorded',
   detectFailed: (cause) => `backend detection failed (${safeLine(cause)}) — every bridge is treated as not ready`,
   refusal: (name, detail) => `tier-preview: refused — ${name}${detail ? `: ${safeLine(detail)}` : ''}`,
@@ -61,7 +59,7 @@ export const OUTCOME_LINES = Object.freeze({
   help: () => [
     'tier-preview.mjs --cwd DIR [--apply | --decline]',
     'Previews every profile gap of the project in DIR; writes nothing by default.',
-    '--apply writes the offered items: the absent epic and task settings and the epic store seed.',
+    '--apply writes the offered items: the absent epic and task settings, the epic store seed and the queue seed.',
     '--decline records every offered item as declined at the shipped profile lineage.',
     'Exit codes: 0 done, 1 one named refusal, 2 usage.',
   ].join(LF),
@@ -121,23 +119,18 @@ const slotLines = (slots) => slots.map(({ target, declared, value, skipped }) =>
   ? OUTCOME_LINES.slotPresent(target.activity, target.slot)
   : OUTCOME_LINES.slotValue(target.activity, target.slot, value, skipped)));
 
-const judgeEntries = (root, deps, profile, declined) => PROFILE_GAPS.map((entry) => {
-  const detected = entry.detect({ root, deps });
-  if (detected.verdict === PRESENT_VERDICT) return { entry, word: WORDS.present };
-  if (detected.verdict !== ABSENT_VERDICT) return { entry, word: WORDS.undecidable, detail: detected.reason };
-  if (isDeclineCurrent(declined, entry.id, profile.lineage)) {
-    return { entry, word: WORDS.declined, detail: OUTCOME_LINES.declinedAt(declined[entry.id]) };
-  }
-  return { entry, word: WORDS.offered };
-});
+const judgeEntries = (root, deps, profile, declined) => judgeProfileGaps({ root, deps, lineage: profile.lineage, declined })
+  .map(({ entry, state, lineage, reason }) => ({
+    entry, word: state, detail: state === GAP_STATES.declined ? OUTCOME_LINES.declinedAt(lineage) : reason,
+  }));
 
 const renderEntry = ({ entry, word, detail }, root, slots) => {
   const lines = [OUTCOME_LINES.entry(entry.id, word, detail)];
-  if (word === WORDS.offered) {
+  if (word === GAP_STATES.offered) {
     const command = entry.apply(root);
     lines.push(command ? OUTCOME_LINES.applyLine(command) : OUTCOME_LINES.noCommand());
   }
-  if (entry.id === SLOTS_ID && (word === WORDS.offered || word === WORDS.applied)) lines.push(...slotLines(slots));
+  if (entry.id === SLOTS_ID && (word === GAP_STATES.offered || word === WORDS.applied)) lines.push(...slotLines(slots));
   return lines;
 };
 
@@ -149,19 +142,40 @@ const writeSlots = (root, config, slots, deps) => {
   writeConfig(root, refreshReadme(merged).config, deps);
 };
 
-const storeCreated = (root, deps) => {
+const directoryAt = (root, rel, deps) => {
   try {
-    return deps.lstat(resolve(root, STORE_DIR)).isDirectory();
+    return deps.lstat(resolve(root, rel)).isDirectory();
   } catch {
     return false;
   }
 };
 
+const missingAt = (root, rel, deps) => {
+  try {
+    deps.lstat(resolve(root, rel));
+    return false;
+  } catch (error) {
+    return error?.code === MISSING_CODE;
+  }
+};
+
+const writeQueueSeed = (root, deps, bytes, made) => {
+  const plansMissing = missingAt(root, PLANS_DIR, deps);
+  try {
+    return { seeded: writeProjectFileCreateOnly(root, QUEUE_SEED, bytes, deps, { noun: 'the queue seed' }) };
+  } catch (error) {
+    if (plansMissing && directoryAt(root, PLANS_DIR, deps)) made.push(`${PLANS_DIR} created`);
+    return { refusal: refuse('write-failed', [...made, causeOf(error)].join('; ')) };
+  }
+};
+
 const runApply = (root, deps, judged, slots, config) => {
   const byId = new Map(judged.map((item) => [item.entry.id, item]));
   const extra = [];
   const made = [];
-  if (byId.get(SLOTS_ID)?.word === WORDS.offered) {
+  const seed = byId.get(QUEUE_ID)?.word === GAP_STATES.offered ? readQueueSeed(deps) : null;
+  if (seed?.reason) return { refusal: refuse(seed.reason) };
+  if (byId.get(SLOTS_ID)?.word === GAP_STATES.offered) {
     try {
       writeSlots(root, config, slots, deps);
     } catch (error) {
@@ -170,16 +184,26 @@ const runApply = (root, deps, judged, slots, config) => {
     made.push(`${CONFIG_WRITTEN} written`);
     byId.set(SLOTS_ID, { ...byId.get(SLOTS_ID), word: WORDS.applied });
   }
-  if (byId.get(STORE_ID)?.word === WORDS.offered) {
+  if (byId.get(STORE_ID)?.word === GAP_STATES.offered) {
     let seeded;
     try {
       seeded = writeProjectFileCreateOnly(root, STORE_SEED, '', deps, { noun: 'the epic store seed' });
     } catch (error) {
-      if (storeCreated(root, deps)) made.push(`${STORE_DIR} created`);
+      if (directoryAt(root, STORE_DIR, deps)) made.push(`${STORE_DIR} created`);
       return { refusal: refuse('write-failed', [...made, causeOf(error)].join('; ')) };
     }
-    byId.set(STORE_ID, { ...byId.get(STORE_ID), word: seeded.created ? WORDS.applied : WORDS.present });
-    if (seeded.tmpLeftBehind) extra.push(OUTCOME_LINES.tmpLeft(seeded.tmpLeftBehind));
+    byId.set(STORE_ID, { ...byId.get(STORE_ID), word: seeded.created ? WORDS.applied : GAP_STATES.present });
+    if (seeded.created) made.push(`${STORE_SEED} created`);
+    if (seeded.tmpLeftBehind) {
+      extra.push(OUTCOME_LINES.tmpLeft(STORE_SEED, seeded.tmpLeftBehind));
+      made.push(`${seeded.tmpLeftBehind} left behind`);
+    }
+  }
+  if (seed) {
+    const written = writeQueueSeed(root, deps, seed.bytes, made);
+    if (written.refusal) return written;
+    byId.set(QUEUE_ID, { ...byId.get(QUEUE_ID), word: written.seeded.created ? WORDS.applied : GAP_STATES.present });
+    if (written.seeded.tmpLeftBehind) extra.push(OUTCOME_LINES.tmpLeft(QUEUE_SEED, written.seeded.tmpLeftBehind));
   }
   return { judged: judged.map((item) => byId.get(item.entry.id)), extra };
 };
@@ -190,7 +214,7 @@ const serializeDeclines = (declined) => {
 };
 
 const runDecline = (root, deps, judged, profile, declined) => {
-  const offered = judged.filter(({ word }) => word === WORDS.offered);
+  const offered = judged.filter(({ word }) => word === GAP_STATES.offered);
   if (offered.length === 0) return { judged, extra: [OUTCOME_LINES.nothingOffered()] };
   const merged = { ...(declined ?? {}) };
   for (const { entry } of offered) merged[entry.id] = profile.lineage;
@@ -200,7 +224,7 @@ const runDecline = (root, deps, judged, profile, declined) => {
     return { refusal: refuse('write-failed', causeOf(error)) };
   }
   return {
-    judged: judged.map((item) => (item.word === WORDS.offered ? { ...item, word: WORDS.recorded } : item)),
+    judged: judged.map((item) => (item.word === GAP_STATES.offered ? { ...item, word: WORDS.recorded } : item)),
     extra: [],
   };
 };
@@ -222,7 +246,7 @@ const runOffer = (options, given) => {
     ...deps, onDetectError: (error) => notes.push(OUTCOME_LINES.detectFailed(causeOf(error))),
   });
   const judged = judgeEntries(root, deps, shipped.profile, record.declined);
-  const offersSlots = judged.some(({ entry, word }) => entry.id === SLOTS_ID && word === WORDS.offered);
+  const offersSlots = judged.some(({ entry, word }) => entry.id === SLOTS_ID && word === GAP_STATES.offered);
   const config = offersSlots ? readTierConfig(root, deps).config : null;
   const slots = offersSlots ? planSlots(config, readiness) : [];
   let outcome = { judged, extra: [] };