@sabaiway/agent-workflow-kit 1.14.0 → 1.15.0

package/CHANGELOG.md

@@ -4,6 +4,44 @@ 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.
 
+## 1.15.0 — Velocity-profile onboarding (kit)
+
+An opt-in **`/agent-workflow-kit velocity`** mode seeds a fixed, audited **read-only** Claude Code
+allowlist into `.claude/settings.json` so an agent stops idling on approval prompts for routine
+read-only commands while the maintainer is away. It never allowlists `commit`/`push`/`publish`, so a
+direct invocation still ASKs — the only caveat is the trust-posture residual (below), closed by a
+deferred hook.
+
+### Added
+- **`tools/velocity-profile.mjs`** — the pure core (a frozen 18-entry `UNIVERSAL_READONLY_ALLOWLIST`,
+  the `screenAllowlistEntry` read-only screen, the read-only `discoverGateCandidates` gate advisor, and
+  the `validateProfile` drift guard) **plus** the programmatic settings writer + CLI
+  (`[--dry-run | --apply] [--accept-edits] [--cwd <dir>]`). Strict **preflight-then-mutate**:
+  merge-don't-clobber, opt-in `acceptEdits`; refuses an unsafe `permissions.defaultMode`
+  (`bypassPermissions` / any non-`{default,acceptEdits,plan}` mode present in **either** settings file),
+  a symlinked `.claude`, malformed settings JSON, or a non-current deployment stamp on `--apply`. Writes
+  **only** `.claude/settings.json`, never `settings.local.json`.
+- A **`### Mode: velocity`** section + a `## Modes` dispatch entry + a one-line opt-in bootstrap offer
+  in `SKILL.md`.
+- The guarded **`uninstall`** now also reports `permissions.defaultMode`/`permissions.allow` in
+  `.claude/settings.json` **non-committally** (REPORT_ONLY, never auto-removed — the writer stores no
+  ownership marker).
+
+### Honesty
+- This is the family's **first programmatic `.claude/settings.json` writer** — a new writer subsystem
+  with its own tests and teardown reporting, **not** merely an extension of the attribution prose seam.
+- The audited core is **read-only by intent — verified, not assumed** (no mutating command, no inline
+  code execution): build-time probes proved `git grep` (`--open-files-in-pager`) and `sort`
+  (`--compress-program`) give inline code execution; both were dropped (the core is 18, not 20).
+  `git diff`/`log`/`show` are kept with a documented bounded-write (`--output`) residual.
+- A seeded read-only allow entry is a **trust posture, not a sandbox**: Claude Code's settings-level
+  allow rules do not inspect output redirection (`cmd > file`) nor command substitution (`cmd $(…)`),
+  so that residual is surfaced honestly in the consent copy, bounded by `acceptEdits` staying opt-in,
+  and **fully closed only by a deferred PreToolUse hook** (a recorded follow-up). `commit`/`push`/
+  `publish` are never added as allow rules.
+
+Lineage head stays **1.3.0** (no `docs/ai` structural change; no migration). See AD-021.
+
 ## 1.14.0 — Activity procedures: recipe-aware, configurable playbooks
 
 A new read-only **`/agent-workflow-kit procedures <activity>`** advisor turns a bare command like

package/README.md

@@ -223,7 +223,8 @@ command is printed).
 | `/agent-workflow-kit status` | any time | **read-only** view of the whole family: which members (kit / memory / engine / the two bridges) are installed and at what version, and — with a project — what's deployed (`docs/ai`, the version stamps, and whether the AI files are git-ignored for hidden mode). Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit recipes` | any time | **read-only** orchestration advisor: presents four named recipes for composing the bridges into plan → execute → review — **Solo / Reviewed / Council / Delegated** — plans + recommends one for your environment (degrading with a stated reason when a backend isn't ready), and offers the choice. The orchestrator runs it via the bridge skills and **always commits**; the kit never executes a recipe, never runs a subscription CLI, never commits. |
 | `/agent-workflow-kit procedures <activity>` | any time | **read-only** activity-procedures advisor: prints a named activity's ordered steps (`plan-authoring` / `plan-execution`) read **live** from the engine, plus the **resolved recipe per slot** from your hand-edited `docs/ai/orchestration.json` + backend readiness (default Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated). `--override <slot>=<recipe>` adjusts one slot per run. Composes with `recipes`; never writes, never commits, never runs a subscription CLI. |
