@sabaiway/agent-workflow-kit 1.34.0 → 1.36.0

package/tools/set-autonomy.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+// set-autonomy.mjs — the WRITER for docs/ai/autonomy.json (the per-project autonomy policy). Mirrors
+// set-recipe.mjs (AD-044): the AGENT turns plain language into explicit `--set <section>.<key>=<value>`
+// / `--unset <section>.<key>` ops; the KIT does the deterministic validate → merge → preview → write.
+// No NL parser (stays dependency-free + deterministic), no `all`-magic — the agent expands plain
+// language into explicit per-key ops (asking if scope is unclear). Ops route through the SAME
+// accept/reject grammar as validateAutonomy (autonomy-config.mjs), so the writer and the config
+// validator can never disagree.
+//
+// Posture: PREVIEW BY DEFAULT (dry-run); `--write` applies. It NEVER commits, NEVER runs a backend, and
+// NEVER renders enforcement — it writes ONLY docs/ai/autonomy.json (the render into .claude/settings.json
+// is the separate velocity autonomy mode). It writes only via the hardened writeAutonomy (deployment
+// gate; exclusive-create tmp + rename; symlink/TOCTOU-safe; last-writer-wins). A no-op set never writes
+// and never spuriously seeds the _README. `--unset` returns a key to its computed default, so reverting
+// needs no hand-edit either. Hand-edit stays first-class — this is an OFFERED convenience, never a lock.
+//
+// Output is ENGLISH/structured (repo-artifact Hard Constraint); the agent localizes when narrating.
+// Exit codes: 0 success; 2 usage (bad/duplicate op, --write with zero ops); 1 config error
+// (malformed/unreadable policy) or a write STOP (no deployment / symlinked leaf). main(argv, ctx) →
+// { code, stdout, stderr }; cwd / fs are injectable for host-independent tests.
+//
+// Dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
+
+import { readFileSync, lstatSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import {
+  AUTONOMY_REL,
+  fail,
+  loadAutonomy,
+  validateAutonomy,
+  parseAutonomyOp,
+  applyAutonomyOps,
+  serializeAutonomy,
+  resolveAutonomy,
+  AUTONOMY_README,
+} from './autonomy-config.mjs';
+import { writeAutonomy as writeAutonomyFs } from './autonomy-write.mjs';
+
+// ── argument parsing (usage errors → exit 2) ────────────────────────────────────────
+
+// Parse argv → { ops, write, json }. `--set`/`--unset` take a fully-qualified token (parseAutonomyOp
+// validates it). A duplicate op for the same section.key, a `--write` with zero ops, an unknown flag, or
+// a bad token → exit 2. `--set=<tok>` / `--unset=<tok>` inline forms are accepted too.
+const parseArgs = (argv) => {
+  const ops = [];
+  const seen = new Set();
+  let write = false;
+  let json = false;
+  const takeOp = (kind, tok) => {
+    if (tok === undefined || tok.startsWith('--')) throw fail(2, `--${kind} requires <section>.<key>${kind === 'set' ? '=<value>' : ''}`);
+    const op = parseAutonomyOp(kind, tok);
+    const key = `${op.section}.${op.key}`;
+    if (seen.has(key)) throw fail(2, `duplicate op for "${key}" — name each section.key at most once`);
+    seen.add(key);
+    ops.push(op);
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--json') json = true;
+    else if (a === '--write') write = true;
+    else if (a === '--set') { takeOp('set', argv[i + 1]); i += 1; }
+    else if (a === '--unset') { takeOp('unset', argv[i + 1]); i += 1; }
+    else if (a.startsWith('--set=')) takeOp('set', a.slice('--set='.length));
+    else if (a.startsWith('--unset=')) takeOp('unset', a.slice('--unset='.length));
+    else if (a.startsWith('-')) throw fail(2, `unknown flag: ${a}`);
+    else throw fail(2, `unexpected argument: ${a}`);
+  }
+  if (write && ops.length === 0) throw fail(2, 'nothing to write — pass at least one --set/--unset (a bare --write is a no-op)');
+  return { ops, write, json };
+};
+
+// ── per-op before/after + resolved effective value ──────────────────────────────────
+
+// The resolved effective value for a section.key against a resolved policy (computed defaults filled).
+const resolvedValueFor = (resolved, section, key) =>
+  section === 'redlines' ? resolved.redlines[key] : resolved.activities[section]?.[key];
+
+// A single op's before/after value + the effective value it resolves to (the computed default shows for
+// an unset). `to` is null for an unset (falls to the computed default).
+const resolveOp = (op, current, after) => {
+  const from = current?.[op.section]?.[op.key] ?? null;
+  const to = after?.[op.section]?.[op.key] ?? null;
+  const effective = resolvedValueFor(resolveAutonomy(after), op.section, op.key);
+  return { section: op.section, key: op.key, from, to, effective };
+};
+
+// ── rendering (ENGLISH; the agent localizes) ────────────────────────────────────────
+
+const valueLabel = (v) => (v == null ? '(computed default)' : v);
+
+const APPLY_HINT =
+  'Next: render this policy into .claude/settings.json with the velocity autonomy mode (previews first) — the writer changes only the policy file, never the settings.';
+
+const formatHuman = ({ changed, unchanged, wrote, fileBody }) => {
+  const lines = [];
+  if (wrote) lines.push(`wrote ${AUTONOMY_REL}`);
+  else if (changed.length) lines.push('set-autonomy — preview (nothing written; re-run with --write to apply)');
+  for (const e of changed) {
+    lines.push(`  ${e.section}.${e.key}: ${valueLabel(e.from)} → ${valueLabel(e.to)}`);
+    lines.push(`      ↳ effective: ${e.effective}`);
+  }
+  for (const e of unchanged) lines.push(`  ${e.section}.${e.key}: already ${valueLabel(e.from)} (no change)`);
+  if (wrote && fileBody) lines.push('', `${AUTONOMY_REL} now reads:`, fileBody.replace(/\n$/, ''), '', APPLY_HINT);
+  if (!wrote) {
+    if (!changed.length) lines.push('  no changes — nothing to write.');
+    else lines.push('', `would write ${AUTONOMY_REL} — re-run with --write to apply.`);
+  }
+  return lines.join('\n');
+};
+
+const buildJson = ({ changed, unchanged, writtenPath, noop }) => ({
+  changed: changed.map((e) => ({ section: e.section, key: e.key, from: e.from, to: e.to, effective: e.effective })),
+  unchanged: unchanged.map((e) => ({ section: e.section, key: e.key, value: e.from })),
+  writtenPath: writtenPath ?? null,
+  noop,
+});
+
+const HELP = `set-autonomy — write the per-project autonomy policy (docs/ai/autonomy.json).
+
+Usage:
+  node set-autonomy.mjs [--set <section>.<key>=<value>]... [--unset <section>.<key>]... [--write] [--json]
+
+  --set    <section>.<key>=<value>   pin a policy value (fully-qualified; e.g. plan-execution.autonomy=sandbox)
+  --unset  <section>.<key>           return a key to its computed default
+  --write                            apply the change (default: preview only — writes nothing)
+  --json                             machine-readable output
+  --help, -h                         this help
+
+Sections/keys: redlines → commit|push|publish|network|credentials|fs_outside_repo (each ask|deny);
+               plan-authoring.autonomy, plan-execution.autonomy (each sandbox|prompt)
+
+Previews by default; --write applies via an atomic, symlink/TOCTOU-safe write behind a deployment gate.
+Policy writer only: it NEVER renders enforcement (that is the velocity autonomy mode), NEVER runs a
+backend, and NEVER commits. Hand-editing the file stays fully supported.
+
+Exit codes: 0 success; 2 usage (bad/duplicate op, or --write with no ops);
+            1 config error (malformed/unreadable policy) or a write STOP (no deployment / symlinked leaf).`;
+
+// ── main ────────────────────────────────────────────────────────────────────────────
+
+export const main = (argv, ctx = {}) => {
+  const cwd = ctx.cwd ?? process.cwd();
+  const readFile = ctx.readFileSync ?? readFileSync;
+  const lstat = ctx.lstatSync ?? lstatSync;
+  const writeAutonomy = ctx.writeAutonomy ?? writeAutonomyFs;
+  try {
+    if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
+    const { ops, write, json } = parseArgs(argv);
+
+    // Load the current policy first (loadAutonomy throws fail(1) loud on malformed/unreadable — a write
+    // never clobbers an unparseable file; the message points the agent at the parse error to help fix it).
+    const { config: current, source } = loadAutonomy(cwd, readFile, lstat);
+
+    // No ops + no --write → show the current policy + a hint (read-only; nothing changes).
+    if (ops.length === 0) {
+      if (json) {
+        return { code: 0, stdout: JSON.stringify(buildJson({ changed: [], unchanged: [], writtenPath: null, noop: true }), null, 2), stderr: '' };
+      }
+      const shown = current == null ? `(no ${AUTONOMY_REL} yet — computed defaults apply)` : serializeAutonomy(current).replace(/\n$/, '');
+      const hint = `\nPass --set <section>.<key>=<value> (preview) then --write to apply. Sections: redlines, plan-authoring.autonomy, plan-execution.autonomy.`;
+      return { code: 0, stdout: `${source === 'none' ? '' : `${AUTONOMY_REL}:\n`}${shown}${hint}`, stderr: '' };
+    }
+
+    const after = applyAutonomyOps(current, ops, { seedReadme: AUTONOMY_README });
+    const resolved = ops.map((op) => resolveOp(op, current, after));
+    const changed = resolved.filter((e) => e.from !== e.to);
+    const unchanged = resolved.filter((e) => e.from === e.to);
+    const noop = changed.length === 0;
+
+    if (!write || noop) {
+      const stdout = json
+        ? JSON.stringify(buildJson({ changed, unchanged, writtenPath: null, noop }), null, 2)
+        : formatHuman({ changed, unchanged, wrote: false });
+      return { code: 0, stdout, stderr: '' };
+    }
+
+    validateAutonomy(after); // defensive re-validate immediately before the write
+    const { writtenPath } = writeAutonomy(cwd, after, ctx);
+    const fileBody = serializeAutonomy(after);
+    const stdout = json
+      ? JSON.stringify(buildJson({ changed, unchanged, writtenPath, noop: false }), null, 2)
+      : formatHuman({ changed, unchanged, wrote: true, fileBody });
+    return { code: 0, stdout, stderr: '' };
+  } catch (err) {
+    return { code: err.exitCode ?? 1, stdout: '', stderr: `set-autonomy: ${err.message}` };
+  }
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  const r = main(process.argv.slice(2));
+  if (r.stdout) console.log(r.stdout);
+  if (r.stderr) console.error(r.stderr);
+  process.exit(r.code);
+}

package/tools/setup-backends.mjs

@@ -99,6 +99,78 @@ const probeMarker = (file, fs) => {
   }
 };
 
