context-planning 0.7.0

package/lib/worktree.js

@@ -0,0 +1,253 @@
+'use strict';
+
+/**
+ * lib/worktree.js — pure helpers for `cp worktree {create,list,remove}`.
+ *
+ * The cp worktree workflow is intentionally minimal: cp wraps `git worktree`
+ * with sensible defaults (sibling-directory layout, `cp/<slug>` branch name)
+ * and records a row per worktree in `.planning/WORKTREES.md` for traceability
+ * across phases and resumption.
+ *
+ * If the configured workflow provider (default: Superpowers) is installed
+ * AND its `worktree` role resolves to a skill (e.g.
+ * `using-git-worktrees`), `cmdWorktree` in bin/cp.js prints a hand-off
+ * line so the harness knows to invoke that skill. The cp-native behaviour
+ * still runs as a fallback / non-delegated path.
+ *
+ * v0.4.3.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawnSync, execSync } = require('child_process');
+const { planningDir } = require('./paths');
+
+const WORKTREES_FILENAME = 'WORKTREES.md';
+
+/** Conservative slug: lowercase, alphanumeric + hyphen only. */
+function slugify(name) {
+  if (typeof name !== 'string') throw new Error('slugify: name must be a string');
+  const out = name
+    .toLowerCase()
+    .replace(/[_\s]+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+  if (out.length === 0) throw new Error(`slugify: "${name}" produced an empty slug`);
+  return out;
+}
+
+/**
+ * Default sibling location for a worktree: `<parent-of-repo>/<repo-name>-<slug>`.
+ *
+ *   /work/projects/myrepo  → /work/projects/myrepo-cool-feature
+ *
+ * The user can override with --path; this is just the default.
+ */
+function defaultWorktreePath(repoRoot, slug) {
+  const parent = path.dirname(repoRoot);
+  const base = path.basename(repoRoot);
+  return path.join(parent, `${base}-${slug}`);
+}
+
+function defaultBranchName(slug) {
+  return `cp/${slug}`;
+}
+
+/**
+ * Parse the output of `git worktree list --porcelain` into objects:
+ *   { path, head, branch, bare, detached, locked, prunable }
+ *
+ * Tolerates the slight differences in older git versions.
+ */
+function parseGitWorktreeList(raw) {
+  const trees = [];
+  let cur = null;
+  for (const rawLine of raw.split(/\r?\n/)) {
+    const line = rawLine.replace(/\r$/, '');
+    if (line === '') {
+      if (cur) { trees.push(cur); cur = null; }
+      continue;
+    }
+    if (line.startsWith('worktree ')) {
+      if (cur) trees.push(cur);
+      cur = { path: line.slice('worktree '.length), branch: null };
+      continue;
+    }
+    if (!cur) continue;
+    if (line.startsWith('HEAD ')) cur.head = line.slice('HEAD '.length);
+    else if (line.startsWith('branch ')) cur.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '');
+    else if (line === 'bare') cur.bare = true;
+    else if (line === 'detached') cur.detached = true;
+    else if (line.startsWith('locked')) cur.locked = true;
+    else if (line.startsWith('prunable')) cur.prunable = true;
+  }
+  if (cur) trees.push(cur);
+  return trees;
+}
+
+/**
+ * Render the WORKTREES.md registry from an array of `{ path, branch, slug,
+ * phase?, created, notes? }` entries. Stable order: created ascending.
+ */
+function renderWorktreesDoc(entries) {
+  const lines = [
+    '# Worktrees',
+    '',
+    '> cp-managed git worktrees for this project. Use `cp worktree create`',
+    '> to add an entry. Each row pairs a sibling worktree directory with a',
+    '> short slug and (optionally) a phase number for traceability.',
+    '',
+    '| Slug | Branch | Path | Phase | Created | Notes |',
+    '|------|--------|------|-------|---------|-------|',
+  ];
+  const sorted = entries.slice().sort((a, b) => String(a.created).localeCompare(String(b.created)));
+  for (const e of sorted) {
+    lines.push(`| ${e.slug} | ${e.branch} | ${e.path} | ${e.phase || '—'} | ${e.created} | ${e.notes || ''} |`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Parse WORKTREES.md back to an array of registry entries. Tolerates extra
+ * narrative the user added before/after the table.
+ */
+function parseWorktreesDoc(content) {
+  if (typeof content !== 'string' || content.length === 0) return [];
+  const entries = [];
+  for (const line of content.split(/\r?\n/)) {
+    if (!line.startsWith('|')) continue;
+    if (/^\|\s*-+\s*\|/.test(line)) continue; // separator row
+    if (/^\|\s*Slug\s*\|/i.test(line)) continue; // header row
+    const cells = line.split('|').slice(1, -1).map((c) => c.trim());
+    if (cells.length < 5) continue;
+    const [slug, branch, p, phase, created, notes = ''] = cells;
+    if (!slug || slug === '—') continue;
+    entries.push({
+      slug, branch, path: p,
+      phase: phase && phase !== '—' ? phase : null,
+      created, notes,
+    });
+  }
+  return entries;
+}
+
+/** Path to .planning/WORKTREES.md (does not require the file to exist). */
+function worktreesPath(root) {
+  return path.join(planningDir(root), WORKTREES_FILENAME);
+}
+
+/**
+ * Compute the action list to add an entry to .planning/WORKTREES.md.
+ * Returns `{ actions, entry, alreadyPresent }`. Uses the lifecycle.writeBatch
+ * action shape so the caller can scope its commit and atomic-write through
+ * the same pipeline as every other cp lifecycle op.
+ */
+function addRegistryEntry(root, entry) {
+  const p = worktreesPath(root);
+  const existing = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '';
+  const entries = parseWorktreesDoc(existing);
+  const alreadyPresent = entries.some((e) => e.slug === entry.slug);
+  if (!alreadyPresent) entries.push(entry);
+  const after = renderWorktreesDoc(entries);
+  return {
+    actions: [{ kind: 'write', path: p, after, label: 'add-worktree-entry' }],
+    entry,
+    alreadyPresent,
+  };
+}
+
+/**
+ * Compute the action list to remove an entry from .planning/WORKTREES.md by slug.
+ * Returns `{ actions, removed }` where `removed` is the entry that was removed
+ * (or null if no such slug).
+ */
+function removeRegistryEntry(root, slug) {
+  const p = worktreesPath(root);
+  if (!fs.existsSync(p)) return { actions: [], removed: null };
+  const entries = parseWorktreesDoc(fs.readFileSync(p, 'utf8'));
+  const removed = entries.find((e) => e.slug === slug) || null;
+  if (!removed) return { actions: [], removed: null };
+  const remaining = entries.filter((e) => e.slug !== slug);
+  const after = renderWorktreesDoc(remaining);
+  return {
+    actions: [{ kind: 'write', path: p, after, label: 'remove-worktree-entry' }],
+    removed,
+  };
+}
+
+/** Read current registry. Returns an array of entries (possibly empty). */
+function listRegistry(root) {
+  const p = worktreesPath(root);
+  if (!fs.existsSync(p)) return [];
+  return parseWorktreesDoc(fs.readFileSync(p, 'utf8'));
+}
+
+function isoDay(d = new Date()) {
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+
+/**
+ * Shell out to `git worktree add <path> -b <branch> [<from>]`.
+ * Returns the raw spawnSync result (`{ status, stdout, stderr, error }`).
+ * The CLI layer owns printing and exit codes; this function is the only
+ * place where `git worktree add` is invoked.
+ *
+ * v0.4.4 — extracted from bin/cp.js so the shell-out lives next to the rest
+ * of the worktree lib (matches the pattern in lib/lifecycle.js).
+ */
+function runGitWorktreeAdd(root, { worktreePath, branch, from } = {}) {
+  const args = ['worktree', 'add', worktreePath, '-b', branch];
+  if (from) args.push(from);
+  return spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+}
+
+/**
+ * Shell out to `git worktree remove [--force] <path>`. Returns the raw
+ * spawnSync result. v0.4.4.
+ */
+function runGitWorktreeRemove(root, { worktreePath, force } = {}) {
+  const args = ['worktree', 'remove'];
+  if (force) args.push('--force');
+  args.push(worktreePath);
+  return spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+}
+
+/**
+ * Shell out to `git worktree list --porcelain` and parse the output.
+ * Returns an array of `{ path, head, branch, ... }` objects. Swallows
+ * errors (returns `[]`) so callers can use it for best-effort
+ * cross-referencing without crashing in non-git contexts. v0.4.4.
+ */
+function listGitWorktrees(root) {
+  try {
+    const raw = execSync('git worktree list --porcelain', {
+      cwd: root,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).toString();
+    return parseGitWorktreeList(raw);
+  } catch {
+    return [];
+  }
+}
+
+module.exports = {
+  WORKTREES_FILENAME,
+  worktreesPath,
+  slugify,
+  defaultWorktreePath,
+  defaultBranchName,
+  parseGitWorktreeList,
+  renderWorktreesDoc,
+  parseWorktreesDoc,
+  addRegistryEntry,
+  removeRegistryEntry,
+  listRegistry,
+  isoDay,
+  runGitWorktreeAdd,
+  runGitWorktreeRemove,
+  listGitWorktrees,
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "context-planning",
+  "version": "0.7.0",
+  "description": "Lightweight stateful context-management plugin that delegates dev workflow to Superpowers (or any compatible provider).",
+  "bin": {
+    "cp": "bin/cp.js",
+    "cplan": "bin/cp.js"
+  },
+  "files": [
+    "bin",
+    "commands",
+    "install",
+    "lib",
+    "templates",
+    "docs",
+    "README.md"
+  ],
+  "keywords": [
+    "ai",
+    "context",
+    "planning",
+    "milestone",
+    "superpowers",
+    "copilot-cli",
+    "claude-code"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "install:copilot": "node bin/cp.js install copilot",
+    "install:claude": "node bin/cp.js install claude",
+    "doctor": "node bin/cp.js doctor",
+    "test": "node test/roundtrip-gsd.js && node test/dryrun-progress.js && node test/dryrun-complete-milestone.js && node test/dryrun-gsd-import.js && node test/dryrun-resume.js && node test/unit-libs.js && node test/unit-detect.js && node test/unit-merge.js && node test/dryrun-doctor.js && node test/dryrun-config-refresh.js && node test/unit-lifecycle.js && node test/unit-codebase.js && node test/unit-atomic.js && node test/unit-gitcommit.js && node test/unit-v034.js && node test/unit-inbox.js && node test/unit-statusline.js && node test/unit-installers.js && node test/unit-worktree.js && node test/unit-design.js",
+    "coverage": "c8 --reporter=text --reporter=html npm test",
+    "coverage:ci": "c8 --reporter=text --reporter=lcov --reporter=json-summary --check-coverage --lines 85 --branches 75 npm test"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "c8": "^10.1.3"
+  }
+}

package/templates/DESIGN.md

@@ -0,0 +1,78 @@
+---
+# Tier marker: cp scaffold substitutes one of:
+#   phase: "{{PHASE_NUM}}"     (for phase-tier DESIGN.md)
+#   milestone_slug: "{{MILESTONE_SLUG}}"  (for milestone-tier DESIGN.md)
+{{TIER_KEY}}
+milestone: {{MILESTONE_NAME}}
+status: proposed
+created: {{DATE}}
+updated: {{DATE}}
+deciders: []
+supersedes: []
+superseded_by: null
+---
+
+# Design: {{TITLE}}
+
+## Status
+
+{Proposed | Accepted on YYYY-MM-DD | Superseded by …}
+
+## Context
+
+<!-- Forces driving this design: constraints, prior decisions, requirements. -->
+
+## Decision
+
+<!-- What we decided. Short, declarative. -->
+
+## Consequences
+
+### Positive
+-
+
+### Negative
+-
+
+### Neutral
+-
+
+---
+
+## Architecture
+
+<!-- Boxes-and-lines, ASCII diagrams welcome. -->
+
+## Components
+
+<!-- Each unit: name, purpose, public interface, dependencies. -->
+
+## Data Flow
+
+<!-- How data moves through the components. -->
+
+## Error Handling
+
+<!-- Failure modes and recovery. -->
+
+## Testing Strategy
+
+<!-- Unit / integration / e2e split, coverage targets. -->
+
+## Alternatives Considered
+
+### Option A — <name>
+
+**Pros:**
+
+**Cons:**
+
+**Verdict:** rejected because…
+
+## Open Questions
+
+- [ ]
+
+## References
+
+-

package/templates/INBOX.md

@@ -0,0 +1,13 @@
+# Inbox
+
+Quick captures awaiting triage. Use `cp capture "..."` to add an item,
+`cp inbox` to list, and the `/cp-capture` slash command to process them
+interactively (route each to a quick task, phase, seed, or discard).
+
+## Open
+
+<!-- new items get appended here as: `- [ ] [YYYY-MM-DDTHH:mm] <text>` -->
+
+## Triaged
+
+<!-- triaged items move here as: `- [x] [YYYY-MM-DDTHH:mm] → <destination>: <text>` -->

package/templates/MILESTONE-CONTEXT.md

@@ -0,0 +1,40 @@
+# Milestone Context: {{MILESTONE_NAME}}
+
+<!--
+Transient document written by /cp-new-milestone after the workflow provider's
+`brainstorm` skill returns its design. Consumed by /cp-plan-phase and then
+typically deleted (or moved to .planning/milestones/{slug}/) once all phases
+in the milestone are planned.
+
+This is the same name and role as GSD's MILESTONE-CONTEXT.md, so a GSD
+workflow can pick up the same file.
+-->
+
+## Goals
+
+<!-- The specific outcomes this milestone delivers, in the user's words. -->
+
+## In Scope
+
+- {feature/change 1}
+- {feature/change 2}
+
+## Out of Scope
+
+- {explicit exclusion 1} — {why}
+
+## Constraints
+
+- {tech/timeline/compat constraint}
+
+## Proposed Phase Breakdown
+
+<!-- The brainstorm skill's recommended phase split. /cp-new-milestone uses
+     this to populate ROADMAP.md. -->
+
+1. **Phase N: {name}** — {one-line goal}
+2. **Phase N+1: {name}** — {one-line goal}
+
+## Decisions Captured
+
+- {decision} — {rationale}

package/templates/MILESTONES.md

@@ -0,0 +1,29 @@
+# Project Milestones: {{PROJECT_NAME}}
+
+<!-- Entries in reverse chronological order — newest first.
+     Append a block via /cp-complete-milestone. -->
+
+<!-- Template per milestone:
+
+## v[X.Y] [Name] (Shipped: YYYY-MM-DD)
+
+**Delivered:** [One sentence describing what shipped]
+
+**Phases completed:** [X-Y] ([Z] plans total)
+
+**Key accomplishments:**
+- [Major achievement 1]
+- [Major achievement 2]
+- [Major achievement 3]
+
+**Stats:**
+- [X] files created/modified
+- [Y] lines of code (primary language)
+- [Z] phases, [N] plans
+
+**Git range:** `feat(XX-XX)` → `feat(YY-YY)`
+
+**What's next:** [Brief description of next milestone goals]
+
+---
+-->

package/templates/PLAN.md

@@ -0,0 +1,84 @@
+---
+phase: {{PHASE_DIR}}
+plan: {{PLAN_NUM_PADDED}}
+type: execute
+wave: {{WAVE}}
+depends_on: []
+files_modified: []
+autonomous: true
+requirements: []
+user_setup: []
+
+# Goal-backward verification (derived during planning, verified after execution)
+must_haves:
+  truths: []
+  artifacts: []
+  key_links: []
+---
+
+<objective>
+{{OBJECTIVE}}
+
+Purpose: {{PURPOSE}}
+Output: {{OUTPUT}}
+</objective>
+
+<execution_context>
+@.planning/config.json
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+
+<!--
+Only reference prior plan SUMMARYs if genuinely needed:
+  - This plan uses types/exports from prior plan
+  - Prior plan made a decision that affects this plan
+Do NOT reflexively chain summaries together.
+-->
+</context>
+
+<tasks>
+
+<!--
+This section is owned by the workflow provider (configured: {{PROVIDER}},
+plan skill: {{PLAN_SKILL}}). The provider replaces this comment with one
+<task>…</task> block per actionable step. Each task should be 2-5 minutes,
+file-scoped, and have a measurable verify/acceptance criterion.
+
+GSD-compatible task shape:
+
+  <task type="auto">
+    <name>Task N: action-oriented name</name>
+    <files>path/to/file.ext</files>
+    <read_first>path/to/reference.ext</read_first>
+    <action>What to do, with concrete values</action>
+    <verify>Command or check that proves it worked</verify>
+    <acceptance_criteria>
+      - Grep-verifiable condition
+    </acceptance_criteria>
+    <done>Measurable acceptance criteria</done>
+  </task>
+-->
+
+</tasks>
+
+<verification>
+Before declaring plan complete:
+- [ ] {test command}
+- [ ] {build / type check passes}
+- [ ] {behavior verification}
+</verification>
+
+<success_criteria>
+- All tasks completed
+- All verification checks pass
+- No errors or warnings introduced
+- {plan-specific criteria}
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/{{PHASE_DIR}}/{{PHASE_PLAN_PREFIX}}-SUMMARY.md`
+</output>

package/templates/PROJECT.md

@@ -0,0 +1,43 @@
+# {{PROJECT_NAME}}
+
+## What This Is
+
+<!-- 2-3 sentences. What does this product do and who is it for? -->
+
+## Core Value
+
+<!-- The ONE thing that matters most. If everything else fails, this must work. -->
+
+## Requirements
+
+### Validated
+<!-- Shipped and confirmed valuable. Format: `- ✓ {requirement} — {milestone}` -->
+
+(None yet — ship to validate)
+
+### Active
+<!-- Current scope. Building toward these. -->
+
+- [ ] {Requirement 1}
+
+### Out of Scope
+<!-- Explicit boundaries. Always include reasoning. -->
+
+(None yet)
+
+## Context
+
+<!-- Background that informs implementation: stack, prior work, user feedback, known issues. -->
+
+## Constraints
+
+<!-- Hard limits. Format: `- **{Type}**: {What} — {Why}` -->
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| | | |
+
+---
+*Last updated: {{DATE}} after {{TRIGGER}}*

package/templates/REVIEW-LOG.md

@@ -0,0 +1,38 @@
+---
+phase: "{{PHASE_NUM}}"
+milestone: {{MILESTONE_NAME}}
+created: {{DATE}}
+schema_version: 1
+---
+
+# Review Log: Phase {{PHASE_NUM}} — {{TITLE}}
+
+Append-only log of subagent review cycles during execution. Each entry is
+written by the cp-execute-phase orchestrator after a review round
+(spec-compliance or code-quality). The cp aggregator counts entries when
+rolling up the milestone summary.
+
+## How to append
+
+The orchestrator (cp-execute-phase Step 4.5) appends a block per review:
+
+```
+## YYYY-MM-DD HH:MM — Plan NN-MM Task N — <reviewer-role>
+
+**Verdict:** approved | rejected | needs-revision
+
+**Findings:**
+
+- <finding>
+
+**Resolution:**
+
+<what changed; commit SHA if applied>
+
+---
+```
+
+## Entries
+
+<!-- orchestrator appends below this marker; do not delete the marker -->
+<!-- REVIEW-LOG-ENTRIES-BELOW -->

package/templates/ROADMAP.md

@@ -0,0 +1,34 @@
+# Roadmap: {{PROJECT_NAME}}
+
+## Overview
+
+<!-- One paragraph: the journey from here to shipped. -->
+
+## Phases
+
+<!--
+  Milestone heading shape (parsed by lib/milestone.js findMilestoneInRoadmap):
+    ### 🚧 v0.1 — name (In Progress)     (active)
+    ### 📋 v0.2 — name (Planned)          (queued)
+    ### ✅ v0.1 — name (Shipped YYYY-MM-DD) — wraps a <details> block after close-out
+
+  Phase heading shape (must follow a milestone heading):
+    ### Phase 1: name
+    ### Phase 2.1: name    (decimal = urgent insert between integers)
+
+  After /cp-complete-milestone the milestone heading is replaced with a collapsed
+  <details><summary>...</summary>...</details> block; phase headings remain inside.
+
+  Start your first milestone with:
+    cp scaffold-milestone "v0.1 — <your milestone name>"
+    cp scaffold-phase 1 --name "<phase name>" --plans <count>
+-->
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order (decimal phases like 2.1 are urgent inserts between integers).
+
+| Phase | Milestone | Plans Complete | Status | Completed |
+|-------|-----------|----------------|--------|-----------|
+| *(none yet — run `cp scaffold-phase 1 --name <name> --plans <count>`)* | | | | |