-| `/agent-workflow-kit uninstall` | opt-in, any time | **guarded teardown** — the inverse of `init` / `setup`. Removes only what's **provably ours** (managed skill dirs + bridge wrappers; in a project, the hidden-mode git-ignore block it added + the pre-commit hook it installed); **never deletes** your `docs/ai` / `AGENTS.md` / settings — for those it prints the exact `rm` commands to run by hand. Always `--dry-run` first; preflight-then-mutate; never commits. |
+| `/agent-workflow-kit uninstall` | opt-in, any time | **guarded teardown** — the inverse of `init` / `setup`. Removes only what's **provably ours** (managed skill dirs + bridge wrappers; in a project, the hidden-mode git-ignore block it added + the pre-commit hook it installed); **never deletes** your `docs/ai` / `AGENTS.md` (prints the exact `rm` to run by hand) or your `.claude/settings.json` (prints an **edit** — remove the attribution key, review any velocity `permissions.*` — never an `rm`). Always `--dry-run` first; preflight-then-mutate; never commits. |
+| `/agent-workflow-kit velocity` | Claude Code · opt-in | **onboarding velocity profile** — seeds a fixed, audited **read-only** allowlist into `.claude/settings.json` so routine read-only commands stop idling on approval prompts while you're away; opt-in `acceptEdits`; plus a **read-only advisory** of likely project gate commands to add by hand. Writes **only** `.claude/settings.json` — **never** allowlists commit/push/publish, never writes `settings.local.json`, never commits. A seeded entry is a **trust posture, not a sandbox** (a redirection/command-substitution residual remains, closed by a deferred hook); a direct commit/push/publish still asks. `--dry-run` first. |
 
 It **never auto-commits** and **never overwrites** an existing `AGENTS.md` without asking.
 

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".
 disable-model-invocation: true
 metadata:
-  version: '1.14.0'
+  version: '1.15.0'
 ---
 
 # agent-workflow-kit
