kairn-cli 1.12.0 → 1.14.0

package/dist/cli.js

@@ -706,6 +706,23 @@ Use subagents for deep investigation to keep main context clean.
 - Do not create abstractions for one-time operations
 - Complete the task fully \u2014 don't gold-plate, but don't leave it half-done
 - Prefer editing existing files over creating new ones
+
+## First Turn Protocol
+
+At the start of every session, before doing ANY work:
+1. Run \`pwd && ls -la && git status --short\` to orient yourself
+2. Check relevant runtimes (e.g. \`node --version\`, \`python3 --version\` \u2014 pick what fits this project)
+3. Read any task-tracking files (docs/SPRINT.md, docs/DECISIONS.md)
+4. Summarize what you see in 2-3 lines, then proceed
+
+This saves 2-5 exploratory turns. Never ask "what files are here?" \u2014 look first.
+
+## Completion Standards
+
+Never mark a task "done" without running the Completion Verification checklist.
+Tests passing is necessary but not sufficient \u2014 also verify requirements coverage,
+state cleanliness, and review changes from the perspective of a test engineer,
+code reviewer, and the requesting user.
 \`\`\`
 
 Do not add generic filler. Every line must be specific to the user's workflow.
@@ -727,6 +744,8 @@ Do not add generic filler. Every line must be specific to the user's workflow.
 13. A "Debugging" section in CLAUDE.md (2 lines: paste raw errors, use subagents)
 14. A "Git Workflow" section in CLAUDE.md (3 rules: small commits, conventional format, <200 lines PR)
 15. "Engineering Standards", "Tool Usage Policy", and "Code Philosophy" sections in CLAUDE.md
+16. A "First Turn Protocol" section in CLAUDE.md (orient before working: pwd, ls, git status, check relevant runtimes, read task files)
+17. A "Completion Standards" section in CLAUDE.md (never mark done without verifying: requirements met, tests passing, no debug artifacts, reviewed from 3 perspectives)
 
 ## Shell-Integrated Commands
 
@@ -844,7 +863,7 @@ Merge this into the settings hooks alongside the PreToolUse and PostToolUse hook
 - \`/project:status\` command (live git status, recent commits, SPRINT.md overview using ! prefix)
 - \`/project:fix\` command (takes $ARGUMENTS as issue number, plans fix, implements, tests, commits)
 - \`/project:sprint\` command (define acceptance criteria before coding, writes to docs/SPRINT.md)
-- \`/project:develop\` command (full development pipeline \u2014 orchestrates @architect \u2192 @planner \u2192 @implementer \u2192 @verifier \u2192 @fixer \u2192 @grill \u2192 @doc-updater through spec, plan, TDD implement, review, and doc update phases)
+- \`/project:develop\` command (full development pipeline \u2014 orchestrates @architect \u2192 @planner \u2192 @implementer \u2192 @verifier \u2192 @fixer \u2192 @grill \u2192 @doc-updater through spec, plan, TDD implement, review, and doc update phases). MUST include a Phase 7 "Completion Gate" that runs a Completion Verification checklist before marking the feature done: re-read original requirements, confirm each is met with evidence, run test suite + lint/typecheck, review git diff for unexpected changes or debug artifacts, answer 3 perspective questions (test engineer, code reviewer, requesting user). If ANY check fails, loop back to fix before completing.
 - A TDD skill using the 3-phase isolation pattern (RED \u2192 GREEN \u2192 REFACTOR):
   - RED: Write failing test only. Verify it FAILS.
   - GREEN: Write MINIMUM code to pass. Nothing extra.
@@ -1002,6 +1021,23 @@ Use subagents for deep investigation to keep main context clean.
 - Do not create abstractions for one-time operations
 - Complete the task fully \u2014 don't gold-plate, but don't leave it half-done
 - Prefer editing existing files over creating new ones
+
+## First Turn Protocol
+
+At the start of every session, before doing ANY work:
+1. Run \`pwd && ls -la && git status --short\` to orient yourself
+2. Check relevant runtimes (e.g. \`node --version\`, \`python3 --version\` \u2014 pick what fits this project)
+3. Read any task-tracking files (docs/SPRINT.md, docs/DECISIONS.md)
+4. Summarize what you see in 2-3 lines, then proceed
+
+This saves 2-5 exploratory turns. Never ask "what files are here?" \u2014 look first.
+
+## Completion Standards
+
+Never mark a task "done" without running the Completion Verification checklist.
+Tests passing is necessary but not sufficient \u2014 also verify requirements coverage,
+state cleanliness, and review changes from the perspective of a test engineer,
+code reviewer, and the requesting user.
 \`\`\`
 
 Do not add generic filler. Every line must be specific to the user's workflow.
@@ -1023,6 +1059,8 @@ Do not add generic filler. Every line must be specific to the user's workflow.
 13. A "Debugging" section in CLAUDE.md (2 lines: paste raw errors, use subagents)
 14. A "Git Workflow" section in CLAUDE.md (3 rules: small commits, conventional format, <200 lines PR)
 15. "Engineering Standards", "Tool Usage Policy", and "Code Philosophy" sections in CLAUDE.md
+16. A "First Turn Protocol" section in CLAUDE.md (orient before working: pwd, ls, git status, check relevant runtimes, read task files)
+17. A "Completion Standards" section in CLAUDE.md (never mark done without verifying: requirements met, tests passing, no debug artifacts, reviewed from 3 perspectives)
 
 ## Tool Selection Rules
 
@@ -1577,6 +1615,61 @@ ${agentList}
 Type \`/project:help\` in Claude Code for a quick reference.
 `;
 }
