@sabaiway/agent-workflow-kit 14.13.0 → 14.14.1

package/CHANGELOG.md

@@ -4,6 +4,47 @@ 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.1 — the agents writer stops on a project folder given as a symlink, before it reads or writes anything (AD-161)
+
+**`cheap-agents.mjs --cwd <dir>` now refuses a `<dir>` that is itself a symlink.** Until 14.14.1 an `--apply` there
+wrote the vehicles through the link. With a hand-edited executor it placed `changelog-skeleton.md` and then failed on
+the executor with an uncoded error, leaving `.claude/agents/` half placed; with a trailing `/` even that executor was
+rewritten through the link.
+
+- **The refusal.** `<link>`, `<link>/` and `<link>/.` stop with `CHEAP_AGENTS_SYMLINK`, exit 1, and a message naming
+  the project root as a symlink the writer refuses to write through. It is the first step of `--dry-run` and
+  `--apply` alike and of a direct `preflightCheapAgents` call: nothing under the root is read, nothing is written.
+- **What stays.** A real directory, a regular file, an absent path and a project reached through a linked parent
+  directory get the same answers as in 14.14.0, and so does the default, the current directory. The mode doc's
+  symlink-safe line and the tool header name the project root.
+
+## 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

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.13.0'
+  version: '14.14.1'
 ---
 
 # agent-workflow-kit

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "14.13.0",
+  "version": "14.14.1",
   "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.13.0",
+  "version": "14.14.1",
   "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/modes/agents.md

@@ -19,7 +19,7 @@ Writing code, running gates, and user-facing copy never move to these four vehic
 Run `node ${CLAUDE_SKILL_DIR}/tools/cheap-agents.mjs [--dry-run | --apply] [--cwd <dir>]`:
 
 1. **`--dry-run` first, always** (the default — changes nothing). It previews, per bundled vehicle, whether it **would place** the file, finds it **already current**, or finds a **customized** file (different content) that will be **preserved, never overwritten** (delete the file to reseed it from the bundle) — except the executor, whose differing bytes **would re-derive** from `docs/ai/vehicles.json` and are rewritten on `--apply` (a hand edit is replaced, never preserved).
-2. **Only on an explicit yes**, re-run with `--apply`. It writes **only** under `.claude/agents/` — never `settings.json` / `settings.local.json`, never a commit. `--apply` is deployment-gated (the stamp must be at the lineage head) and symlink-safe (a symlinked `.claude` / `.claude/agents` / target file is a STOP).
+2. **Only on an explicit yes**, re-run with `--apply`. It writes **only** under `.claude/agents/` — never `settings.json` / `settings.local.json`, never a commit. `--apply` is deployment-gated (the stamp must be at the lineage head) and symlink-safe (a symlinked project root / `.claude` / `.claude/agents` / target file is a STOP, in a `--dry-run` too).
 3. **Hidden-mode deployments:** after apply, run the hide-footprint reconcile (`node ${CLAUDE_SKILL_DIR}/tools/hide-footprint.mjs --dir <project> --reconcile`) so the placed files stay invisible to `git status` — `/.claude/agents/` is in the known-footprint registry; the apply report reminds you.
 
 **Invariants:** writer (writes only `.claude/agents/`) · preview by default · a diverged existing file is reported and preserved, never clobbered — except the executor, re-derived from `docs/ai/vehicles.json` on apply · never touches settings · never commits · **no READ-ONLY vehicle grants `Bash`, and exactly one bundled vehicle, `executor`, grants a shell** · the cheap-lane vehicles are pinned to `model: haiku` + `effort: low`, and the review lens is pinned OFF the cheap model (all content-tested).

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/tools/cheap-agents.mjs

@@ -12,8 +12,8 @@
 //   • deployment-gated — `--apply` STOPs unless docs/ai/.workflow-version equals the lineage
 //     head (a dry-run stays usable whatever the stamp says; an unreadable orchestration config
 //     STOPs both, since the derived lenses it names cannot be known);
