@warnyin/sdlc 0.1.2 → 0.2.1

package/CHANGELOG.md

@@ -1,19 +1,66 @@
-# Changelog
-
-## 0.1.0 (2026-08-20)
-
-Initial release — the full Day-1 SDLC loop:
-
-- CLI: `init` (multi-tool: claude/cursor/windsurf/copilot/cline/gemini/agents-md),
-  `update` (ownership-aware refresh + guarded prune), `validate`, `status`,
-  `observe`, `archive`.
-- Artifact model: constitution (≤30) + steering with inclusion modes + harness
-  (routing/triage/autonomy policy) + living specs + delta-based changes
-  (vibe/standard/deep caps 40/100/150) + contracts (tests ≤60, evals ≤40).
-- Managed Claude Code hooks: static-context injector, spec write-lock with TTL
-  gates, artifact validator + steering pointers, session token/cost journaling,
-  compact-event tracking.
-- 13 stage playbooks + 13 `/sdlc:*` commands + 3 background skills + 8 agents
-  with model routing (cheap/balanced/deepest).
-- Observability: per-change tokens/cost, first-pass rate, lead time, dead
-  steering and residency flags; post-ship learner loop (distill, never bloat).
+# Changelog
+
+## 0.2.1 (2026-08-20)
+
+- **Fix**: `archive` failed with `ENOENT` on the first change a repo ever ships.
+  `init` scaffolds `sdlc/changes/archive/`, but git does not track empty
+  directories, so the folder is absent for everyone who clones before that first
+  ship. The rename is now preceded by a `mkdir -p` of the archive root.
+
+  The failure landed mid-phase-2, after the delta had been merged into the living
+  specs, evals promoted, `status: shipped` stamped and the ship event journalled —
+  a repo left half-shipped while the CLI reported total failure. The directory is
+  now prepared next to the other destination checks, before phase 1 computes a
+  single merge, so an unusable archive path aborts with the specs untouched.
+
+## 0.2.0 (2026-08-20)
+
+`init` is now an installer you can actually see working — still zero dependencies.
+
+- **Interactive tool picker**: a searchable checkbox list replaces the
+  comma-separated typing prompt. Arrows move, `space` toggles, typing filters,
+  `ctrl+a` selects everything on screen, `enter` confirms, `ctrl+c` cancels
+  without installing anything.
+- **Tool detection**: tools the project already uses (`.claude/`, `.cursor/`,
+  `AGENTS.md`, …) come pre-selected; an empty project still defaults to claude.
+- **Post-install summary**: artifact counts, the adapter path per tool, a
+  written/unchanged/refreshed/kept tally, and Getting-started hints that differ
+  per tool (slash commands for Claude Code, prose for the rest).
+- **Colour** gated on `NO_COLOR` > `FORCE_COLOR` > TTY, with an ASCII glyph
+  fallback for legacy Windows consoles.
+- `--tool` accepts `all` and `none`; `--tools` is an alias. An empty `--tool`,
+  an unknown tool, or `all` mixed with a named tool now fails loudly.
+- **Fix**: `update` read an explicit `tools: []` (what `init --tool none` writes)
+  as "unset" and reinstalled claude. A missing key and a declared-empty one are
+  now distinguished.
+
+## 0.1.2 (2026-08-20)
+
+- Fix: `readStdinJson()` grew a 1s grace timeout — journal and hook utilities no
+  longer hang when stdin is open but idle.
+- Fix: hooks release stdin (pause + unref) so an open-idle stdin cannot keep a
+  hook process alive.
+
+## 0.1.1 (2026-08-20)
+
+- Fix: the entrypoint guard must realpath `process.argv[1]` — npx invokes through
+  a `node_modules/.bin` symlink, which made the CLI a silent no-op.
+- Fix (CI): `node --test` bare discovery; a quoted glob is not expanded on Node 20.
+
+## 0.1.0 (2026-08-20)
+
+Initial release — the full Day-1 SDLC loop:
+
+- CLI: `init` (multi-tool: claude/cursor/windsurf/copilot/cline/gemini/agents-md),
+  `update` (ownership-aware refresh + guarded prune), `validate`, `status`,
+  `observe`, `archive`.
+- Artifact model: constitution (≤30) + steering with inclusion modes + harness
+  (routing/triage/autonomy policy) + living specs + delta-based changes
+  (vibe/standard/deep caps 40/100/150) + contracts (tests ≤60, evals ≤40).
+- Managed Claude Code hooks: static-context injector, spec write-lock with TTL
+  gates, artifact validator + steering pointers, session token/cost journaling,
+  compact-event tracking.
+- 13 stage playbooks + 13 `/sdlc:*` commands + 3 background skills + 8 agents
+  with model routing (cheap/balanced/deepest).
+- Observability: per-change tokens/cost, first-pass rate, lead time, dead
+  steering and residency flags; post-ship learner loop (distill, never bloat).

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 warnyin
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 warnyin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,74 +1,83 @@
-# @warnyin/sdlc
-
-**Spec-driven, AI-driven SDLC for coding agents — token-lean by construction.**
-
-Operationalizes the *"New SDLC with Vibe Coding"* (Day-1) work process: the human configures
-the harness once; the AI drives changes end-to-end through contract-first gates; deterministic
-hooks and a validator enforce the rules; a journal prices every change in real tokens.
-
-Inspired by OpenSpec (delta specs, archive lifecycle), spec-kit (artifact grammar), and
-Kiro (steering + enforced hooks) — tuned for minimum context residency.
-
-## Install
-
-```bash
-cd your-project
-npx @warnyin/sdlc init          # pick tools: claude, cursor, windsurf, copilot, cline, gemini, agents-md
-```
-
-Then in your coding agent:
-
-```
-/sdlc:init                      # interview → constitution + harness (the one human gate)
-/sdlc:auto Add rate limiting    # AI runs new → contract → build → verify → ship
-```
-
-## How it works
-
-```
-sdlc/
-├── context/constitution.md   ≤30 lines — the ONLY always-loaded prose (hook-injected)
-├── context/steering/*.md     scoped knowledge · inclusion: always|paths|manual|agent
-├── harness.md                tools, model routing, tier triage, autonomy policy
-├── specs/<capability>/       living specs — WHEN/THEN SHALL, merged mechanically at ship
-├── changes/<id>/             one change: change.md (Why+Delta+Tasks) + contract/ + journal
-└── changes/archive/          shipped changes + digests (the async human touchpoint)
-```
-
-- **Contract-first**: tests + evals are written *before* code and gate everything after.
-- **AI-driven, exception-only humans**: the autonomy policy in `harness.md` decides what
-  auto-ships and what escalates (hard-floor: security/payments/data-loss/irreversible).
-- **Managed hooks** (Claude Code): SessionStart injects ≤60 lines of static context;
-  PreToolUse write-locks living specs; PostToolUse validates caps and points at steering;
-  Stop journals real token usage. Other tools get the same rules as prose + the validator.
-- **Self-improving, leaner over time**: a post-ship learner proposes rules with evidence;
-  the always-loaded budget is fixed, so learning must distill, not accumulate.
-- **Measured**: `npx @warnyin/sdlc observe` — tokens/cost per change, first-pass rate,
-  lead time, dead steering, context-overflow flags.
-
-## CLI
-
-```
-warnyin-sdlc init [--tool ...]      scaffold + adapters + hooks
-warnyin-sdlc update [--force]       refresh payload, guarded prune of stale files
-warnyin-sdlc validate [id] [--strict]
-warnyin-sdlc status | observe [--json]
-warnyin-sdlc archive <id>           merge deltas into living specs + archive
-```
-
-## Commands (in your agent)
-
-`/sdlc:init` · `/sdlc:auto` · `/sdlc:new` · `/sdlc:design` · `/sdlc:contract` · `/sdlc:build`
-· `/sdlc:verify` · `/sdlc:review` · `/sdlc:ship` · `/sdlc:observe` · `/sdlc:converge`
-· `/sdlc:steer` · `/sdlc:next`
-
-Playbooks live in `sdlc/.playbook/` — behavior is defined once there; commands are thin pointers.
-
-## Development
-
-Zero dependencies, Node ≥ 20. `npm test` runs the black-box suite (temp dirs, real CLI spawns).
-This repo self-hosts: its own development flows through `sdlc/changes/`. After cloning, run
-`npm run setup:dogfood` to regenerate the installer-owned mirrors (`sdlc/.playbook/`,
-`sdlc/.hooks/`, `.claude/`).
-
-MIT
+# @warnyin/sdlc
+
+**Spec-driven, AI-driven SDLC for coding agents — token-lean by construction.**
+
+Operationalizes the *"New SDLC with Vibe Coding"* (Day-1) work process: the human configures
+the harness once; the AI drives changes end-to-end through contract-first gates; deterministic
+hooks and a validator enforce the rules; a journal prices every change in real tokens.
+
+Inspired by OpenSpec (delta specs, archive lifecycle), spec-kit (artifact grammar), and
+Kiro (steering + enforced hooks) — tuned for minimum context residency.
+
+## Install
+
+```bash
+cd your-project
+npx @warnyin/sdlc init          # interactive picker; tools already in the project are pre-selected
+```
+
+The picker is a checkbox list — arrows move, `space` toggles, typing filters, `ctrl+a` selects
+everything on screen, `enter` confirms. Skip it in CI or scripts:
+
+```bash
+npx @warnyin/sdlc init --tool claude,cursor   # explicit list
+npx @warnyin/sdlc init --tool all             # every supported tool
+npx @warnyin/sdlc init --tool none            # sdlc/ framework only, no agent adapters
+```
+
+Then in your coding agent:
+
+```
+/sdlc:init                      # interview → constitution + harness (the one human gate)
+/sdlc:auto Add rate limiting    # AI runs new → contract → build → verify → ship
+```
+
+## How it works
+
+```
+sdlc/
+├── context/constitution.md   ≤30 lines — the ONLY always-loaded prose (hook-injected)
+├── context/steering/*.md     scoped knowledge · inclusion: always|paths|manual|agent
+├── harness.md                tools, model routing, tier triage, autonomy policy
+├── specs/<capability>/       living specs — WHEN/THEN SHALL, merged mechanically at ship
+├── changes/<id>/             one change: change.md (Why+Delta+Tasks) + contract/ + journal
+└── changes/archive/          shipped changes + digests (the async human touchpoint)
+```
+
+- **Contract-first**: tests + evals are written *before* code and gate everything after.
+- **AI-driven, exception-only humans**: the autonomy policy in `harness.md` decides what
+  auto-ships and what escalates (hard-floor: security/payments/data-loss/irreversible).
+- **Managed hooks** (Claude Code): SessionStart injects ≤60 lines of static context;
+  PreToolUse write-locks living specs; PostToolUse validates caps and points at steering;
+  Stop journals real token usage. Other tools get the same rules as prose + the validator.
+- **Self-improving, leaner over time**: a post-ship learner proposes rules with evidence;
+  the always-loaded budget is fixed, so learning must distill, not accumulate.
+- **Measured**: `npx @warnyin/sdlc observe` — tokens/cost per change, first-pass rate,
+  lead time, dead steering, context-overflow flags.
+
+## CLI
+
+```
+warnyin-sdlc init [--tool all|none|a,b]   scaffold + adapters + hooks (picker when omitted)
+warnyin-sdlc update [--force]       refresh payload, guarded prune of stale files
+warnyin-sdlc validate [id] [--strict]
+warnyin-sdlc status | observe [--json]
+warnyin-sdlc archive <id>           merge deltas into living specs + archive
+```
+
+## Commands (in your agent)
+
+`/sdlc:init` · `/sdlc:auto` · `/sdlc:new` · `/sdlc:design` · `/sdlc:contract` · `/sdlc:build`
+· `/sdlc:verify` · `/sdlc:review` · `/sdlc:ship` · `/sdlc:observe` · `/sdlc:converge`
+· `/sdlc:steer` · `/sdlc:next`
+
+Playbooks live in `sdlc/.playbook/` — behavior is defined once there; commands are thin pointers.
+
+## Development
+
+Zero dependencies, Node ≥ 20. `npm test` runs the black-box suite (temp dirs, real CLI spawns).
+This repo self-hosts: its own development flows through `sdlc/changes/`. After cloning, run
+`npm run setup:dogfood` to regenerate the installer-owned mirrors (`sdlc/.playbook/`,
+`sdlc/.hooks/`, `.claude/`).
+
+MIT