+var BOOTSTRAP_COMMAND = `# Environment Snapshot
+
+Run this command at the start of any session to gather runtime context.
+This saves 2-5 exploratory turns.
+
+1. Run the following compound command and read the output:
+   \`\`\`bash
+   echo '=== WORKING DIRECTORY ===' && pwd && \\
+   echo '=== PROJECT FILES ===' && ls -la && \\
+   echo '=== GIT STATUS ===' && (git status --short 2>/dev/null || echo 'not a git repo') && \\
+   echo '=== LANGUAGES ===' && \\
+   (node --version 2>&1 || true) && \\
+   (python3 --version 2>&1 || true) && \\
+   (go version 2>&1 || true) && \\
+   (rustc --version 2>&1 || true) && \\
+   echo '=== PACKAGE MANAGERS ===' && \\
+   (npm --version 2>&1 && echo "npm $(npm --version 2>&1)" || true) && \\
+   (pip3 --version 2>&1 || true) && \\
+   (cargo --version 2>&1 || true) && \\
+   echo '=== ENVIRONMENT ===' && \\
+   (cat .env 2>/dev/null | sed 's/=.*/=***/' || echo 'no .env file')
+   \`\`\`
+
+2. Summarize the environment in 3-4 lines:
+   - Runtime: [languages + versions found]
+   - Project: [framework, key deps, file count]
+   - State: [git branch, clean/dirty, .env present]
+
+3. Keep this summary in context for the rest of the session.`;
+function buildBootstrapHookCommand(spec) {
+  const checks = [
+    "echo '--- Environment Snapshot ---'",
+    "pwd",
+    "ls -la --color=never | head -20",
+    "echo '---'",
+    "git status --short 2>/dev/null || true",
+    "echo '---'"
+  ];
+  const md = (spec.harness.claude_md ?? "").toLowerCase();
+  if (md.includes("node") || md.includes("typescript") || md.includes("javascript") || md.includes("react") || md.includes("next")) {
+    checks.push("node --version 2>&1 || true");
+    checks.push("cat package.json 2>/dev/null | head -5 || true");
+  }
+  if (md.includes("python") || md.includes("django") || md.includes("flask") || md.includes("fastapi")) {
+    checks.push("python3 --version 2>&1 || true");
+  }
+  if (md.includes("rust") || md.includes("cargo")) {
+    checks.push("rustc --version 2>&1 || true");
+  }
+  if (md.includes("go ") || md.includes("golang")) {
+    checks.push("go version 2>&1 || true");
+  }
+  checks.push("cat .env 2>/dev/null | sed 's/=.*/=***/' || true");
+  return checks.join(" && ");
+}
 var LOOP_COMMAND_CODE = `# Development Loop
 
 Run an assisted development cycle for the next feature.
@@ -1605,7 +1698,29 @@ If confidence is LOW or MEDIUM, fix issues and re-verify.
 Run /project:grill for adversarial review.
 Fix any BLOCKERs.
 
-## Phase 6: SHIP
+## Phase 6: COMPLETION GATE
+
+Before shipping, run the Completion Verification checklist:
+
+### Requirements Check
+- [ ] Re-read the ORIGINAL task description (not your interpretation)
+- [ ] Each explicit requirement is met with evidence (test output, diff)
+- [ ] Each implicit requirement (error handling, types, tests) is addressed
+
+### State Check
+- [ ] Test suite passes
+- [ ] Lint/typecheck passes
+- [ ] \`git diff --stat\` \u2014 every changed file is intentional
+- [ ] No debug artifacts (console.log, TODO, commented-out code, temp files)
+
+### Perspective Check (1 sentence each)
+- **Test engineer:** Most likely production failure mode?
+- **Code reviewer:** What would I flag in review?
+- **Requesting user:** Does this solve my actual problem?
+
+ALL pass \u2192 proceed to ship. ANY fail \u2192 fix first, then re-verify.
+
+## Phase 7: SHIP
 Run /project:commit.
 Report what was built and what's next from docs/SPRINT.md.
 
@@ -1685,11 +1800,26 @@ Run verification:
 - Run functional tests
 - If NEEDS FIXES: fix and re-verify
 
-## Phase 5: PR
+## Phase 5: COMPLETION GATE
+
+Before creating a PR, run the Completion Verification checklist:
+- [ ] Re-read the ORIGINAL spec from docs/SPRINT.md
+- [ ] Each requirement is met with evidence (test output, diff)
+- [ ] Test suite + lint/typecheck pass
+- [ ] \`git diff --stat\` \u2014 every changed file is intentional, no debug artifacts
+- **Test engineer:** Most likely production failure mode?
+- **Code reviewer:** What would I flag in review?
+- **Requesting user:** Does this solve my actual problem?
+
+ALL pass \u2192 proceed to PR. ANY fail \u2192 fix first, then re-verify.
+
+Include the checklist results in the PR description.
+
+## Phase 6: PR
 Create a pull request:
-  gh pr create --title "feat: {name}" --body "{spec + QA report}"
+  gh pr create --title "feat: {name}" --body "{spec + QA report + verification checklist}"
 
-## Phase 6: NEXT
+## Phase 7: NEXT
 Report:
   "PR #{N} ready for review: {link}
    Next priority from SPRINT.md: {next task}
@@ -1713,13 +1843,19 @@ Repeat until max features reached or stopped:
 2. Create worktree + branch
 3. Implement the feature
 4. Run verification (build, test, lint)
-5. Open PR via gh
-6. Report status
-7. Move to next feature
+5. Run Completion Verification checklist:
+   - Requirements met with evidence
+   - Tests + lint/typecheck pass
+   - No debug artifacts or unexpected file changes
+   - 3-perspective check (test engineer, reviewer, user)
+6. Open PR via gh (include verification results in PR body)
+7. Report status
+8. Move to next feature
 
 ## Stop Conditions
 - Max 5 features per autopilot session
 - Any BLOCKER from verification
+- Completion Verification checklist fails after 2 fix attempts
 - Build failure that can't be resolved in 3 attempts
 - User presses Escape`;
 var AUTOPILOT_WARNING = `
@@ -1750,6 +1886,9 @@ function applyAutonomyLevel(spec) {
     settings.hooks = hooks;
   }
   if (level >= 2) {
+    if (!("bootstrap" in commands)) {
+      commands.bootstrap = BOOTSTRAP_COMMAND;
+    }
     if (!("loop" in commands)) {
       commands.loop = isResearchProject(spec) ? LOOP_COMMAND_RESEARCH : LOOP_COMMAND_CODE;
     }
@@ -1761,6 +1900,18 @@ function applyAutonomyLevel(spec) {
     if (!("auto" in commands)) {
       commands.auto = AUTO_COMMAND;
     }
+    const hooks = settings.hooks ?? {};
+    const sessionStart = hooks.SessionStart ?? [];
+    const bootstrapHook = {
+      matcher: "",
+      hooks: [{
+        type: "command",
+        command: buildBootstrapHookCommand(spec)
+      }]
+    };
+    sessionStart.push(bootstrapHook);
+    hooks.SessionStart = sessionStart;
+    settings.hooks = hooks;
   }
   if (level >= 4) {
     if (!("autopilot" in commands)) {