+// ── overwrite honesty (D5) — state what a refresh replaced, never a silent wipe ────────────────────
+
+// The host-level settings surface a refresh NEVER touches — the one place a bridge tweak survives a
+// kit upgrade (bridge CODE stays kit-owned; only these knobs persist). Named wherever a refresh
+// reports overwriting a local edit, so the recovery is always a copy-paste away.
+const SETTINGS_FILE_HINT = '${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf';
+const SETTINGS_CMD_HINT = '/agent-workflow-kit bridge-settings';
+
+// Bundle-owned regular files whose PLACED copy differs from the bundle (a local edit an equal-version
+// refresh would overwrite) or cannot be read (indeterminate — an honest degrade). Mirrors
+// copyTreeRefresh's src dispatch so it flags EXACTLY the files the overwrite touches: a symlink src is
+// additive (copyTreeRefresh skips an existing dest — never overwritten) and a dir recurses; a
+// bundled-only file (no placed copy) is a pure add, no loss. The BUNDLE read is our own shipped
+// artifact — a failure there is a loud corrupt-kit error upstream (never swallowed here); only the
+// PLACED read is caught (EACCES/EIO → 'unreadable', and the refresh still proceeds). Sorted output is
+// deterministic for the stated line. Exported for a direct unit test (the full driver cannot observe a
+// symlinked placed file — copyTreeRefresh refuses to overwrite one, so the refresh fails before any line).
+export const scanBundleOwnedDrift = (bundleDir, skillDir, fs) => {
+  const drifted = [];
+  const unreadable = [];
+  const walk = (rel) => {
+    const src = join(bundleDir, rel);
+    const dest = join(skillDir, rel);
+    const st = fs.lstat(src);
+    if (st.isSymbolicLink()) return;
+    if (st.isDirectory()) {
+      for (const entry of fs.readdir(src)) walk(rel ? join(rel, entry) : entry);
+      return;
+    }
+    // lstat the PLACED path NO-FOLLOW first — never read THROUGH a symlink (copyTreeRefresh's
+    // assertContainedRealPath would refuse to overwrite a symlinked dest, so reading its target here
+    // would be both unsafe and moot). Absent → a bundled-only addition (no local loss); a symlink /
+    // non-regular / unreadable placed node → "could not compare" without a read-through.
+    const destStat = (() => {
+      try {
+        return fs.lstat(dest);
+      } catch (err) {
+        return err && err.code === 'ENOENT' ? 'absent' : 'error';
+      }
+    })();
+    if (destStat === 'absent') return;
+    if (destStat === 'error' || destStat.isSymbolicLink() || !destStat.isFile()) {
+      unreadable.push(rel);
+      return;
+    }
+    const srcBytes = fs.readFile(src);
+    const destBytes = (() => {
+      try {
+        return fs.readFile(dest);
+      } catch {
+        unreadable.push(rel);
+        return null;
+      }
+    })();
+    if (destBytes === null) return;
+    if (!Buffer.from(srcBytes).equals(Buffer.from(destBytes))) drifted.push(rel);
+  };
+  walk('');
+  return { drifted: drifted.sort(), unreadable: unreadable.sort() };
+};
+
+// One user-facing sentence naming what an equal-version re-sync overwrote — or null when nothing local
+// was lost. Callers apply their own indent; the pointer names the settings file that survives a refresh.
+const driftSummary = (drift) => {
+  if (!drift) return null;
+  const parts = [];
+  if (drift.drifted.length) parts.push(`overwrote ${drift.drifted.length} locally-changed file(s): ${drift.drifted.join(', ')}`);
+  if (drift.unreadable.length) parts.push(`could not compare ${drift.unreadable.length} file(s) (kept the bundled copy): ${drift.unreadable.join(', ')}`);
+  if (!parts.length) return null;
+  return `${parts.join('; ')} — bridge code is kit-owned and always refreshed; persist host tweaks in ${SETTINGS_FILE_HINT} (survives every refresh): ${SETTINGS_CMD_HINT}`;
+};
+
 // ── path resolution ──────────────────────────────────────────────────────────
 
 const skillDirOf = (entry, deps) =>
