@sabaiway/agent-workflow-kit 14.25.0 → 14.25.2

package/CHANGELOG.md

@@ -4,6 +4,29 @@ 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.25.2 — the gate migration names `"lcovProducer": true` in the four hints that print the paste-ready suite cmd (AD-175)
+
+- **A suite cmd the migration cannot recognise is no longer told only to rewrite itself.** When the upgrade's
+  `gates-migration` step (`references/scripts/migrate-gates.mjs`) finds no gate it recognises as the lcov producer, for
+  example a suite cmd that starts with `shopt -s globstar &&`, it asked only for the canonical `node --test` form. It
+  now also says: `or, if your suite cmd already writes that lcov in a form this check cannot recognise, add
+  "lcovProducer": true to that gate in docs/ai/gates.json`. The marker is the second producer form `gates.md` already
+  documents, and for a suite cmd that keeps a `shopt -s globstar &&` prefix the only one that works. The line rides the customized `unit-tests`
+  recovery, the INERT row of a vendored checker, and both coverage-check warnings; every existing sentence is unchanged
+  and no migration result changes.
+
+## 14.25.1 — `init` reports what it did: a replaced MCP entry is labelled replaced, and a folder inside a kept folder prints no line of its own (AD-174)
+
+- **The MCP apply report no longer shows the old entry as the current one.** After the `y` that replaces a differing
+  `agent-workflow` entry, `init` printed the old entry under `the entry standing in .mcp.json now:` while the file
+  already held the new one. It now prints `the entry this run replaced in .mcp.json:` and `the entry now in
+  .mcp.json`. The preview before the `y` is unchanged.
+- **A folder inside a kept folder prints no line of its own.** A folder inside one of the kit's own folders
+  (`tools/`, `references/` and the like) that the package does not carry is still kept and reported as yours to
+  remove by hand, but the folders inside it no longer print a line each:
+  a home that kept an emptied `tools/manifest/fixtures/` printed 18 lines on every run and now prints one. A stray
+  file inside such a folder is still removed with its own line.
+
 ## 14.25.0 — `init`, run in a console from a project's folder, applies that project's harness configuration on one "y" (AD-173)
 
 **`npx @sabaiway/agent-workflow-kit@latest init` gains a project step.** Run in your own console from a project's

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`. A typed decision with a confidence from Jev? Run `/agent-workflow-kit jev`.
 disable-model-invocation: true
 metadata:
-  version: '14.25.0'
+  version: '14.25.2'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "14.25.0",
+  "version": "14.25.2",
   "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/mcp.md

@@ -25,7 +25,7 @@ An existing `.mcp.json` and `.claude/settings.json` are written in place: each k
 
 - **DIFFERING** — `.mcp.json` already carries an `"agent-workflow"` entry that **structurally differs** from ours (another kit copy, a hand-edited path, an added `env`, a `null`). The comparison is deliberately key-order-independent, so a re-serialized identical entry is the SAME registration, while any real difference in what would be launched is a difference. Without `--replace`, the run **STOPs unwritten, on both lanes**: silently changing what an MCP server launches is exactly what consent must not slide past.
   With `--replace`, the preview prints the entry standing in `.mcp.json` now and the entry this registration declares, writes nothing and exits 0.
-  With `--replace --apply`, it replaces that entry, keeping every other server and key of `.mcp.json`.
+  With `--replace --apply`, it replaces that entry, keeping every other server and key of `.mcp.json`, and prints the old entry as the one it replaced and ours as the one now in the file.
   This is the console item `mcp-channel.differing`: `init` previews it in the user's console and applies it on the terminal "y".
 - **MASKED** — an OS sandbox injects a **character device** where `.mcp.json` would be (this is the normal condition of a sandboxed session, not a fault; see `${CLAUDE_SKILL_DIR}/references/modes/sandbox-masks.md`). Writing through a device node is refused by construction, so the mode **hands over what to merge, writes nothing, and exits 0**. The two halves of that handoff are worded differently, and the difference is load-bearing: `.claude/settings.json` was **observable — and read where present** — so its body is a real merge already carrying every foreign key it had, while the masked `.mcp.json` was not observable at all, so the mode hands over **the entry alone**, to be merged under `mcpServers` keeping every other server. A whole-file body would name only our server, and pasted as instructed it would delete every server the mask hid. Every other never-committable class (block device, FIFO, socket) takes the same arm. The handoff is scoped to `.mcp.json`: a masked `settings.json` is a **refusal**, because this mode can neither write it nor merge into what it cannot read.
 

package/references/scripts/migrate-gates.mjs

@@ -461,12 +461,14 @@ export const resultingGates = (plan) => {
   return [...kept, ...moved, ...added]; // move/add go LAST — the checker ends up the last declared gate
 };
 
+const MARKER_LANE = 'or, if your suite cmd already writes that lcov in a form this check cannot recognise, add "lcovProducer": true to that gate in docs/ai/gates.json';
+
 // The per-entry customized recovery: a unit-tests-class entry gets the FULL canonical flag set
 // (the intent is known — the cmd shape just cannot be verified); anything else gets the
 // dead-tool recovery.
 const customizedRecovery = (gate) =>
   gate.id === 'unit-tests'
-    ? `declare the canonical suite gate by hand so the coverage contract is verifiable: node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths>`
+    ? `declare the canonical suite gate by hand so the coverage contract is verifiable: node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths> — ${MARKER_LANE}`
     : 'remove the entry, or repoint it at a living check — the review-ledger / fold-completeness tools no longer exist.';
 
 const warningLines = ({ customized, finalCapable, hasReviewState = finalCapable, hasProducer = false, checkerWithheld = false, canonicalCheckerInert = false, duplicateCheckers = 0, externalCoreChecks = [], reviewStateCandidate }) => {
@@ -495,7 +497,7 @@ const warningLines = ({ customized, finalCapable, hasReviewState = finalCapable,
     } else if (inert && hasProducer) {
       lines.push('    it is also INERT as declared: a gate DOES produce the lcov, but it runs AFTER this entry, so this checker reads nothing (or stale bytes) and passes while verifying nothing — a checker belongs LAST, after its producer.');
     } else if (inert) {
-      lines.push(`    it is also INERT as declared: no declared gate PRODUCES the lcov it reads, so it passes while verifying nothing — declare the suite gate: node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths>`);
+      lines.push(`    it is also INERT as declared: no declared gate PRODUCES the lcov it reads, so it passes while verifying nothing — declare the suite gate: node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths> — ${MARKER_LANE}`);
     }
   }
   if (externalCoreChecks.length) {
@@ -506,12 +508,14 @@ const warningLines = ({ customized, finalCapable, hasReviewState = finalCapable,
   if (checkerWithheld) {
     lines.push('  WARNING: the canonical coverage-check gate was NOT added — no declared gate would PRODUCE the lcov it reads, and a checker with no producer passes while verifying nothing. Declare the suite gate first, then re-run this migration:');
     lines.push(`    node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths>`);
+    lines.push(`    ${MARKER_LANE}, then re-run this migration`);
   }
   // The CANONICAL checker's inertness only. An external row's is said on the row itself above, with
   // the edit that fits that row — this block would otherwise add a second, contradictory one.
   if (canonicalCheckerInert) {
     lines.push('  WARNING: the DECLARED coverage-check gate is INERT — no declared gate PRODUCES the lcov it reads, so it passes while verifying nothing. Nothing is removed for you; declare the suite gate:');
     lines.push(`    node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths>`);
+    lines.push(`    ${MARKER_LANE}`);
   }
   if (duplicateCheckers > 1) {
     lines.push(`  WARNING: ${duplicateCheckers} declared gates are the canonical coverage checker — run-gates --final accepts EXACTLY ONE, so the result is NOT final-run-capable. Nothing is removed for you; keep a single checker and delete the rest by hand.`);

package/references/scripts/migrate-gates.test.mjs

@@ -122,6 +122,7 @@ describe('migrate-gates — the pure migration plan', () => {
     const preview = formatPreview(analysis, 'APPLY');
     assert.match(preview, /CUSTOMIZED \(untouched\): unit-tests/);
     assert.match(preview, /declare the canonical suite gate by hand/, 'the paste-ready recovery rides along');
+    assert.match(preview, /recovery \(apply by hand[^\n]*"lcovProducer": true/, 'the recovery names the marker as the other lane');
   });
 
   it('adds the coverage-check gate LAST with the RESOLVED quoted path; never a second one', () => {
@@ -143,6 +144,7 @@ describe('migrate-gates — the pure migration plan', () => {
     const preview = formatPreview(analysis, 'APPLY');
     assert.match(preview, /coverage-check/, 'the withheld checker is named');
     assert.match(preview, /produce/i, 'the preview says WHY — no gate produces the lcov it would read');
+    assert.match(preview, /WARNING: the canonical coverage-check gate was NOT added[^\n]*\n[^\n]*\n[^\n]*"lcovProducer": true/, 'the withheld block names the marker as the other lane');
   });
 
   it('an ALREADY-declared checker over no producer is reported INERT, is never removed, and is not final-run-capable', () => {
@@ -154,6 +156,7 @@ describe('migrate-gates — the pure migration plan', () => {
     const preview = formatPreview(analysis, 'APPLY');
     assert.match(preview, /INERT/, 'the inert pair is named');
     assert.match(preview, /--experimental-test-coverage/, 'the paste-ready suite cmd is carried');
+    assert.match(preview, /WARNING: the DECLARED coverage-check gate is INERT[^\n]*\n[^\n]*\n[^\n]*"lcovProducer": true/, 'the inert block names the marker as the other lane');
     assert.doesNotMatch(preview, /already final-run-capable/);
   });
 
@@ -352,6 +355,7 @@ describe('migrate-gates — a VENDORED core check is the tool, from a copy --kit
     const absent = formatPreview(buildMigrationPlan([INSTALLED_REVIEW_STATE, vendored], KIT_TOOLS, PROJECT), 'APPLY');
     assert.match(absent, /no declared gate PRODUCES the lcov/, 'with nothing producing, the old sentence still holds');
     assert.match(absent, /declare the suite gate/);
+    assert.match(absent, /no declared gate PRODUCES the lcov[^\n]*"lcovProducer": true/, 'the INERT row names the marker as the other lane');
   });
 
   it('a mixed declaration renders ONE edit, never a removal and a reorder at once', () => {

package/tools/mcp.mjs

@@ -317,10 +317,12 @@ export const formatResult = (result) => {
     mcpJsonLine(result),
     settingsLine(result),
     ...(result.registration.mcpJson.differs ? [
-      '  the entry standing in .mcp.json now:',
+      result.dryRun ? '  the entry standing in .mcp.json now:' : '  the entry this run replaced in .mcp.json:',
       indented(JSON.stringify(result.registration.mcpJson.existing, null, JSON_INDENT)),
     ] : []),
-    '  the entry this registration declares (re-serialized here; the same structured value goes into the file):',
+    result.dryRun
+      ? '  the entry this registration declares (re-serialized here; the same structured value goes into the file):'
+      : '  the entry now in .mcp.json (re-serialized here; the file holds the same structured value):',
     indented(JSON.stringify(result.registration.entry, null, JSON_INDENT)),
     POSTURE_LINE,
     HIDDEN_MODE_LINE,

package/tools/payload-prune.mjs

@@ -107,7 +107,9 @@ const readTree = (root, entry, reports, directoryOnly = false) => {
   return entries;
 };
 
+// The walk lists a directory before its children, so a kept directory's line covers the directories beneath it.
 const planSubtree = (carried, installed, orphans, reports) => {
+  const keptDirectories = [];
   for (const [path, kind] of installed) {
     if (carried.has(path)) {
       const packageKind = carried.get(path);
@@ -119,7 +121,10 @@ const planSubtree = (carried, installed, orphans, reports) => {
       }
     } else if (kind === 'file') {
       orphans.push(path);
+    } else if (kind === 'directory' && keptDirectories.some((kept) => path.startsWith(`${kept}/`))) {
+      continue;
     } else {
+      if (kind === 'directory') keptDirectories.push(path);
       reports.push({
         ok: true,
         line: `${PREFIX} kept ${path} (a ${kind} the package does not carry — yours to remove by hand)`,