package/bin/cli.mjs

@@ -7,7 +7,6 @@ import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import process from 'node:process';
-import readline from 'node:readline';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { parseFrontmatter } from '../lib/frontmatter.mjs';
@@ -17,6 +16,9 @@ import { mergeHookSettings } from '../lib/settings-merge.mjs';
 import { buildReport, renderReport } from '../lib/observe.mjs';
 import { parseManifest, renderManifest, computeStale, containedIn, hasSymlinkSegment, PRUNE_BLAST_CAP } from '../lib/manifest.mjs';
 import { validateAll, formatIssues, listChangeDirs } from '../lib/validate.mjs';
+import { detectTools, toolName } from './detect.mjs';
+import { colorEnabled, createStyle, symbolsFor, summarizeInstall, startHints } from './ui.mjs';
+import { multiSelect } from './multiselect.mjs';
 
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const PAYLOAD = path.join(PKG_ROOT, 'payload');
@@ -43,10 +45,13 @@ export function sha256(content) {
 }
 
 export function parseArgs(argv) {
-  const args = { _: [], tool: null, strict: false, force: false, json: false, help: false };
+  const args = { _: [], tool: null, toolProvided: false, strict: false, force: false, json: false, help: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--tool') args.tool = (argv[++i] ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    if (a === '--tool' || a === '--tools') {
+      args.toolProvided = true;
+      args.tool = (argv[++i] ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    }
     else if (a === '--strict') args.strict = true;
     else if (a === '--force') args.force = true;
     else if (a === '--json') args.json = true;
@@ -69,6 +74,11 @@ function writeFileNormalized(dest, content) {
   return out;
 }
 
+function tally(ctx, outcome) {
+  if (ctx.stats) ctx.stats[outcome] = (ctx.stats[outcome] ?? 0) + 1;
+  return outcome;
+}
+
 export function installFile(projectRoot, destRel, content, ctx) {
   const relPosix = toPosix(destRel);
   const dest = path.join(projectRoot, destRel);
@@ -78,21 +88,21 @@ export function installFile(projectRoot, destRel, content, ctx) {
   if (!fs.existsSync(dest)) {
     writeFileNormalized(dest, next);
     ctx.manifest.set(relPosix, nextHash);
-    return 'written';
+    return tally(ctx, 'written');
   }
   const current = normalizeEol(fs.readFileSync(dest, 'utf8'));
   const currentHash = sha256(current);
   if (currentHash === nextHash) {
     ctx.manifest.set(relPosix, nextHash);
-    return 'current';
+    return tally(ctx, 'current');
   }
   if (ctx.mode === 'update' && ctx.oldManifest?.get(relPosix) === currentHash) {
     writeFileNormalized(dest, next);
     ctx.manifest.set(relPosix, nextHash);
-    return 'updated';
+    return tally(ctx, 'updated');
   }
   ctx.warnings.push(`kept (user-modified): ${relPosix}`);
-  return 'kept';
+  return tally(ctx, 'kept');
 }
 
 function copyTree(srcDir, destDirRel, projectRoot, ctx) {
@@ -218,35 +228,88 @@ export function ensureGitignore(projectRoot) {
 
 // ---------- init ----------
 
-export async function resolveTools(args, { interactive = process.stdin.isTTY && process.stdout.isTTY } = {}) {
-  if (args.tool?.length) {
-    const bad = args.tool.filter((t) => !TOOLS.includes(t));
-    if (bad.length) throw new Error(`unknown tool(s): ${bad.join(', ')} — valid: ${TOOLS.join(', ')}`);
-    return args.tool;
+// `all` / `none` are reserved words, never combinable with a list — mixing
+// them would leave the caller guessing which one won.
+export function resolveToolList(picked) {
+  const reserved = picked.filter((t) => t === 'all' || t === 'none');
+  if (reserved.length && picked.length > 1) {
+    throw new Error(`"${reserved[0]}" cannot be combined with other tools`);
   }
-  if (!interactive) return ['claude'];
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  const answer = await new Promise((resolve) => {
-    rl.question(`Tools to set up [${TOOLS.join(', ')}] (comma-separated, default: claude): `, resolve);
-  });
-  rl.close();
-  const picked = answer.split(',').map((s) => s.trim()).filter(Boolean);
-  if (!picked.length) return ['claude'];
+  if (picked[0] === 'all') return [...TOOLS];
+  if (picked[0] === 'none') return [];
+  if (!picked.length) throw new Error(`--tool requires a value: all, none, or any of ${TOOLS.join(', ')}`);
   const bad = picked.filter((t) => !TOOLS.includes(t));
-  if (bad.length) throw new Error(`unknown tool(s): ${bad.join(', ')}`);
+  if (bad.length) throw new Error(`unknown tool(s): ${bad.join(', ')} — valid: ${TOOLS.join(', ')}, all, none`);
+  return [...new Set(picked)];
+}
+
+export async function resolveTools(args, {
+  interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY),
+  projectRoot = process.cwd(),
+  style = createStyle(false),
+} = {}) {
+  if (args.toolProvided) return resolveToolList(args.tool ?? []);
+  if (!interactive) return ['claude'];
+
+  const detected = detectTools(projectRoot);
+  if (detected.length) {
+    console.log(style.dim(`Detected in this project: ${detected.map(toolName).join(', ')} (pre-selected)`));
+  }
+  const choices = TOOLS.map((tool) => ({
+    value: tool,
+    name: toolName(tool),
+    note: detected.includes(tool) ? 'detected' : '',
+    // First-time setup with nothing detected still needs a sane default.
+    preSelected: detected.length ? detected.includes(tool) : tool === 'claude',
+  }));
+  const picked = await multiSelect({ choices, style, symbols: symbolsFor() });
+  if (picked === null) throw new Error('cancelled — nothing was installed');
   return picked;
 }
 
+function printInitSummary(tools, ctx, style, symbols, { configExisted }) {
+  const s = summarizeInstall(ctx.manifest.keys(), tools);
+  const stats = ctx.stats;
+  const line = (text) => console.log(`  ${text}`);
+
+  console.log('');
+  console.log(`  ${style.green(symbols.tick)} ${style.bold('SDLC Setup Complete')}`);
+  console.log('');
+  line(`Tools: ${tools.length ? tools.map(toolName).join(', ') : style.dim('none (framework only)')}`);
+  if (s.commands || s.skills || s.agents) {
+    line(`${s.commands} commands, ${s.skills} skills and ${s.agents} agents in .claude/`);
+  }
+  for (const a of s.adapters.filter((a) => a.tool !== 'claude')) {
+    line(`Rules for ${toolName(a.tool)}: ${a.path}`);
+  }
+  line(`${s.hooks} hooks in sdlc/.hooks/`);
+  line(`Playbook: sdlc/.playbook/ (${s.playbook} stages + ${s.templates} templates)`);
+  line(`Config: sdlc/config.yaml${configExisted ? ' (kept)' : ''}`);
+  line(style.dim(`Files: ${stats.written} written · ${stats.current} unchanged · ${stats.updated} refreshed · ${stats.kept} kept (yours)`));
+  console.log('');
+  console.log(`  ${style.bold('Getting started:')}`);
+  startHints(tools).forEach((hint, i) => line(`  ${i + 1}. ${hint}`));
+  console.log('');
+}
+
 export async function cmdInit(projectRoot, args) {
-  const tools = await resolveTools(args);
-  const ctx = { mode: 'install', manifest: new Map(), oldManifest: readManifestFile(projectRoot), warnings: [] };
+  const style = createStyle(colorEnabled());
+  const symbols = symbolsFor();
+  const tools = await resolveTools(args, { projectRoot, style });
+  const configExisted = fs.existsSync(path.join(projectRoot, 'sdlc', 'config.yaml'));
+  const ctx = {
+    mode: 'install',
+    manifest: new Map(),
+    oldManifest: readManifestFile(projectRoot),
+    warnings: [],
+    stats: { written: 0, current: 0, updated: 0, kept: 0 },
+  };
   scaffoldSdlc(projectRoot, tools, ctx);
   installToolAdapters(projectRoot, tools, ctx);
   writeManifestFile(projectRoot, ctx.manifest);
   ensureGitignore(projectRoot);
-  for (const w of ctx.warnings) console.warn(`  ${w}`);
-  console.log(`sdlc/ initialized for: ${tools.join(', ')}`);
-  console.log('Next: open your coding agent and run /sdlc:init to write your constitution and harness.');
+  for (const w of ctx.warnings) console.warn(`  ${style.yellow(symbols.warn)} ${w}`);
+  printInitSummary(tools, ctx, style, symbols, { configExisted });
   return { tools };
 }
 
@@ -255,12 +318,17 @@ export async function cmdInit(projectRoot, args) {
 export function cmdUpdate(projectRoot, args) {
   const sdlcRoot = path.join(projectRoot, 'sdlc');
   requireSdlc(sdlcRoot);
-  const config = parseConfig(fs.readFileSync(path.join(sdlcRoot, 'config.yaml'), 'utf8'));
-  const tools = args.tool?.length ? args.tool : (config.tools.length ? config.tools : ['claude']);
+  const configRaw = fs.readFileSync(path.join(sdlcRoot, 'config.yaml'), 'utf8');
+  const config = parseConfig(configRaw);
+  // An explicit `tools: []` (from `init --tool none`) is a decision, not a gap:
+  // only a config that never declared the key at all falls back to claude.
+  const tools = args.toolProvided
+    ? resolveToolList(args.tool ?? [])
+    : (/^tools:/m.test(configRaw) ? config.tools : ['claude']);
 
   // Persist an explicit --tool override so declared and installed state never
   // diverge (otherwise pruning tool-specific files leaves config.yaml stale).
-  if (args.tool?.length) {
+  if (args.toolProvided) {
     const configPath = path.join(sdlcRoot, 'config.yaml');
     const raw = fs.readFileSync(configPath, 'utf8');
     fs.writeFileSync(configPath, raw.replace(/^tools:.*$/m, `tools: [${tools.join(', ')}]`));
@@ -369,6 +437,11 @@ export function cmdArchive(projectRoot, changeId, { strict = true } = {}) {
   // while reporting failure.
   const date = new Date().toISOString().slice(0, 10);
   const destDir = path.join(sdlcRoot, 'changes', 'archive', `${date}-${changeId}`);
+  // `init` scaffolds changes/archive/, but git does not track empty directories:
+  // it is absent for anyone who cloned before the first change shipped. Prepare
+  // it here, with the other destination checks, so a bad archive path fails
+  // while the specs are still untouched instead of ENOENT-ing at the rename.
+  fs.mkdirSync(path.dirname(destDir), { recursive: true });
   if (fs.existsSync(destDir)) {
     throw new Error(`archive target already exists: ${toPosix(path.relative(projectRoot, destDir))} — nothing was merged`);
   }
@@ -438,7 +511,7 @@ const HELP = `@warnyin/sdlc — spec-driven AI-SDLC framework
 
 usage: warnyin-sdlc <command> [options]
 
-  init [--tool claude,cursor,...]   scaffold sdlc/ + adapters + hooks into this project
+  init [--tool all|none|a,b]      scaffold sdlc/ + adapters + hooks (interactive picker when omitted)
   update [--tool ...] [--force]     refresh payload-owned files, prune stale ones (guarded)
   validate [id] [--strict]          structural validation (caps, delta grammar, gates)
   status [--json]                   list active changes and their stage

package/bin/detect.mjs

@@ -0,0 +1,51 @@
+// Which agent tools a project already uses, and where each adapter lands.
+// CLI-only: this must NOT move into lib/, which is copied verbatim into every
+// installed project as sdlc/.hooks/lib/.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// The one user-visible path per tool — detection and the post-install summary
+// both name the same file, so nobody has to guess what `init` touched.
+export const ADAPTER_PATHS = Object.freeze({
+  claude: '.claude/',
+  cursor: '.cursor/rules/sdlc.mdc',
+  windsurf: '.windsurf/rules/sdlc.md',
+  copilot: '.github/copilot-instructions.md',
+  cline: '.clinerules',
+  gemini: 'GEMINI.md',
+  'agents-md': 'AGENTS.md',
+});
+
+export const TOOL_NAMES = Object.freeze({
+  claude: 'Claude Code',
+  cursor: 'Cursor',
+  windsurf: 'Windsurf',
+  copilot: 'GitHub Copilot',
+  cline: 'Cline',
+  gemini: 'Gemini CLI',
+  'agents-md': 'AGENTS.md',
+});
+
+// A tool counts as present when the project already carries its home directory
+// or instruction file. Detection only pre-selects a checkbox — it never
+// installs anything on its own.
+const MARKERS = Object.freeze({
+  claude: ['.claude'],
+  cursor: ['.cursor'],
+  windsurf: ['.windsurf'],
+  copilot: ['.github/copilot-instructions.md'],
+  cline: ['.clinerules'],
+  gemini: ['GEMINI.md', '.gemini'],
+  'agents-md': ['AGENTS.md'],
+});
+
+export function detectTools(projectRoot) {
+  return Object.entries(MARKERS)
+    .filter(([, markers]) => markers.some((m) => fs.existsSync(path.join(projectRoot, ...m.split('/')))))
+    .map(([tool]) => tool);
+}
+
+export function toolName(tool) {
+  return TOOL_NAMES[tool] ?? tool;
+}