kracked-core 1.0.0 → 1.4.0

package/src/wizard.mjs

@@ -1,7 +1,6 @@
 // Interactive prompt flow for `npx kracked-core init`.
 // Follows the wizard flow in CONTRACT.md exactly — question order matters.
 
-import readline from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -13,7 +12,10 @@ import {
   classifyProjectDir,
   scanExistingProject,
   stackSummaryLine,
+  detectExistingAgentSetup,
+  sanitizeScanned,
 } from './detect.mjs';
+import { select, checkbox, confirm, input } from './prompt.mjs';
 import {
   writeGlobalMemory,
   registerProject,
@@ -37,6 +39,31 @@ function isoDate() {
   return new Date().toISOString().slice(0, 10);
 }
 
+// Installing into these scatters loader files across the filesystem, and
+// installing into the home dir makes `<project>/.kracked` collide with global
+// memory. A typo like `/` should not silently create a tree.
+const FORBIDDEN_DIRS = ['/', '/etc', '/usr', '/bin', '/sbin', '/var', '/System', '/Library'];
+
+/**
+ * Refuse obviously wrong install targets before anything is written.
+ * Returns an error string, or null when the path is fine.
+ */
+function rejectUnsafeProjectDir(dir) {
+  const resolved = path.resolve(dir);
+
+  if (FORBIDDEN_DIRS.includes(resolved)) {
+    return `${resolved} is a system directory — pick a project folder instead.`;
+  }
+  if (resolved === path.resolve(os.homedir())) {
+    return (
+      'That\'s your home directory. Installing here would put loader files loose in\n' +
+      '  your home folder and collide with global memory at ~/.kracked.\n' +
+      '  Make a project folder first, then run this inside it.'
+    );
+  }
+  return null;
+}
+
 /**
  * Turn detected package.json scripts into a ready-to-read "how to run it" block.
  * The scan already knows these commands — writing them into project.md is the
@@ -68,87 +95,91 @@ export async function runInit() {
     return;
   }
 
-  const rl = readline.createInterface({ input: stdin, output: stdout });
-
-  let interrupted = false;
+  // Ctrl+C / Ctrl+D are handled inside prompt.mjs, which owns stdin in raw
+  // mode. Keep a SIGINT guard for interrupts arriving between prompts.
   const onSigint = () => {
-    interrupted = true;
     stdout.write('\n\nCancelled. Nothing after this point was written.\n');
-    rl.close();
     process.exit(130);
   };
   process.on('SIGINT', onSigint);
 
   try {
-    await wizardFlow(rl);
-  } catch (err) {
-    // Ctrl+D (EOF) mid-question surfaces as readline's AbortError. Treat it
-    // the same as Ctrl+C — a clean cancel, not a crash with a scary stack.
-    if (err.code === 'ABORT_ERR' || /ctrl\+d/i.test(err.message || '')) {
-      stdout.write('\n\nCancelled. Nothing after this point was written.\n');
-      process.exitCode = 130;
-      return;
-    }
-    throw err;
+    await wizardFlow();
   } finally {
     process.off('SIGINT', onSigint);
-    if (!interrupted) rl.close();
+    stdin.pause();
   }
 }
 
-/** Ask a question with a default; Enter alone accepts the default. */
-async function ask(rl, question, defaultValue) {
-  const suffix = defaultValue ? ` [${defaultValue}]` : '';
-  const answer = (await rl.question(`${question}${suffix} `)).trim();
-  return answer === '' ? defaultValue : answer;
+/** Prompt for how to resolve a file-already-exists conflict. */
+async function askConflict(destPath) {
+  stdout.write(`\n  Already exists: ${destPath}\n`);
+  return select(
+    '  What should we do?',
+    [
+      { label: 'Skip', value: 'skip', hint: 'keep the existing file' },
+      { label: 'Overwrite', value: 'overwrite', hint: 'replace it' },
+      { label: 'Write alongside', value: 'alongside', hint: 'save as .kracked-new' },
+    ],
+    0
+  );
 }
 
-/** Ask a yes/no question. Returns boolean. Default shown as Y/n or y/N. */
-async function askYesNo(rl, question, defaultYes) {
-  const suffix = defaultYes ? '[Y/n]' : '[y/N]';
-  const answer = (await rl.question(`${question} ${suffix} `)).trim().toLowerCase();
-  if (answer === '') return defaultYes;
-  return answer === 'y' || answer === 'yes';
+/**
+ * Warn before writing into a directory another agent system already governs.
+ * A CLAUDE.md we didn't write belongs to someone else's setup — overwriting it
+ * silently replaces that agent's identity. Ask first, every time.
+ */
+async function warnOnExistingSetup(projectDir) {
+  const found = detectExistingAgentSetup(projectDir).filter((f) => !f.ours);
+  if (found.length === 0) return true;
+
+  stdout.write('\n  Heads up — this looks like it already has an agent setup:\n');
+  for (const f of found) {
+    const where = f.scope === 'global' ? 'global' : 'this project';
+    stdout.write(`    • ${f.file}  ${c_dim(`(${where})`)}\n`);
+  }
+  stdout.write(
+    '\n  Installing here would overwrite those loaders and change who your\n' +
+    '  agent is in this directory. Existing files are never replaced without\n' +
+    '  asking, but it is easy to end up with two systems giving different\n' +
+    '  instructions.\n\n'
+  );
+
+  return confirm('Continue installing here?', false);
 }
 
-/** Prompt for how to resolve a file-already-exists conflict. */
-async function askConflict(rl, destPath) {
-  stdout.write(`\n  Already exists: ${destPath}\n`);
-  const answer = (
-    await rl.question('  skip / overwrite / write alongside as .kracked-new? [skip] ')
-  ).trim().toLowerCase();
-
-  if (answer === 'o' || answer === 'overwrite') return 'overwrite';
-  if (answer === 'a' || answer === 'alongside' || answer === 'write alongside') return 'alongside';
-  return 'skip';
+/** Minimal dim helper for wizard-level notices. */
+function c_dim(s) {
+  return `${s}`;
 }
 
-async function wizardFlow(rl) {
+async function wizardFlow() {
   const created = [];
   const reporter = (entry) => created.push(entry);
-  const conflictAsk = (destPath) => askConflict(rl, destPath);
+  const conflictAsk = (destPath) => askConflict(destPath);
 
   stdout.write('kracked-core — set up memory for your AI coding agent\n\n');
 
   // 1. Agent name
-  const agentName = (await ask(rl, 'What should we call your agent?', 'KC')) || 'KC';
+  const agentName = sanitizeScanned(await input('What should we call your agent?', 'KC'), 40) || 'KC';
 
   // 2. User name
   const systemUser = os.userInfo().username || 'you';
-  const userName = (await ask(rl, 'Your name?', systemUser)) || systemUser;
+  const userName = sanitizeScanned(await input('Your name?', systemUser), 40) || systemUser;
 
-  // 3. Global memory
+  // 3. Global memory — always installed. It holds identity, preferences and
+  // cross-project lessons, and boot depends on it; making it optional only
+  // created a way to end up with a half-installed system that can't boot.
+  // Existing files are still never overwritten without asking.
   const hasGlobal = globalMemoryExists();
-  let setUpGlobal;
-  if (!hasGlobal) {
-    setUpGlobal = await askYesNo(rl, 'Set up global memory now?', true);
-  } else {
-    const reuse = await askYesNo(rl, 'Global memory found. Reuse it?', true);
-    setUpGlobal = !reuse; // if not reusing, we still (re)write it below
+  const setUpGlobal = true;
+  if (hasGlobal) {
+    stdout.write(`\n  Global memory found at ${globalMemoryDir()} — reusing it.\n`);
   }
 
   // 4. Project setup
-  const setUpProject = await askYesNo(rl, 'Set up this project?', true);
+  const setUpProject = await confirm('Set up this project?', true);
 
   let projectDir = process.cwd();
   let projectMode = null; // 'new' | 'existing'
@@ -156,24 +187,58 @@ async function wizardFlow(rl) {
   let projectSummary = null;
 
   if (setUpProject) {
-    const pathAnswer = await ask(rl, 'Project directory?', '.');
+    const pathAnswer = await input('Project directory?', '.');
     const expanded = expandTilde(pathAnswer);
     projectDir = path.resolve(expanded === '' ? '.' : expanded);
 
-    const classification = classifyProjectDir(projectDir);
+    const unsafe = rejectUnsafeProjectDir(projectDir);
+    if (unsafe) {
+      stdout.write(`\n  ${unsafe}\n\nStopped — nothing was written.\n`);
+      process.exitCode = 1;
+      return;
+    }
+
+    // Already installed here? 27 individual conflict prompts is not a sane
+    // default — offer the three real intents up front instead.
+    if (fs.existsSync(path.join(projectDir, '.kracked'))) {
+      stdout.write('\n  kracked-core is already set up in this project.\n\n');
+      const action = await select('What would you like to do?', [
+        { label: 'Refresh package files', value: 'refresh', hint: 'skills + loaders, keeps all your memory' },
+        { label: 'Reinstall everything', value: 'reinstall', hint: 'asks per file before replacing' },
+        { label: 'Cancel', value: 'cancel' },
+      ], 0);
+
+      if (action === 'cancel') {
+        stdout.write('\nCancelled — nothing changed.\n');
+        return;
+      }
+      if (action === 'refresh') {
+        const { runUpdate } = await import('./update.mjs');
+        process.chdir(projectDir);
+        await runUpdate();
+        return;
+      }
+    }
 
-    if (classification === 'existing') {
-      const modeAnswer = (
-        await ask(rl, 'New project or existing codebase? (new/existing)', 'existing')
-      ).toLowerCase();
-      projectMode = modeAnswer.startsWith('n') ? 'new' : 'existing';
-    } else {
-      const modeAnswer = (
-        await ask(rl, 'New project or existing codebase? (new/existing)', 'new')
-      ).toLowerCase();
-      projectMode = modeAnswer.startsWith('e') ? 'existing' : 'new';
+    // Another agent system already here? Ask before touching its loaders.
+    if (fs.existsSync(projectDir)) {
+      const proceed = await warnOnExistingSetup(projectDir);
+      if (!proceed) {
+        stdout.write('\nStopped — nothing was written to this project.\n');
+        return;
+      }
     }
 
+    const classification = classifyProjectDir(projectDir);
+    projectMode = await select(
+      'Is this a new project or an existing codebase?',
+      [
+        { label: 'Existing codebase', value: 'existing', hint: 'scan it and draft the memory' },
+        { label: 'New project', value: 'new', hint: 'start with a blank scaffold' },
+      ],
+      classification === 'existing' ? 0 : 1
+    );
+
     if (projectMode === 'existing') {
       if (!fs.existsSync(projectDir)) {
         stdout.write(`\n  ${projectDir} doesn't exist yet — nothing to scan. Treating as new.\n`);
@@ -192,10 +257,10 @@ async function wizardFlow(rl) {
         }
         stdout.write('\n');
 
-        const confirmed = await askYesNo(rl, 'Does this look right?', true);
+        const confirmed = await confirm('Does this look right?', true);
         if (!confirmed) {
-          const manualStack = await ask(rl, 'Describe the stack yourself:', stackLine);
-          stackLine = manualStack;
+          const manualStack = await input('Describe the stack yourself:', stackLine);
+          stackLine = sanitizeScanned(manualStack, 80) || stackLine;
         }
       }
     }
@@ -208,22 +273,42 @@ async function wizardFlow(rl) {
     }
   }
 
-  // 5. Editors
-  const editorAnswer = (
-    await ask(rl, 'Which editor(s) do you use? (antigravity/claude/both/other)', 'both')
-  ).toLowerCase();
-
-  let editors;
-  if (editorAnswer.startsWith('both')) {
-    editors = ['antigravity', 'claude'];
-  } else if (editorAnswer.startsWith('a')) {
-    editors = ['antigravity'];
-  } else if (editorAnswer.startsWith('c')) {
-    editors = ['claude'];
-  } else {
-    // "other" or anything unrecognized — still write both loader formats,
-    // since AGENTS.md/CLAUDE.md are cheap and cover most tools either way.
-    editors = ['antigravity', 'claude'];
+  // 5. Editors — a checkbox, so anyone already running another agent system in
+  // one harness can install for the other and leave that one alone.
+  const existing = setUpProject ? detectExistingAgentSetup(projectDir) : [];
+  const claudeTaken = existing.some((f) => f.file === 'CLAUDE.md' && !f.ours);
+
+  const editors = await checkbox('Which editor(s) do you use?', [
+    {
+      label: 'Antigravity',
+      value: 'antigravity',
+      checked: true,
+      hint: 'writes .agents/',
+    },
+    {
+      label: 'Claude Code',
+      value: 'claude',
+      checked: !claudeTaken,
+      hint: claudeTaken ? 'CLAUDE.md already in use here' : 'writes CLAUDE.md + .claude/',
+    },
+    {
+      label: 'Kilo Code (VS Code)',
+      value: 'kilo',
+      checked: false,
+      hint: 'reads AGENTS.md + .agents/skills; adds kilo.jsonc',
+    },
+    {
+      label: 'Roo Code (VS Code)',
+      value: 'roo',
+      checked: false,
+      hint: 'reads AGENTS.md + .agents/skills; adds .roo/rules',
+    },
+  ]);
+
+  // Kilo and Roo both read AGENTS.md and .agents/skills/ natively, so picking
+  // either implies the shared .agents/ footprint.
+  if ((editors.includes('kilo') || editors.includes('roo')) && !editors.includes('antigravity')) {
+    editors.push('antigravity');
   }
 
   // 6. Write files
@@ -254,7 +339,7 @@ async function wizardFlow(rl) {
 
   if (setUpProject) {
     await writeProjectMemory({ projectDir, tokens, ask: conflictAsk, report: reporter });
-    await writeLoaders({ projectDir, tokens, ask: conflictAsk, report: reporter });
+    await writeLoaders({ projectDir, tokens, ask: conflictAsk, report: reporter, editors });
     await writeSkills({ projectDir, tokens, editors, ask: conflictAsk, report: reporter });
   }
 

package/templates/loaders/AGENTS.md

@@ -1,3 +1,4 @@
+<!-- kracked-core:owned -->
 # AGENTS.md — {{PROJECT_NAME}}
 
 This is the canonical loader. Every harness (Antigravity, Claude Code, others) reads this file
@@ -50,6 +51,7 @@ the signup flow, next step is wiring the email step. Ready."
 | `/kracked-sdd` | Runs the SDD flow: idea → spec → docs → build → review |
 | `/kracked-wrap` | Writes lessons + updates session state, closes the session cleanly |
 | `/kracked-explain` | Walks {{USER_NAME}} through what kracked-core installed and why |
+| `/kracked-identity` | Change who you are, your tone, or how {{USER_NAME}} likes to work |
 
 ## Writing memory (wrap)
 

package/templates/loaders/CLAUDE.md

@@ -1,4 +1,5 @@
 @AGENTS.md
+<!-- kracked-core:owned -->
 
 This file is a shim. The canonical instructions live in `AGENTS.md` — duplicating them here would
 let the two drift apart, which is the exact bug kracked-core exists to prevent. If you need to

package/templates/loaders/antigravity-rules.md

@@ -1,3 +1,4 @@
+<!-- kracked-core:owned -->
 # Antigravity — {{PROJECT_NAME}}
 
 This file is a pointer, not the source of truth. The full instructions — who the agent is, the

package/templates/project/sdd/README.md

@@ -0,0 +1,46 @@
+# SDD — {{PROJECT_NAME}}
+
+Spec-driven development artifacts. Run `/kracked-sdd` to work through the flow; these folders are
+where it puts things.
+
+```
+idea → spec → epic → stories → build → review
+```
+
+| Folder | Holds | Written when |
+|---|---|---|
+| `specs/` | What to build and why | Start of any non-trivial job |
+| `epics/` | A group of related stories | When a spec is too big for one story |
+| `stories/` | One independently shippable slice | Broken out of a spec or epic |
+| `architecture/` | How the system is put together | Large or risky work only |
+| `tracker.md` | Status of every story + evidence | Continuously |
+
+## Naming
+
+Numbers first so files sort in the order you built them.
+
+```
+specs/login.md
+epics/1-authentication.md
+stories/1.1-email-login.md
+stories/1.2-password-reset.md
+architecture/data-model.md
+architecture/decisions/0001-use-postgres.md
+```
+
+Story IDs are `<epic>.<story>` and must match the ID in `tracker.md`. That's the link between a
+story's detail and its status — if they drift, the tracker stops being trustworthy.
+
+## The two rules that matter
+
+**1. Not everything needs the full flow.** A typo fix needs no spec. `/kracked-sdd` sizes the job
+first and skips straight to the build when ceremony would be waste. Over-documenting small work is
+the fastest way to abandon the system entirely.
+
+**2. A story isn't `done` without evidence.** The tracker's Evidence column must say what was
+actually verified — and what wasn't. "Tests pass" is not evidence of a working feature.
+
+## Commit these
+
+These docs belong in git. They're how the next person — including you in three months, and your
+agent on its next boot — finds out why the code looks the way it does.

package/templates/project/sdd/architecture/_TEMPLATE.md

@@ -0,0 +1,51 @@
+# Architecture — <area>
+
+**Date:** {{DATE}}
+**Status:** current | superseded by `<file>`
+
+Write one of these only for work that's **large or risky** — new services, data model changes,
+auth, anything touching money or user data. A small feature does not need an architecture doc,
+and writing one anyway is how the system becomes ceremony people skip.
+
+## The shape
+
+What the pieces are and how they talk to each other. A diagram in text is fine:
+
+```
+browser → api route → service → database
+                   ↘ queue → worker
+```
+
+## Data model
+
+Tables/collections, key fields, and the relationships that matter. Not every column — the ones a
+newcomer would get wrong.
+
+| Entity | Key fields | Related to |
+|---|---|---|
+| | | |
+
+## Key decisions
+
+The choices someone would otherwise re-litigate. Link to an ADR in `decisions/` for the big ones.
+
+| Decision | Why | Alternative rejected |
+|---|---|---|
+| | | |
+
+## Failure modes
+
+What breaks, and what happens when it does. Answer for each: does it fail loudly or silently?
+
+| What fails | Effect | Handling |
+|---|---|---|
+| Database unreachable | | |
+| Third-party API down | | |
+| Duplicate/retried request | | |
+
+## What this does NOT do
+
+Scope boundaries and deliberate limitations. Prevents someone assuming a capability that isn't
+there.
+
+- ...

package/templates/project/sdd/architecture/decisions/_TEMPLATE.md

@@ -0,0 +1,40 @@
+# <NNNN> — <the decision, as a statement>
+
+**Date:** {{DATE}}
+**Status:** accepted | superseded by `<NNNN>` | reversed
+
+> Example filename: `0001-use-postgres-not-mongo.md`
+> Number them in order. Never renumber or delete one — a reversed decision is still history worth
+> keeping, and the reasoning is often more valuable than the outcome.
+
+## Context
+
+What forced a choice here? The constraints, the pressures, what was true at the time. Someone
+reading this in six months has none of that context — this section is the whole point.
+
+## Decision
+
+What was decided, stated plainly and in the present tense. "We use X." Not "we should" or
+"we might."
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| | |
+
+## Consequences
+
+Both directions — honest about the costs.
+
+**Good:**
+- ...
+
+**Costs / things we now have to live with:**
+- ...
+
+## Revisit if
+
+The conditions that would make this decision wrong. If none, say "no expected trigger."
+
+- ...

package/templates/project/sdd/epics/_TEMPLATE.md

@@ -0,0 +1,34 @@
+# Epic <N> — <name>
+
+**Spec:** `../specs/<name>.md`
+**Status:** planning | in-progress | done
+**Date:** {{DATE}}
+
+## Goal
+
+What is true when this whole epic is finished? One or two sentences.
+
+## Stories
+
+Every story must be **independently shippable** — mergeable on its own, leaving the app working.
+If a story can't ship alone, split it.
+
+| ID | Story | File |
+|---|---|---|
+| <N>.1 | | `../stories/<N>.1-<slug>.md` |
+| <N>.2 | | `../stories/<N>.2-<slug>.md` |
+
+Status lives in `../tracker.md`, not here. One source of truth — don't track status in two places
+or they drift.
+
+## Order
+
+Which stories block others, and why. If they're all independent, say so explicitly.
+
+1. ...
+
+## Out of scope
+
+What belongs to a future epic, not this one.
+
+- ...

package/templates/project/sdd/specs/_TEMPLATE.md

@@ -0,0 +1,44 @@
+# Spec — <name>
+
+**Status:** draft | agreed | building | shipped
+**Date:** {{DATE}}
+
+## What
+
+One paragraph. What is being built, in plain language — no implementation detail.
+
+## Why
+
+The problem this solves, and for whom. If you can't name who is worse off without it, the spec
+isn't ready.
+
+## Acceptance criteria
+
+Concrete and checkable. Someone else must be able to read these and tell whether the thing works.
+
+- [ ] A user can ...
+- [ ] When X happens, the system ...
+- [ ] If the input is empty/invalid, it ...
+
+## Out of scope
+
+**Not optional.** Scope creep starts exactly where this section is skipped. List what this spec
+deliberately does NOT cover.
+
+- ...
+
+## Edge cases
+
+For every input involved, answer: what if it's empty, missing, or unexpected?
+
+| Case | Expected behaviour |
+|---|---|
+| Empty input | |
+| Already exists | |
+| Not authorised | |
+
+## Open questions
+
+Things that must be answered before or during the build. Delete this section once it's empty.
+
+- [ ] ...

package/templates/project/sdd/stories/_TEMPLATE.md

@@ -0,0 +1,33 @@
+# Story <N>.<M> — <name>
+
+**Epic:** `../epics/<N>-<slug>.md`
+**Status:** backlog | in-progress | review | done  ← mirror this in `../tracker.md`
+**Date:** {{DATE}}
+
+## What
+
+One slice of the epic. Small enough to build and verify in one sitting.
+
+## Acceptance criteria
+
+- [ ] ...
+- [ ] ...
+
+## Notes for the build
+
+Files likely to change, existing code to reuse, anything that would trip someone up.
+
+> Verify these claims before building on them. A story written from memory can name a file,
+> function, or column that doesn't exist — grep first, then build.
+
+- ...
+
+## Evidence
+
+**Fill this in before marking `done`.** Copy the summary line into `tracker.md`.
+
+- **Verified:** what you actually ran or checked, and what you saw
+- **Not verified:** what you did NOT check — untested paths, edge cases, anything left open
+
+A story marked `done` with an empty Evidence section is worse than one left at `review`: it hides
+risk instead of surfacing it.

package/templates/skills/kracked-boot/SKILL.md

@@ -5,14 +5,21 @@ description: Use at the start of every session, before any other work, to load g
 
 Run this before doing anything else in the session. Do not skip steps or merge reads together.
 
-## 1. Check that memory exists
+## 1. Check what memory exists
 
-Look for `~/.kracked/identity.md`. If it is missing, global memory has not been set up. Tell the
-user:
+Look for `~/.kracked/identity.md` (global) and `.kracked/` in the current directory (project).
+At least one must exist. Boot works with either layer — never halt just because one is missing.
 
-> Global memory isn't set up yet. Run `npx kracked-core init` to create it, then re-run this.
+- **Both present** — normal boot. Continue to step 2.
+- **Project only** (no `~/.kracked/`) — boot from project memory alone. Behave as a careful,
+  direct coding agent, and say in your orientation line that global memory isn't set up, so
+  cross-project lessons and preferences aren't loaded. Mention `npx kracked-core init` once.
+  Do NOT invent preferences or lessons you haven't read.
+- **Global only** (no `.kracked/` here) — see step 3.
+- **Neither** — nothing is installed. Say so and point at `npx kracked-core init`. This is the
+  only case where there's nothing to load.
 
-Stop here if memory doesn't exist. Do not fabricate identity, preferences, or project state.
+Never fabricate identity, preferences, project state, or lessons. Missing is missing — say it.
 
 ## 2. Load global memory, in this exact order
 
@@ -36,6 +43,7 @@ If the current directory has a `.kracked/` folder, read:
 1. `.kracked/project.md` — what this project is (stack, conventions)
 2. `.kracked/session.md` — working memory: state + next steps
 3. `.kracked/decisions.md` — why things are the way they are
+4. `.kracked/sdd/tracker.md` — story status, if this project uses SDD (skip if absent)
 
 If there is no `.kracked/` folder here, this is a project that hasn't been set up yet. Say so
 plainly and suggest `npx kracked-core init` if the user wants project memory for it. Continue