@@ -105,7 +105,8 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
 - **`/agent-workflow-kit status`** — read-only view of the **whole family**: which members (kit / memory / engine / the two bridges) are installed, at what version, and — in a project — what is deployed (`docs/ai`, the version stamps, the hidden-mode fence). Never writes, never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit recipes`** — read-only **orchestration advisor**: present the four recipes (Solo / Reviewed / Council / Delegated) over the bridges' role vocabulary, plan + recommend one for the current environment, and offer the choice. **The orchestrator executes the chosen recipe via the bridge skills and always commits** — the kit only surfaces/selects/plans it; it never executes a recipe, never runs a subscription CLI, never commits.
 - **`/agent-workflow-kit procedures <activity>`** — read-only **activity-procedures advisor**: print the ordered steps of a named activity (`plan-authoring` / `plan-execution`) read **live** from the installed engine (`references/procedures.md`), and the **resolved effective recipe per slot** from the per-project `docs/ai/orchestration.json` (hand-edited, strict JSON) + backend readiness (default = Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated; graceful default vs loud override degradation). A per-run `--override <slot>=<recipe>` overrides one slot. Composes with `recipes` (which stays read-only); never writes, never commits, never runs a subscription CLI.
-- **`/agent-workflow-kit uninstall`** — the **guarded teardown** companion to `init`/`setup`. Removes what they placed — installed skill dirs + the bridge wrappers — and, in a project, reverses the hidden-mode fence + the marker pre-commit hook. **Never deletes user-authored content** (`docs/ai`, `AGENTS.md`, `.claude/settings.json`): it prints the exact commands for you to run by hand. `--dry-run` first, always; preflight-then-mutate; never commits.
+- **`/agent-workflow-kit uninstall`** — the **guarded teardown** companion to `init`/`setup`. Removes what they placed — installed skill dirs + the bridge wrappers — and, in a project, reverses the hidden-mode fence + the marker pre-commit hook. **Never deletes user-authored content**: it prints the exact `rm` for `docs/ai` / `AGENTS.md` and an **edit** for `.claude/settings.json` (the `includeCoAuthoredBy` key + any velocity `permissions.*`), for you to run by hand. `--dry-run` first, always; preflight-then-mutate; never commits.
+- **`/agent-workflow-kit velocity`** — opt-in onboarding **velocity profile**: seed a fixed, audited **read-only** Claude Code allowlist into `.claude/settings.json` so routine read-only commands stop idling on approval prompts; opt-in `acceptEdits`; plus a **read-only advisory** of likely project gate commands to add by hand. **Writes only `.claude/settings.json`, never allowlists commit/push/publish, never writes `settings.local.json`, never commits.** `--dry-run` first.
 
 ### Version status & the two axes — surface this on every invocation
 
@@ -185,7 +186,7 @@ readiness, then **append an actionable recipe recommendation** from the recipe p
     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 **one-line backend-status line** (the shared contract above — same detector, format, invariants, and detector-unavailable skip-with-reason). Then **ask before committing** — never auto-commit.
+11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on what was filled with real data vs left as TODO, then print the **one-line backend-status line** (the shared contract above — same detector, format, invariants, and detector-unavailable skip-with-reason). Then **ask before committing** — never auto-commit. Finally, offer the optional, opt-in **velocity profile** in one line — `/agent-workflow-kit velocity` seeds a read-only allowlist so routine read-only commands stop prompting (*Mode: velocity*); never run it without a yes.
 
 Fill strategy:
 
@@ -317,10 +318,29 @@ It classifies every surface into four classes and acts accordingly:
 
 - **remove** (safe) — an installed skill dir that is **provably ours** (valid manifest, `name`+`kind` match). A dir present but **not provably ours** (`foreign`/`stub`/`invalid`/unreadable) → **STOP**: left untouched **and reported**, while the teardown still removes the members that ARE ours (a not-ours surface is never clobbered, and never blocks removing the rest — the per-item `setup` posture). **Preflight-then-mutate:** if a mutable surface **changed since the dry-run** (a skill no longer ours, a wrapper turned foreign, a hook that lost our marker, a malformed fence), the run **aborts with zero changes**.
 - **reverse** (managed-marker) — a bridge **wrapper symlink that points at our source** (a foreign/non-symlink one → STOP); the hidden-mode **managed fence** (via the existing `--unhide` path — only the fenced lines); a **pre-commit hook carrying our marker** (an unmarked / user hook → left + reported).
-- **KEEP — never deleted** (report-only) — `docs/ai`, `AGENTS.md`, `CLAUDE.md`, `docs/plans`, and the `.claude/settings.json` `includeCoAuthoredBy` edit. The tool **prints the exact `rm` / `git rm --cached` commands**; the **user** runs them. Surface this in plain language; never delete on their behalf.
+- **KEEP — never deleted** (report-only) — `docs/ai`, `AGENTS.md`, `CLAUDE.md`, `docs/plans`, and `.claude/settings.json` (the `includeCoAuthoredBy` edit **and** any `permissions.defaultMode`/`permissions.allow` the velocity profile may have seeded). The tool **prints the exact `rm` / `git rm --cached`** for the docs/entry files and an **edit** instruction for `settings.json` (never an `rm` — it may hold your own settings); the **user** runs them. Surface this in plain language; never delete on their behalf.
 
 **Shared globals:** removing `agent-workflow-memory` / `agent-workflow-engine` / a bridge removes a **global** skill that another project on the machine may use — say so before applying. **Windows:** the wrappers are POSIX; the skill-dir + project arms still work, the wrapper arm reports *use WSL*.
 
+### Mode: velocity
+
+The opt-in onboarding **velocity profile** — it seeds a fixed, audited **read-only** Claude Code allowlist into `.claude/settings.json` so an agent stops idling on approval prompts for routine read-only commands while the maintainer is away. It is the family's **first programmatic `.claude/settings.json` writer** (attribution stayed an agent-driven prose merge). **In-agent, opt-in, writes only `.claude/settings.json`**, on one hard rule: **it never allowlists `commit`/`push`/`publish`** — so a direct commit/push/publish still ASKs; the only caveat is the trust-posture residual (below), closed by the deferred hook.
+
+**Version-status routing (like the other writer modes):** read `docs/ai/.workflow-version` first — not-deployed → bootstrap; stamp < `1.3.0` → `upgrade`; stamp > head / unparseable → STOP. The tool enforces this in code too (`--apply` STOPs unless the stamp is the lineage head).
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/velocity-profile.mjs [--dry-run | --apply] [--accept-edits] [--cwd <dir>]`:
+
+1. **`--dry-run` first, always** (the default — changes nothing). It prints: the fixed read-only core it would add; a **read-only advisory** that lists your `package.json` `scripts` as **unaudited candidates you may add BY HAND** (inspect each first) to `.claude/settings.json` / `settings.local.json` — the tool **never** writes them and flags obviously-mutating names as "do not add"; any **pre-existing non-read-only `Bash(...)` entries** to consider removing by hand; and the honest residual notice (below). It STOPs (zero writes) on a symlinked `.claude` / non-regular `settings.json`, malformed settings JSON, or an unsafe `permissions.defaultMode` — `bypassPermissions` or anything outside `default`/`acceptEdits`/`plan`, present in **either** `settings.json` or `settings.local.json`.
+2. **Ask the `acceptEdits` opt-in** via **`AskUserQuestion` where supported**, the safe option FIRST:
+   - **"Keep per-edit approval prompts (recommended)"** — seed only the read-only allowlist; file edits still prompt.
+   - **"Auto-accept file edits (`defaultMode: acceptEdits`)"** — present the honest FULL posture: it auto-applies Edit/Write AND auto-runs `mkdir`/`touch`/`mv`/`cp` in the working dir, is paired with the read-only allowlist, and — stated plainly — a settings-level allow rule is a **trust posture, not a sandbox**: a read-only entry can still write a file via output redirection, and (Claude Code's allow rules do not inspect command substitution) could in principle run another command via `cmd $(…)`. velocity **never adds `commit`/`push`/`publish` as allow rules** — so a direct `git push` still ASKs — but that same redirection/substitution residual means they are not *fully* closed until the deferred PreToolUse hook (family backlog). Note also that a `defaultMode` in `settings.local.json` would override this project-level write (local > project), since velocity writes only `.claude/settings.json`.
+3. **Only on an explicit yes**, re-run with `--apply` (add `--accept-edits` only if they chose the second option). It merges-don't-clobber (preserves `includeCoAuthoredBy`, every key, and existing allow entries) and writes **only** `.claude/settings.json`.
+4. **Surface delegation-readiness, read-only.** If they want a step run Delegated, point them at the hand-edited `docs/ai/orchestration.json` (*Mode: procedures*); the tool never writes it.
+
+**Invariants:** creates `.claude/` if absent and writes **only** `.claude/settings.json` (no other file); **never** allowlists commit/push/publish; **never** writes `settings.local.json`; never commits; opt-in `acceptEdits`, never silent.
+
+**Exit codes:** `0` done / dry-run; `1` a precondition STOP (stamp not current, unsafe mode, malformed settings, symlinked `.claude` / non-regular target); `2` bad arguments.
+
 ---
 
 ## Gotchas
@@ -337,7 +357,7 @@ The non-obvious traps — scan these before bootstrapping or upgrading. Each is
 - **Conversational language never translates artifacts.** It governs *dialogue only*. Code, identifiers, paths, commands, log output, abbreviations, and every deployed `docs/ai/` / `AGENTS.md` file stay in their source language. See [Communication contract](references/contracts.md#communication-contract).
 - **Never auto-commit.** Report quality-gate results and wait for explicit approval — in both modes.
 - **Never leak kit internals to the user.** No ADR ids, tool / function / operation names (`reconcile`, `inject`, `ensureSlot`), marker / slot / fragment / anchor terminology, or verbatim tool stderr in anything the user reads. Translate every tool outcome into plain language a third-party user — who has never read this `SKILL.md` — can understand and act on (e.g. the cap-refusal report in *Mode: upgrade* step 3).
-- **Uninstall never deletes user-authored content, and dry-runs first.** `/agent-workflow-kit uninstall` removes only what is **provably ours** (a managed skill dir / wrapper symlink / fenced block / marker hook) and **prints — never runs** the `rm` / `git rm --cached` for `docs/ai`, the entry-point docs, and `.claude/settings.json`. Always run `--dry-run` first, show the plan, get consent, then `--yes`. A skill dir or symlink that is not provably ours is a STOP, never a clobber (the `setup` posture, inverted). Removing a shared global (memory/engine/a bridge) may affect another project — say so.
+- **Uninstall never deletes user-authored content, and dry-runs first.** `/agent-workflow-kit uninstall` removes only what is **provably ours** (a managed skill dir / wrapper symlink / fenced block / marker hook) and **prints — never runs** the `rm` / `git rm --cached` for `docs/ai` and the entry-point docs, and an **edit** instruction (not an `rm`) for `.claude/settings.json`. Always run `--dry-run` first, show the plan, get consent, then `--yes`. A skill dir or symlink that is not provably ours is a STOP, never a clobber (the `setup` posture, inverted). Removing a shared global (memory/engine/a bridge) may affect another project — say so.
 
 ---
 

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.14.0",
+  "version": "1.15.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/tools/uninstall.mjs

@@ -5,8 +5,9 @@
 // family-registry (the SKILL axis) + surveyProject (the DEPLOY axis) and classifies every surface it
 // could touch into one of four classes, then mutates ONLY after preflighting all of them (AD-011:
 // a conflict on a later item leaves the filesystem untouched). The hard rule: it NEVER deletes
-// user-authored content (docs/ai, the entry-point docs, settings.json) — it only PRINTS the exact
-// commands for the user to run by hand (the AD-014 tracked-file posture, generalized to teardown).
+// user-authored content — it PRINTS the exact remove commands for docs/ai + the entry-point docs, and
+// an EDIT instruction for .claude/settings.json (never an rm), for the user to run by hand (the
+// AD-014 tracked-file posture, generalized to teardown).
 //
 //   safe-remove    — kit-placed + provably ours: a family skill dir (valid manifest, name+kind match).
 //   managed-marker — recognized by an OWNED marker: a wrapper symlink that points at our source, the
@@ -193,8 +194,15 @@ export const buildPlan = ({ family, project = null, projectDir = null, member =
         return null;
       }
     })();
-    if (settings != null && settings.includes('includeCoAuthoredBy')) {
-      items.push({ surface: 'settings', path: settingsPath, class: REPORT_ONLY, reason: 'we set "includeCoAuthoredBy": false here — review/remove that key by hand (the file may hold your own settings)' });
+    const settingsSeams = detectSettingsSeams(settings);
+    if (settingsSeams.attribution || settingsSeams.permissions) {
+      items.push({
+        surface: 'settings',
+        path: settingsPath,
+        class: REPORT_ONLY,
+        reason: settingsSeamReason(settingsSeams),
+        hand: settingsSeamHand(settingsSeams, settingsPath),
+      });
     }
 
     for (const rel of REPORT_PATHS) {
@@ -306,12 +314,51 @@ const CLASS_LABEL = { [SAFE_REMOVE]: 'remove', [MANAGED_MARKER]: 'reverse', [REP
 // or shell metacharacters can't misbehave when the user pastes it (codex #4).
 const shq = (p) => `'${String(p).replace(/'/g, "'\\''")}'`;
 
-// The "do this by hand" line for a report-only surface. settings.json is an EDIT (remove one key), not
-// an `rm` — deleting it would lose the user's own settings (codex #4); everything else is a quoted rm.
+// Detect the two settings.json seams the family may have written: the attribution edit
+// (`includeCoAuthoredBy`) and the velocity profile (`permissions.defaultMode` / `permissions.allow`).
+// Parse when possible (accurate); on malformed JSON fall back to a substring probe for the attribution
+// key so it is still surfaced (no silent miss). The velocity writer stores NO ownership marker, so the
+// permissions seam is reported NON-COMMITTALLY — never a false ownership claim, never auto-removed.
+const detectSettingsSeams = (settings) => {
+  if (settings == null) return { attribution: false, permissions: false };
+  const parsed = (() => { try { return JSON.parse(settings); } catch { return null; } })();
+  if (parsed == null || typeof parsed !== 'object') {
+    // Malformed / JSONC settings.json (comments, trailing commas) — probe both seams by substring so
+    // neither is silently missed (over-reporting REPORT_ONLY is safe; it is never auto-removed).
+    return {
+      attribution: settings.includes('includeCoAuthoredBy'),
+      permissions: settings.includes('"permissions"') && (settings.includes('"defaultMode"') || settings.includes('"allow"')),
+    };
+  }
+  const perms = parsed.permissions;
+  const permissions = perms != null && typeof perms === 'object'
+    && (Object.prototype.hasOwnProperty.call(perms, 'defaultMode') || Object.prototype.hasOwnProperty.call(perms, 'allow'));
+  return { attribution: Object.prototype.hasOwnProperty.call(parsed, 'includeCoAuthoredBy'), permissions };
+};
+
+const ATTRIBUTION_REASON = 'we set "includeCoAuthoredBy": false here — review/remove that key by hand (the file may hold your own settings)';
+const PERMISSIONS_REASON = 'a "permissions.defaultMode" and/or "permissions.allow" key is present in this file — if the velocity profile seeded them, review/remove by hand (no ownership marker is stored); otherwise leave them';
+
+const settingsSeamReason = (seams) =>
+  seams.attribution && seams.permissions ? `${ATTRIBUTION_REASON}. Also: ${PERMISSIONS_REASON}`
+    : seams.permissions ? PERMISSIONS_REASON
+      : ATTRIBUTION_REASON;
+
+const settingsSeamHand = (seams, p) =>
+  seams.attribution && seams.permissions
+    ? `edit ${shq(p)} → remove the "includeCoAuthoredBy" entry and review "permissions.defaultMode"/"permissions.allow" (if the velocity profile seeded them) — keep the rest of your settings`
+    : seams.permissions
+      ? `edit ${shq(p)} → if the velocity profile seeded "permissions.defaultMode"/"permissions.allow", review/remove them by hand (keep the rest of your settings)`
+      : `edit ${shq(p)} → remove the "includeCoAuthoredBy" entry (keep the rest of your settings)`;
+
+// The "do this by hand" line for a report-only surface. A settings.json item carries its own `hand`
+// guidance (an EDIT, never an `rm` — deleting it would lose the user's own settings, codex #4);
+// everything else is a quoted rm. The fallback preserves the attribution wording for a bare item.
 const handGuidance = (item) =>
-  item.surface === 'settings'
+  item.hand ??
+  (item.surface === 'settings'
     ? `edit ${shq(item.path)} → remove the "includeCoAuthoredBy" entry (keep the rest of your settings)`
-    : `rm -rf ${shq(item.path)}   # if it was committed:  git rm -r --cached ${shq(item.path)}`;
+    : `rm -rf ${shq(item.path)}   # if it was committed:  git rm -r --cached ${shq(item.path)}`);
 
 export const formatPlan = (plan) => {
   const lines = ['agent-workflow uninstall — planned actions (nothing is changed without --yes)', ''];
@@ -379,8 +426,9 @@ Usage:
   --yes        apply the auto-removable set (skill dirs + wrappers + fence + marker hook)
   --help       this help
 
-It NEVER deletes user-authored content (docs/ai, AGENTS.md, settings.json) — those are reported with
-the exact commands for you to run by hand. A skill dir that is not provably ours is left untouched.`;
+It NEVER deletes user-authored content — docs/ai and the entry-point docs are reported with the exact
+rm commands for you to run, and .claude/settings.json with an EDIT instruction (remove the attribution
+key; review any velocity permissions.*), never an rm. A skill dir not provably ours is left untouched.`;
 
 const main = (argv) => {
   const args = parseArgs(argv);

package/tools/uninstall.test.mjs

@@ -163,6 +163,35 @@ describe('buildPlan — project deploy axis', () => {
     assert.equal(settings.class, REPORT_ONLY);
   });
 
+  it('reports velocity permissions.* in settings.json NON-COMMITTALLY (never auto-removed)', () => {
+    const fs = projectFs({ files: { [join(dir, '.claude/settings.json')]: JSON.stringify({ permissions: { defaultMode: 'acceptEdits', allow: ['Bash(git status:*)'] } }) } });
+    const plan = buildPlan({ family: [], project, projectDir: dir }, fs);
+    const settings = plan.items.find((i) => i.surface === 'settings');
+    assert.equal(settings.class, REPORT_ONLY);
+    assert.match(settings.reason, /velocity profile seeded them/);
+    assert.doesNotMatch(settings.reason, /includeCoAuthoredBy/);
+    const out = formatPlan(plan);
+    assert.match(out, /permissions\.defaultMode/);
+    assert.ok(!/rm -rf .*settings\.json/.test(out), 'settings.json is never rm-ed');
+  });
+
+  it('reports BOTH the attribution edit and velocity permissions when both are present', () => {
+    const fs = projectFs({ files: { [join(dir, '.claude/settings.json')]: JSON.stringify({ includeCoAuthoredBy: false, permissions: { allow: ['Bash(cat:*)'] } }) } });
+    const settings = buildPlan({ family: [], project, projectDir: dir }, fs).items.find((i) => i.surface === 'settings');
+    assert.equal(settings.class, REPORT_ONLY);
+    assert.match(settings.reason, /includeCoAuthoredBy/);
+    assert.match(settings.reason, /permissions\.(defaultMode|allow)/);
+  });
+
+  it('falls back to a substring probe on malformed settings JSON (no silent miss of either seam)', () => {
+    const broken = '{ "includeCoAuthoredBy": false, "permissions": { "allow": ["Bash(ls:*)"] },, }'; // double comma → JSON.parse throws
+    const fs = projectFs({ files: { [join(dir, '.claude/settings.json')]: broken } });
+    const settings = buildPlan({ family: [], project, projectDir: dir }, fs).items.find((i) => i.surface === 'settings');
+    assert.equal(settings.class, REPORT_ONLY);
+    assert.match(settings.reason, /includeCoAuthoredBy/);
+    assert.match(settings.reason, /permissions/);
+  });
+
   it('reports docs/ai, AGENTS.md, CLAUDE.md, docs/plans as never-deleted', () => {
     const fs = projectFs({ files: { [join(dir, 'AGENTS.md')]: 'x', [join(dir, 'CLAUDE.md')]: 'x' } });
     const docs = buildPlan({ family: [], project, projectDir: dir }, fs).items.filter((i) => i.surface === 'docs');