-//   • symlink-safe — a symlinked `.claude` / `.claude/agents` / target file is a STOP, never a
-//     write-through;
+//   • symlink-safe — a symlinked project root, `.claude`, `.claude/agents` or target file is a
+//     STOP, in a dry-run too, never a write-through;
 //   • preserves differing .claude/agents/ files (`customized — preserved`), except the executor:
 //     on apply its body is re-derived from docs/ai/vehicles.json, replacing a hand edit;
 //     an identical file is `already current` (idempotent re-run);
@@ -31,7 +31,7 @@
 // Dependency-free, Node >= 22. No side effects on import.
 
 import { mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isDirectRun } from './direct-run.mjs';
 import { shellQuoteArg } from './repo-lex.mjs';
@@ -117,9 +117,21 @@ const writeFsDeps = (deps = {}) => ({
   writeFile: deps.writeFile ?? writeFileSync,
 });
 
+const refuseSymlinkedRoot = (projectDir, deps) => {
+  const root = resolve(projectDir);
+  let stat;
+  try {
+    stat = readFsDeps(deps).lstat(root);
+  } catch {
+    return;
+  }
+  if (stat.isSymbolicLink()) throw makeCheapAgentsError(CHEAP_AGENTS_SYMLINK, `the project root ${root} is a symlink — refusing to write through it`);
+};
+
 export const preflightCheapAgents = ({ cwd, derived = [] }, deps = {}) => {
   const fs = readFsDeps(deps);
   const projectDir = cwd ?? process.cwd();
+  refuseSymlinkedRoot(projectDir, deps);
   const templatesByName = new Map(readBundledAgents(deps).map((template) => [template.name, template]));
   for (const template of derived) templatesByName.set(template.name, template);
   const templates = [...templatesByName.values()];
@@ -169,6 +181,7 @@ export const applyCheapAgentsCommand = (root) =>
 export const writeCheapAgents = ({ cwd, dryRun = true } = {}, deps = {}) => {
   const fs = writeFsDeps(deps);
   const projectDir = cwd ?? process.cwd();
+  refuseSymlinkedRoot(projectDir, deps);
   const posture = loadExecutorPostureOrStop(projectDir, deps);
   const derived = [executorTemplate(posture, deps), ...configuredDerivedTemplates(projectDir, deps)];
   const preflight = preflightCheapAgents({ cwd: projectDir, derived }, deps);

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

@@ -3,7 +3,7 @@ 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,
@@ -67,7 +67,8 @@ const REASONS = Object.freeze({
   queueUnreadable: 'queue-unreadable',
   seedUnreadable: 'seed-unreadable',
 });
-const REGION_ABSENT = Object.freeze({ communication: 'communication-absent', 'story-sessions': 'story-sessions-absent' });
+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);
@@ -250,3 +251,22 @@ export const PROFILE_GAPS = Object.freeze([
   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/tier-preview.mjs

@@ -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, readQueueSeed, 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;
@@ -39,21 +39,15 @@ 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`,
@@ -125,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;
 };
 
@@ -184,9 +173,9 @@ const runApply = (root, deps, judged, slots, config) => {
   const byId = new Map(judged.map((item) => [item.entry.id, item]));
   const extra = [];
   const made = [];
-  const seed = byId.get(QUEUE_ID)?.word === WORDS.offered ? readQueueSeed(deps) : null;
+  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 === WORDS.offered) {
+  if (byId.get(SLOTS_ID)?.word === GAP_STATES.offered) {
     try {
       writeSlots(root, config, slots, deps);
     } catch (error) {
@@ -195,7 +184,7 @@ 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' });
@@ -203,7 +192,7 @@ const runApply = (root, deps, judged, slots, config) => {
       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 });
+    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));
@@ -213,7 +202,7 @@ const runApply = (root, deps, judged, slots, config) => {
   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 : WORDS.present });
+    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 };
@@ -225,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;
@@ -235,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: [],
   };
 };
@@ -257,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: [] };