@@ -253,14 +325,26 @@ const assertNoDowngrade = (plan, deps = {}) => {
   if (compareSemver(placed, bundled) === 1) throw stop(downgradeReason(placed, bundled), { skillDir: plan.skillDir, wouldDowngrade: true });
 };
 
+// Copy the bundle over the placed skill dir (the refresh overwrite), FIRST scanning bundle-owned files
+// for local drift so the caller can STATE what the overwrite replaced (D5 — overwrite honesty). Scan
+// only on a refresh: a `place` writes into an absent/empty dir, so there is nothing local to lose. The
+// copy proceeds either way — bridge code is kit-owned. Returns the drift report (null for a place).
+const copyBridgeWithHonesty = (action, bundleDir, skillDir, deps) => {
+  const fs = fsDeps(deps);
+  const drift = action === 'refresh' ? scanBundleOwnedDrift(bundleDir, skillDir, fs) : null;
+  copyTreeRefresh(bundleDir, skillDir, skillDir, fs);
+  return drift;
+};
+
 // Place/refresh the bundled bridge skill. Re-inspects before writing (never trusts a stale plan).
+// Returns the plan plus `drift`: on a refresh, the bundle-owned files whose local edits it overwrote.
 export const placeSkill = (name, deps = {}) => {
   const entry = registryEntry(name);
   if (!entry) throw stop(`unknown backend: ${name}`);
   const plan = inspectSkillDir(entry, deps);
   assertNoDowngrade(plan, deps);
-  copyTreeRefresh(plan.bundleDir, plan.skillDir, plan.skillDir, fsDeps(deps));
-  return plan;
+  const drift = copyBridgeWithHonesty(plan.action, plan.bundleDir, plan.skillDir, deps);
+  return { ...plan, drift };
 };
 
 // Link the wrappers onto `bindir`. PREFLIGHT all (source is a regular non-symlink file inside the
