cc-dev-template 0.1.100 → 0.1.102

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.100",
+  "version": "0.1.102",
   "description": "Structured AI-assisted development framework for Claude Code",
   "bin": {
     "cc-dev-template": "./bin/install.js"

package/src/scripts/ship-policy.js

@@ -7,15 +7,15 @@
  * of (phase, agent_type, tool_name, target_path) rules. No-op when
  * ship is not active for the current session.
  *
- * Shared mailbox: {cwd}/.claude/ship-hook-state.json
- *   Written by orchestrator (doesn't know its session_id).
+ * Per-session state: {cwd}/.claude/ship-sessions/{session_id}.json
+ *   Created/updated by this hook when it intercepts `ship-state.js`
+ *   Bash calls. The agent doesn't know its session_id — only the hook does.
  *
- * Per-session: {cwd}/.claude/ship-sessions/{session_id}.json
- *   Created by the hook when it intercepts a Write to the mailbox.
- *   This is what the hook reads for enforcement.
+ * Feature state: {spec_dir}/state.yaml
+ *   Created/updated by ship-state.js (the CLI script the agent runs).
  */
 
-const { readFileSync, writeFileSync, existsSync, mkdirSync, realpathSync } = require('fs');
+const { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, realpathSync } = require('fs');
 const { join, resolve, relative } = require('path');
 
 // Tools that bypass all policy checks
@@ -61,16 +61,6 @@ function relPath(tool, input, cwd) {
   return relative(cwd, abs);
 }
 
-function realResolve(p) {
-  const abs = resolve(p);
-  try { return realpathSync(abs); } catch {}
-  // File may not exist yet — resolve parent
-  const dir = resolve(abs, '..');
-  const base = require('path').basename(abs);
-  try { return join(realpathSync(dir), base); } catch {}
-  return abs;
-}
-
 function under(p, prefix) {
   const dir = prefix.replace(/\/$/, '');
   return p === dir || p.startsWith(dir + '/');
@@ -101,8 +91,8 @@ function orchestratorPolicy(tool, input, cwd, specDir, phase) {
     const p = relPath(tool, input, cwd);
     if (p === null || p === undefined) return allow();
 
-    // State/mailbox files always writable
-    if (p === `${specDir}/state.yaml` || p === '.claude/ship-hook-state.json') return allow();
+    // State file always writable
+    if (p === `${specDir}/state.yaml`) return allow();
 
     // Per-phase permissions
     const permFn = ORCHESTRATOR_WRITES[phase];
@@ -202,21 +192,44 @@ function main() {
   const input = JSON.parse(readFileSync(0, 'utf-8'));
   let cwd;
   try { cwd = realpathSync(process.cwd()); } catch { cwd = process.cwd(); }
-  const stateFile = join(cwd, '.claude', 'ship-hook-state.json');
   const sessionsDir = join(cwd, '.claude', 'ship-sessions');
   const sessionFile = join(sessionsDir, `${input.session_id}.json`);
 
-  // Detect writes to the shared mailbox — copy content to per-session file
-  if ((input.tool_name === 'Write' || input.tool_name === 'Edit') && input.tool_input) {
-    const targetPath = input.tool_input.file_path;
-    if (targetPath && realResolve(targetPath) === stateFile) {
-      if (input.tool_name === 'Write') {
-        try {
+  // Detect ship-state.js Bash calls — manage per-session state
+  if (input.tool_name === 'Bash' && input.tool_input) {
+    const cmd = input.tool_input.command || '';
+    const match = cmd.match(/ship-state\.js\s+(set|release)/);
+    if (match) {
+      const action = match[1];
+      if (action === 'set') {
+        const phaseMatch = cmd.match(/--phase\s+(\S+)/);
+        const featureMatch = cmd.match(/--feature\s+(\S+)/);
+        const specDirMatch = cmd.match(/--spec-dir\s+(\S+)/);
+        const subPhaseMatch = cmd.match(/--sub-phase\s+(?:"([^"]+)"|(\S+))/);
+        const subPhaseValue = subPhaseMatch ? (subPhaseMatch[1] || subPhaseMatch[2]) : null;
+
+        if (existsSync(sessionFile)) {
+          let state;
+          try { state = JSON.parse(readFileSync(sessionFile, 'utf-8')); } catch { state = {}; }
+          if (phaseMatch) { state.phase = phaseMatch[1]; state.sub_phase = null; }
+          if (featureMatch) state.feature = featureMatch[1];
+          if (specDirMatch) state.spec_dir = specDirMatch[1];
+          if (subPhaseValue) state.sub_phase = subPhaseValue;
+          writeFileSync(sessionFile, JSON.stringify(state, null, 2));
+        } else {
           mkdirSync(sessionsDir, { recursive: true });
-          writeFileSync(sessionFile, input.tool_input.content);
-        } catch {}
+          const state = {
+            phase: phaseMatch ? phaseMatch[1] : null,
+            feature: featureMatch ? featureMatch[1] : null,
+            spec_dir: specDirMatch ? specDirMatch[1] : null,
+            sub_phase: subPhaseValue,
+          };
+          writeFileSync(sessionFile, JSON.stringify(state, null, 2));
+        }
+      } else if (action === 'release') {
+        try { unlinkSync(sessionFile); } catch {}
       }
-      process.exit(0); // Allow the write (Edit is allowed too, per-session file stays slightly stale)
+      process.exit(0);
     }
   }
 

package/src/scripts/ship-state.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+/**
+ * Ship State CLI — manages feature state for the ship skill.
+ *
+ * Commands:
+ *   set --phase <p> --feature <f> --spec-dir <d>   Initial claim or resume
+ *   set --phase <p> --spec-dir <d>                  Phase transition
+ *   set --sub-phase <s>                             Review loop tracking (no-op here, hook handles it)
+ *   release                                         Cleanup sessions directory
+ *
+ * The PreToolUse hook (ship-policy.js) intercepts these Bash calls to manage
+ * per-session state files. This script handles feature-level state (state.yaml).
+ */
+
+const { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync } = require('fs');
+const { join } = require('path');
+
+function parseArgs(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--')) {
+      const key = args[i].slice(2);
+      const val = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : true;
+      flags[key] = val;
+    }
+  }
+  return flags;
+}
+
+const [command, ...rest] = process.argv.slice(2);
+
+if (command === 'set') {
+  const flags = parseArgs(rest);
+
+  // sub-phase only — hook handles per-session state, script is a no-op
+  if (flags['sub-phase'] && !flags.phase && !flags['spec-dir']) {
+    process.exit(0);
+  }
+
+  if (flags['spec-dir'] && flags.phase) {
+    const specDir = flags['spec-dir'];
+    mkdirSync(specDir, { recursive: true });
+
+    const stateFile = join(specDir, 'state.yaml');
+    const existed = existsSync(stateFile);
+    let yaml;
+
+    if (existed) {
+      yaml = readFileSync(stateFile, 'utf-8');
+      yaml = yaml.replace(/^phase:.*$/m, `phase: ${flags.phase}`);
+      if (flags.feature) {
+        yaml = yaml.replace(/^feature:.*$/m, `feature: ${flags.feature}`);
+      }
+    } else {
+      yaml = `feature: ${flags.feature || 'unknown'}\nphase: ${flags.phase}\ndir: ${specDir}\n`;
+    }
+
+    writeFileSync(stateFile, yaml);
+  }
+} else if (command === 'release') {
+  rmSync('.claude/ship-sessions/', { recursive: true, force: true });
+} else {
+  console.error(`Unknown command: ${command}`);
+  process.exit(1);
+}

package/src/scripts/statusline.js

@@ -20,8 +20,8 @@ const { homedir } = require('os');
 
 // Usage API cache
 const USAGE_CACHE_PATH = join(homedir(), '.claude', '.usage-cache.json');
-const USAGE_CACHE_TTL = 45000; // 45 seconds
-const USAGE_HISTORY_MAX = 20; // ~15 min of readings at 45s intervals
+const USAGE_CACHE_TTL = 120000; // 2 minutes
+const USAGE_HISTORY_MAX = 20; // ~40 min of readings at 2min intervals
 
 // Background refresh mode: fetch usage data and write cache, then exit
 if (process.argv.includes('--refresh')) {
@@ -373,6 +373,13 @@ function getUsageData() {
 
   // Trigger background refresh if cache is stale
   if (cacheAge > USAGE_CACHE_TTL) {
+    // Optimistic lock: claim the timestamp so other sessions see fresh cache
+    try {
+      const raw = readFileSync(USAGE_CACHE_PATH, 'utf-8');
+      const cache = JSON.parse(raw);
+      cache.timestamp = Date.now();
+      writeFileSync(USAGE_CACHE_PATH, JSON.stringify(cache));
+    } catch {}
     try {
       const child = spawn(process.execPath, [__filename, '--refresh'], {
         detached: true,

package/src/skills/ship/SKILL.md

@@ -44,27 +44,16 @@ Look for `docs/specs/{feature-name}/state.yaml`.
 | tasks | `references/step-7-tasks.md` |
 | implement | `references/step-8-implement.md` |
 
-Also write/update `.claude/ship-hook-state.json` with `phase`, `feature`, and `spec_dir` from state.yaml (set `sub_phase` to `null`).
+Also run: `node ~/.claude/scripts/ship-state.js set --phase {phase} --feature {feature} --spec-dir {dir}` (using values from state.yaml).
 
 Read the step file for the current phase and follow its instructions.
 
-**If state.yaml does not exist**, this is a new feature. Create the spec directory and an initial state.yaml:
+**If state.yaml does not exist**, this is a new feature. Run:
 
-```yaml
-feature: {feature-name}
-phase: intent
-dir: docs/specs/{feature-name}
 ```
-
-Also write `.claude/ship-hook-state.json` (enables policy enforcement for this session):
-
-```json
-{
-  "phase": "intent",
-  "feature": "{feature-name}",
-  "spec_dir": "docs/specs/{feature-name}",
-  "sub_phase": null
-}
+node ~/.claude/scripts/ship-state.js set --phase intent --feature {feature-name} --spec-dir docs/specs/{feature-name}
 ```
 
+This creates the spec directory, initializes state.yaml, and enables policy enforcement for this session.
+
 Then read `references/step-1-intent.md` to begin.

package/src/skills/ship/references/step-1-intent.md

@@ -45,6 +45,6 @@ Present the intent document to the user for confirmation. Adjust if they have co
 
 ## Task 3: Proceed
 
-Update `{spec_dir}/state.yaml` — set `phase: questions`. Update `.claude/ship-hook-state.json` — set `phase` to `"questions"`, `sub_phase` to `null`.
+Run: `node ~/.claude/scripts/ship-state.js set --phase questions --spec-dir {spec_dir}`
 
 Use the Read tool on `references/step-2-questions.md` to generate research questions from the intent.

package/src/skills/ship/references/step-2-questions.md

@@ -36,6 +36,6 @@ Update `questions.md` based on user feedback. The user may add questions about p
 
 ## Task 3: Proceed
 
-Update `{spec_dir}/state.yaml` — set `phase: research`. Update `.claude/ship-hook-state.json` — set `phase` to `"research"`, `sub_phase` to `null`.
+Run: `node ~/.claude/scripts/ship-state.js set --phase research --spec-dir {spec_dir}`
 
 Use the Read tool on `references/step-3-research.md` to begin objective codebase research.

package/src/skills/ship/references/step-3-research.md

@@ -58,6 +58,6 @@ If the research is thin or missing critical areas, spawn the objective-researche
 
 ## Task 3: Proceed
 
-Update `{spec_dir}/state.yaml` — set `phase: design`. Update `.claude/ship-hook-state.json` — set `phase` to `"design"`, `sub_phase` to `null`.
+Run: `node ~/.claude/scripts/ship-state.js set --phase design --spec-dir {spec_dir}`
 
 Use the Read tool on `references/step-4-design.md` to begin the design discussion with the user.

package/src/skills/ship/references/step-4-design.md

@@ -63,6 +63,6 @@ Present to the user for confirmation.
 
 ## Task 4: Proceed
 
-Update `{spec_dir}/state.yaml` — set `phase: spec`. Update `.claude/ship-hook-state.json` — set `phase` to `"spec"`, `sub_phase` to `null`.
+Run: `node ~/.claude/scripts/ship-state.js set --phase spec --spec-dir {spec_dir}`
 
 Use the Read tool on `references/step-5-spec.md` to generate the implementation specification.

package/src/skills/ship/references/step-5-spec.md

@@ -38,7 +38,7 @@ Agent tool:
 
 ## Task 3: Review Loop
 
-Spawn a FRESH instance of spec-writer in review mode. At least one review is mandatory. Before each review cycle, update `.claude/ship-hook-state.json` `sub_phase` to `"review-cycle-N"` (N = cycle number, starting at 1).
+Spawn a FRESH instance of spec-writer in review mode. At least one review is mandatory. Before each review cycle, run: `node ~/.claude/scripts/ship-state.js set --sub-phase "review-cycle-N"` (N = cycle number, starting at 1).
 
 ```
 Agent tool:
@@ -71,6 +71,6 @@ Revise based on user feedback. If changes are substantial, re-run the review loo
 
 ## Task 5: Proceed
 
-Update `{spec_dir}/state.yaml` — set `phase: verify`. Update `.claude/ship-hook-state.json` — set `phase` to `"verify"`, `sub_phase` to `null`.
+Run: `node ~/.claude/scripts/ship-state.js set --phase verify --spec-dir {spec_dir}`
 
 Use the Read tool on `references/step-6-verify.md` to plan verification for the spec.

package/src/skills/ship/references/step-6-verify.md

@@ -27,7 +27,7 @@ Agent tool:
 
 ## Task 2: Review Loop
 
-Spawn a FRESH instance of test-planner in review mode. At least one review is mandatory. Before each review cycle, update `.claude/ship-hook-state.json` `sub_phase` to `"review-cycle-N"` (N = cycle number, starting at 1).
+Spawn a FRESH instance of test-planner in review mode. At least one review is mandatory. Before each review cycle, run: `node ~/.claude/scripts/ship-state.js set --sub-phase "review-cycle-N"` (N = cycle number, starting at 1).
 
 ```
 Agent tool:
@@ -59,6 +59,6 @@ Ask the user if the verification strategy is complete. Revise based on feedback.
 
 ## Task 4: Proceed
 
-Update `{spec_dir}/state.yaml` — set `phase: tasks`. Update `.claude/ship-hook-state.json` — set `phase` to `"tasks"`, `sub_phase` to `null`.
+Run: `node ~/.claude/scripts/ship-state.js set --phase tasks --spec-dir {spec_dir}`
 
 Use the Read tool on `references/step-7-tasks.md` to break the spec into implementation tasks.

package/src/skills/ship/references/step-7-tasks.md

@@ -25,7 +25,7 @@ Agent tool:
 
 ## Task 2: Review Loop
 
-Spawn a FRESH instance of task-breakdown in review mode. Before each review cycle, update `.claude/ship-hook-state.json` `sub_phase` to `"review-cycle-N"` (N = cycle number, starting at 1):
+Spawn a FRESH instance of task-breakdown in review mode. Before each review cycle, run: `node ~/.claude/scripts/ship-state.js set --sub-phase "review-cycle-N"` (N = cycle number, starting at 1):
 
 ```
 Agent tool:
@@ -55,6 +55,6 @@ Revise based on user feedback. If changes are substantial, re-run the review loo
 
 ## Task 4: Proceed
 
-Update `{spec_dir}/state.yaml` — set `phase: implement`. Update `.claude/ship-hook-state.json` — set `phase` to `"implement"`, `sub_phase` to `null`.
+Run: `node ~/.claude/scripts/ship-state.js set --phase implement --spec-dir {spec_dir}`
 
 Use the Read tool on `references/step-8-implement.md` to begin implementation.

package/src/skills/ship/references/step-8-implement.md

@@ -43,7 +43,7 @@ Run independent tasks (no dependency between them) in parallel when possible. Al
 
 ## Step 3: Finalize
 
-Update `{spec_dir}/state.yaml` — set `phase: complete`. Update `.claude/ship-hook-state.json` — set `phase` to `"complete"`, `sub_phase` to `null`.
+Run: `node ~/.claude/scripts/ship-state.js set --phase complete --spec-dir {spec_dir}`
 
 Present a summary to the user:
 

package/src/skills/ship/references/step-9-reflect.md

@@ -2,7 +2,7 @@
 
 ## Cleanup
 
-Delete `.claude/ship-hook-state.json` and the `.claude/ship-sessions/` directory — policy enforcement is no longer needed for this feature.
+Run: `node ~/.claude/scripts/ship-state.js release` — this cleans up per-session state and the sessions directory.
 
 ## Self-Assessment