kracked-core 1.1.0 → 1.4.0

package/src/uninstall.mjs

@@ -0,0 +1,214 @@
+// `kracked-core uninstall` — remove what the installer wrote.
+//
+// Deleting a user's memory is unrecoverable, so this is deliberately cautious:
+// it shows exactly what it will remove, asks per layer, defaults to No on the
+// global layer, and never deletes a file it didn't recognise as its own.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { stdout } from 'node:process';
+
+import { select, confirm } from './prompt.mjs';
+import { OWNED_MARKER, SKILL_NAMES } from './scaffold.mjs';
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+
+/**
+ * Files/dirs the installer writes into a project.
+ *
+ * CRITICAL: when the "project" IS the home directory, `<project>/.kracked` and
+ * `~/.kracked` are the same folder — so listing it as a project target would
+ * delete the user's entire global memory behind the mild "Remove these project
+ * files?" prompt, never reaching the two-step global confirmation below.
+ * Global memory is only ever removable via the global layer.
+ */
+function projectTargets(projectDir) {
+  const globalDir = path.resolve(path.join(os.homedir(), '.kracked'));
+
+  const targets = [
+    { path: path.join(projectDir, '.kracked'), label: '.kracked/', kind: 'dir' },
+    { path: path.join(projectDir, 'AGENTS.md'), label: 'AGENTS.md', kind: 'file' },
+    { path: path.join(projectDir, 'CLAUDE.md'), label: 'CLAUDE.md', kind: 'file' },
+    {
+      path: path.join(projectDir, '.agents', 'rules', 'kracked.md'),
+      label: '.agents/rules/kracked.md',
+      kind: 'file',
+    },
+  ];
+
+  // Roo's rules mirror. kilo.jsonc is deliberately NOT listed — it may hold the
+  // user's own settings, so removing it wholesale would destroy their config.
+  targets.push({
+    path: path.join(projectDir, '.roo', 'rules', 'kracked.md'),
+    label: '.roo/rules/kracked.md',
+    kind: 'file',
+  });
+
+  // "Write alongside" during init creates these; nothing else knew about them,
+  // so they were orphaned forever.
+  for (const base of ['AGENTS.md', 'CLAUDE.md']) {
+    targets.push({
+      path: path.join(projectDir, `${base}.kracked-new`),
+      label: `${base}.kracked-new`,
+      kind: 'file',
+    });
+  }
+
+  for (const skill of SKILL_NAMES) {
+    targets.push({
+      path: path.join(projectDir, '.claude', 'skills', skill),
+      label: `.claude/skills/${skill}/`,
+      kind: 'dir',
+    });
+    targets.push({
+      path: path.join(projectDir, '.agents', 'skills', skill),
+      label: `.agents/skills/${skill}/`,
+      kind: 'dir',
+    });
+  }
+
+  return targets.filter((t) => {
+    if (!fs.existsSync(t.path)) return false;
+    // Never let a project target resolve onto global memory.
+    if (path.resolve(t.path) === globalDir) return false;
+    return true;
+  });
+}
+
+/**
+ * Only the two SHARED loader filenames can belong to another system —
+ * AGENTS.md and CLAUDE.md are conventions other tools use too, so their
+ * contents decide ownership. Everything else lives at a kracked-core-specific
+ * path (.kracked/, kracked.md, skills/kracked-*) and is ours by definition.
+ */
+function isOurs(filePath) {
+  const base = path.basename(filePath);
+  if (base !== 'AGENTS.md' && base !== 'CLAUDE.md') return true;
+
+  try {
+    // Require the sentinel the installer writes. Anything else — including a
+    // file that merely MENTIONS kracked-core, or another tool using the shared
+    // `@AGENTS.md` import convention — is someone else's and must survive.
+    // Fail closed: an orphaned file is recoverable, a deleted one is not.
+    const body = fs.readFileSync(filePath, 'utf8');
+    if (body.includes(OWNED_MARKER)) return true;
+
+    // Pre-sentinel installs (<=1.2.0) have no marker. Recognise their exact
+    // generated shape so an upgrade path doesn't orphan loaders forever.
+    // Deliberately narrow: a bare `@AGENTS.md` (a shared convention other tools
+    // use) is NOT enough on its own.
+    const legacyClaude = /^@AGENTS\.md\s*\n[\s\S]*canonical instructions live in `AGENTS\.md`/.test(body);
+    const legacyAgents = /^# AGENTS\.md — [\s\S]*This is the canonical loader[\s\S]*kracked-boot/.test(body);
+    return legacyClaude || legacyAgents;
+  } catch {
+    return false; // unreadable — leave it alone rather than risk deleting someone else's
+  }
+}
+
+function remove(target) {
+  if (target.kind === 'dir') {
+    fs.rmSync(target.path, { recursive: true, force: true });
+  } else {
+    fs.rmSync(target.path, { force: true });
+  }
+}
+
+/** Drop now-empty .claude/.agents shells so uninstall leaves no litter. */
+function pruneEmptyParents(projectDir) {
+  const candidates = [
+    path.join(projectDir, '.claude', 'skills'),
+    path.join(projectDir, '.claude'),
+    path.join(projectDir, '.agents', 'rules'),
+    path.join(projectDir, '.roo', 'rules'),
+    path.join(projectDir, '.roo'),
+    path.join(projectDir, '.agents', 'skills'),
+    path.join(projectDir, '.agents'),
+  ];
+  for (const dir of candidates) {
+    try {
+      if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) fs.rmdirSync(dir);
+    } catch {
+      // Non-empty or not ours to remove — leaving it is the safe outcome.
+    }
+  }
+}
+
+export async function runUninstall() {
+  if (!process.stdin.isTTY) {
+    process.stderr.write(
+      'kracked-core uninstall needs an interactive terminal.\n' +
+      'Run it directly in a terminal, or delete the files manually — see\n' +
+      'https://github.com/Krackeddevs-Org/kracked-core/blob/main/docs/UNINSTALL.md\n'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const projectDir = process.cwd();
+  const globalDir = path.join(os.homedir(), '.kracked');
+
+  stdout.write(`${bold('kracked-core uninstall')}\n\n`);
+
+  // ---- Project layer ----
+  const found = projectTargets(projectDir);
+
+  if (found.length === 0) {
+    stdout.write(`No kracked-core files found in ${projectDir}\n`);
+  } else {
+    // Loaders another system owns must never be deleted.
+    const foreign = found.filter((t) => t.kind === 'file' && !isOurs(t.path));
+    const ours = found.filter((t) => !foreign.includes(t));
+
+    stdout.write(`Found in ${dim(projectDir)}:\n`);
+    for (const t of ours) stdout.write(`  ${t.label}\n`);
+    if (foreign.length) {
+      stdout.write('\n  Not ours — will NOT be touched:\n');
+      for (const t of foreign) stdout.write(`    ${t.label} ${dim('(another system wrote this)')}\n`);
+    }
+    stdout.write('\n');
+
+    const choice = await select('Remove these project files?', [
+      { label: 'No, keep everything', value: 'no' },
+      { label: 'Yes, remove them', value: 'yes', hint: 'this cannot be undone' },
+    ], 0);
+
+    if (choice === 'yes') {
+      for (const t of ours) remove(t);
+      pruneEmptyParents(projectDir);
+      stdout.write(`\n  Removed ${ours.length} item(s) from this project.\n`);
+    } else {
+      stdout.write('\n  Kept project files.\n');
+    }
+  }
+
+  // ---- Global layer ----
+  stdout.write('\n');
+  if (!fs.existsSync(globalDir)) {
+    stdout.write(`No global memory at ${globalDir}\n`);
+  } else {
+    stdout.write(`${bold('Global memory')} — ${dim(globalDir)}\n`);
+    stdout.write(
+      '  This holds your agent\'s identity, your preferences, and every lesson it has\n' +
+      '  learned across ALL projects. Removing it cannot be undone, and it is not\n' +
+      '  recreated by reinstalling — the content is yours, not the package\'s.\n\n'
+    );
+
+    const wipe = await confirm('Remove global memory too?', false);
+    if (wipe) {
+      // Deleting months of accumulated lessons deserves a second, explicit yes.
+      const sure = await confirm('Are you sure? Your lessons and preferences will be gone.', false);
+      if (sure) {
+        fs.rmSync(globalDir, { recursive: true, force: true });
+        stdout.write('\n  Removed global memory.\n');
+      } else {
+        stdout.write('\n  Kept global memory.\n');
+      }
+    } else {
+      stdout.write('\n  Kept global memory.\n');
+    }
+  }
+
+  stdout.write('\nDone.\n');
+}

package/src/update.mjs

@@ -0,0 +1,150 @@
+// `kracked-core update` — refresh the package-owned files without touching
+// anything the user has written.
+//
+// The distinction that makes this safe: SKILLS and LOADERS are package files
+// (we wrote them, we can replace them). MEMORY is the user's (identity,
+// preferences, lessons, project docs) — never overwritten here, ever.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { stdout } from 'node:process';
+import { createRequire } from 'node:module';
+
+import { select } from './prompt.mjs';
+import { writeLoaders, writeSkills, SKILL_NAMES } from './scaffold.mjs';
+
+const require = createRequire(import.meta.url);
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+
+function installedVersion() {
+  try {
+    return require('../package.json').version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+/** Which harnesses this project already uses, so update doesn't add new ones. */
+function detectInstalledHarnesses(projectDir) {
+  const editors = [];
+  if (fs.existsSync(path.join(projectDir, '.claude', 'skills'))) editors.push('claude');
+  if (fs.existsSync(path.join(projectDir, '.agents', 'skills'))) editors.push('antigravity');
+  // A CLAUDE.md with no skills dir still means Claude Code is in play.
+  if (!editors.includes('claude') && fs.existsSync(path.join(projectDir, 'CLAUDE.md'))) {
+    editors.push('claude');
+  }
+  return editors;
+}
+
+/** Read the agent + user name back out of an installed AGENTS.md. */
+function recoverTokens(projectDir) {
+  const agentsPath = path.join(projectDir, 'AGENTS.md');
+  const tokens = { AGENT_NAME: 'KC', USER_NAME: os.userInfo().username || 'you' };
+
+  try {
+    const body = fs.readFileSync(agentsPath, 'utf8');
+    const agent = body.match(/You are \*\*([^*]+)\*\*/);
+    if (agent) tokens.AGENT_NAME = agent[1].trim();
+    const user = body.match(/how ([^\s]+) likes to work/);
+    if (user) tokens.USER_NAME = user[1].trim();
+  } catch {
+    // No AGENTS.md to read — fall back to defaults above.
+  }
+
+  return tokens;
+}
+
+/** Which skills exist here but aren't in this version — i.e. new ones to add. */
+function missingSkills(projectDir, editors) {
+  const missing = [];
+  for (const skill of SKILL_NAMES) {
+    const inClaude = editors.includes('claude')
+      && fs.existsSync(path.join(projectDir, '.claude', 'skills', skill, 'SKILL.md'));
+    const inAgents = editors.includes('antigravity')
+      && fs.existsSync(path.join(projectDir, '.agents', 'skills', skill, 'SKILL.md'));
+    const expected = (editors.includes('claude') ? 1 : 0) + (editors.includes('antigravity') ? 1 : 0);
+    const present = (inClaude ? 1 : 0) + (inAgents ? 1 : 0);
+    if (present < expected) missing.push(skill);
+  }
+  return missing;
+}
+
+export async function runUpdate() {
+  if (!process.stdin.isTTY) {
+    process.stderr.write(
+      'kracked-core update needs an interactive terminal.\n' +
+      'Run it directly in a terminal, not piped or in a script.\n'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const projectDir = process.cwd();
+  const version = installedVersion();
+
+  stdout.write(`${bold('kracked-core update')} ${dim(`v${version}`)}\n\n`);
+
+  if (!fs.existsSync(path.join(projectDir, '.kracked'))) {
+    stdout.write(
+      `No kracked-core install found in ${projectDir}\n\n` +
+      'Run `npx kracked-core init` to set it up first.\n'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const editors = detectInstalledHarnesses(projectDir);
+  if (editors.length === 0) {
+    stdout.write('Found .kracked/ but no editor files. Run `npx kracked-core init` instead.\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  const tokens = {
+    ...recoverTokens(projectDir),
+    PROJECT_NAME: path.basename(projectDir),
+    PROJECT_PATH: projectDir,
+    DATE: new Date().toISOString().slice(0, 10),
+    STACK: '',
+    RUN_COMMANDS: '',
+  };
+
+  const newSkills = missingSkills(projectDir, editors);
+
+  stdout.write(`Agent:   ${tokens.AGENT_NAME}\n`);
+  stdout.write(`Editors: ${editors.join(', ')}\n`);
+  if (newSkills.length) {
+    stdout.write(`New in this version: ${newSkills.join(', ')}\n`);
+  }
+
+  stdout.write(`\n${bold('Will be refreshed')} ${dim('(package files — safe to replace)')}\n`);
+  stdout.write('  the 5 skills, AGENTS.md, CLAUDE.md, .agents/rules/kracked.md\n');
+  stdout.write(`\n${bold('Will NOT be touched')} ${dim('(yours)')}\n`);
+  stdout.write('  ~/.kracked/  — identity, preferences, lessons\n');
+  stdout.write('  .kracked/    — project memory, specs, epics, stories, architecture\n\n');
+
+  const choice = await select('Refresh package files to this version?', [
+    { label: 'Yes, update', value: 'yes' },
+    { label: 'No, cancel', value: 'no' },
+  ], 0);
+
+  if (choice === 'no') {
+    stdout.write('\nCancelled — nothing changed.\n');
+    return;
+  }
+
+  // Package files are ours, so overwrite silently rather than prompting per
+  // file. User memory is never in this set.
+  const created = [];
+  const report = (entry) => created.push(entry);
+  const overwrite = async () => 'overwrite';
+
+  stdout.write('\nUpdating...\n');
+  await writeLoaders({ projectDir, tokens, ask: overwrite, report, editors });
+  await writeSkills({ projectDir, tokens, editors, ask: overwrite, report });
+
+  stdout.write(`\n  Refreshed ${created.length} file(s).\n`);
+  stdout.write('\nRestart your editor so it picks up the updated skills.\n');
+}

package/src/wizard.mjs

@@ -13,6 +13,7 @@ import {
   scanExistingProject,
   stackSummaryLine,
   detectExistingAgentSetup,
+  sanitizeScanned,
 } from './detect.mjs';
 import { select, checkbox, confirm, input } from './prompt.mjs';
 import {
@@ -38,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
@@ -136,11 +162,11 @@ async function wizardFlow() {
   stdout.write('kracked-core — set up memory for your AI coding agent\n\n');
 
   // 1. Agent name
-  const agentName = (await input('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 input('Your name?', systemUser)) || systemUser;
+  const userName = sanitizeScanned(await input('Your name?', systemUser), 40) || systemUser;
 
   // 3. Global memory — always installed. It holds identity, preferences and
   // cross-project lessons, and boot depends on it; making it optional only
@@ -165,6 +191,35 @@ async function wizardFlow() {
     const expanded = expandTilde(pathAnswer);
     projectDir = path.resolve(expanded === '' ? '.' : expanded);
 
+    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;
+      }
+    }
+
     // Another agent system already here? Ask before touching its loaders.
     if (fs.existsSync(projectDir)) {
       const proceed = await warnOnExistingSetup(projectDir);
@@ -205,7 +260,7 @@ async function wizardFlow() {
         const confirmed = await confirm('Does this look right?', true);
         if (!confirmed) {
           const manualStack = await input('Describe the stack yourself:', stackLine);
-          stackLine = manualStack;
+          stackLine = sanitizeScanned(manualStack, 80) || stackLine;
         }
       }
     }
@@ -236,8 +291,26 @@ async function wizardFlow() {
       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
   const projectName = projectSummary?.name || (setUpProject ? path.basename(projectDir) : 'unnamed-project');
 
@@ -266,7 +339,7 @@ async function wizardFlow() {
 
   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

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."
+
+- ...