@@ -413,9 +497,12 @@ export const planFor = (backend, deps = {}) => {
 // in the plan across the read→write gap). Throws on a mid-flight conflict / fs error (honest partial
 // failure — placeSkill/chmod/symlink all converge on a re-run, so there is nothing to roll back).
 const applyBackend = (plan, deps) => {
-  if (plan.place.action === 'place' || plan.place.action === 'refresh') placeSkill(plan.name, deps);
+  const placed = (plan.place.action === 'place' || plan.place.action === 'refresh')
+    ? placeSkill(plan.name, deps)
+    : null;
   const manifest = readBundledManifest(plan.place.bundleDir, deps);
   linkWrappers(plan.skillDir, manifest, { ...deps, bindir: plan.bindir, platform: plan.platform });
+  return { drift: placed?.drift ?? null };
 };
 
 // ── formatting ─────────────────────────────────────────────────────────────────
@@ -442,6 +529,11 @@ const formatBackend = (plan, applied) => {
   }
   const placeVerb = applied ? { place: 'placed', refresh: 'refreshed' } : { place: 'will place', refresh: 'will refresh' };
   lines.push(`      • skill: ${placeVerb[plan.place.action]}${versionLabel(plan)} → ${plan.skillDir}`);
+  // Overwrite honesty (D5): on an equal-version re-sync that clobbered a local edit, say so (a version
+  // upgrade's diffs are the version delta — versionLabel's arrow already signals that change).
+  const equalVersionRefresh = plan.place.action === 'refresh' && (!plan.priorVersion || plan.priorVersion === plan.version);
+  const driftLine = equalVersionRefresh ? driftSummary(plan.drift) : null;
+  if (driftLine) lines.push(`      ↳ ${driftLine}`);
   for (const l of plan.links) {
     const verb = l.dstState === 'ours' ? 'already linked' : applied ? 'linked' : 'will link';
     lines.push(`      • wrapper ${l.cmd}: ${verb} → ${l.dst}`);
@@ -463,10 +555,10 @@ const formatBackend = (plan, applied) => {
 // a per-bridge lock file would be new machinery for a user-driven, self-healing race.
 const refreshSkillOnly = (entry, deps = {}) => {
   const fresh = inspectSkillDir(entry, deps);
-  if (fresh.action !== 'refresh') return false;
+  if (fresh.action !== 'refresh') return { refreshed: false, drift: null };
   assertNoDowngrade(fresh, deps);
-  copyTreeRefresh(fresh.bundleDir, fresh.skillDir, fresh.skillDir, fsDeps(deps));
-  return true;
+  const drift = copyBridgeWithHonesty('refresh', fresh.bundleDir, fresh.skillDir, deps);
+  return { refreshed: true, drift };
 };
 
 const NOT_PLACED_LINE = 'skipped — not placed (placement is opt-in: /agent-workflow-kit setup)';
@@ -499,7 +591,8 @@ export const refreshPlacedBridges = (deps = {}, names = KNOWN_BACKENDS.map((b) =
       if (plan.outcome === 'stop' || plan.outcome === 'error') {
         return { name: plan.name, outcome: 'failed', line: `  ${plan.name}: could not refresh — ${stripPrefix(plan.reason)}; recover with /agent-workflow-kit setup` };
       }
-      if (!refreshSkillOnly(registryEntry(plan.name), deps)) {
+      const refresh = refreshSkillOnly(registryEntry(plan.name), deps);
+      if (!refresh.refreshed) {
         return { name: plan.name, outcome: 'not-placed', line: `  ${plan.name}: ${NOT_PLACED_LINE}` };
       }
       const manifest = readBundledManifest(plan.place.bundleDir, deps);
@@ -507,10 +600,14 @@ export const refreshPlacedBridges = (deps = {}, names = KNOWN_BACKENDS.map((b) =
       const current = plan.version !== null && plan.priorVersion === plan.version;
       // The equal-version line still states the copy that ran (repair-on-rerun) — the tool never
       // reports a mutation-free "already current" while it re-synced files underneath.
+      const base = `  ${plan.name}: ${current ? `already current${versionLabel(plan)} — files re-synced from the bundled copy` : `refreshed${versionLabel(plan)}`}`;
+      // Overwrite honesty (D5): only an EQUAL-version re-sync can prove a byte diff is a LOCAL edit —
+      // a version upgrade's diffs are the version delta, which the (vOld → vNew) arrow already states.
+      const summary = current ? driftSummary(refresh.drift) : null;
       return {
         name: plan.name,
         outcome: current ? 'already-current' : 'refreshed',
-        line: `  ${plan.name}: ${current ? `already current${versionLabel(plan)} — files re-synced from the bundled copy` : `refreshed${versionLabel(plan)}`}`,
+        line: summary ? `${base}\n     ↳ ${summary}` : base,
       };
     } catch (err) {
       // A downgrade STOP raised at the write boundary (a newer bridge landed between plan and apply)
@@ -647,7 +744,8 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
     let plan = planFor(name, runDeps);
     if (!args.dryRun && plan.outcome === 'ok') {
       try {
-        applyBackend(plan, runDeps);
+        const { drift } = applyBackend(plan, runDeps);
+        plan = { ...plan, drift };
         appliedOk = true;
       } catch (err) {
         plan = { ...plan, outcome: err.code === SETUP_STOP ? 'stop' : 'error', reason: err.message };