create-issflow 1.9.2 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-issflow",
-  "version": "1.9.2",
+  "version": "1.10.0",
   "description": "Scaffold the iStartSoftFlow AI-coding workflow into a project. Stack-agnostic, tool-agnostic (Claude Code, Codex, Cursor, Gemini, Aider), non-destructive.",
   "bin": {
     "create-issflow": "bin/cli.js"

package/template/.issflow/hooks/approval-policy.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+function fail(message) {
+  return { ok: false, reason: message };
+}
+
+function within(root, relative) {
+  if (!relative || path.isAbsolute(relative)) return false;
+  const full = path.resolve(root, relative);
+  return full.startsWith(path.resolve(root) + path.sep);
+}
+
+function read(root, relative) {
+  if (!within(root, relative)) throw new Error('Path escapes repository');
+  return fs.readFileSync(path.join(root, relative), 'utf8');
+}
+
+function gitBlobSha(content) {
+  const bytes = Buffer.from(content, 'utf8');
+  return crypto.createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+}
+
+function activePlan(root, explicit) {
+  if (explicit) return explicit.replaceAll('\\', '/');
+  const pointer = path.join(root, 'docs', 'ACTIVE-PLAN');
+  if (fs.existsSync(pointer)) return fs.readFileSync(pointer, 'utf8').trim();
+  const plansDir = path.join(root, 'docs', 'plans');
+  if (fs.existsSync(plansDir) && fs.readdirSync(plansDir).some((name) => /^PLAN-.*\.md$/i.test(name))) {
+    throw new Error('docs/ACTIVE-PLAN is required when scoped plans exist');
+  }
+  return 'docs/PLAN.md'; // Legacy projects remain supported.
+}
+
+function matchesPath(pattern, relative) {
+  if (pattern.endsWith('/**')) return relative.startsWith(pattern.slice(0, -2));
+  return relative === pattern;
+}
+
+function validate(root, { planFile, changedFiles = [] } = {}) {
+  try {
+    const relativePlan = activePlan(root, planFile);
+    if (!within(root, relativePlan)) return fail('Invalid plan path');
+    const plan = read(root, relativePlan);
+    if (relativePlan === 'docs/PLAN.md') {
+      const match = plan.match(/^>\s*Approval:\s*(.+)$/mi);
+      if (!match || !/^approved\b/i.test(match[1].trim())) return fail('Legacy PLAN.md is not approved');
+      return { ok: true, mode: 'legacy', planFile: relativePlan, warning: 'Legacy approval is not revision-scoped; migrate to docs/plans/' };
+    }
+
+    const id = plan.match(/^#\s+(PLAN-[A-Za-z0-9-]+)\b/m)?.[1];
+    const revision = Number(plan.match(/^>\s*Revision:\s*(\d+)\s*$/mi)?.[1]);
+    if (!id || !Number.isSafeInteger(revision) || revision < 1) return fail('Plan ID or revision missing');
+    const approvalFile = `docs/approvals/${id}.json`;
+    const approval = JSON.parse(read(root, approvalFile));
+    if (approval.planId !== id || approval.revision !== revision) return fail('Approval is for a different plan ID or revision');
+    if (approval.planBlobSha !== gitBlobSha(plan)) return fail('Plan changed after approval; request a new approval');
+    if (!approval.approvedBy || !approval.approvedAt || !approval.approvalSource) return fail('Approval provenance is incomplete');
+    if (!Array.isArray(approval.allowedPaths) || approval.allowedPaths.length === 0 ||
+        !approval.allowedPaths.every((p) => typeof p === 'string' && p.length > 0 && !p.includes('..') && !p.startsWith('/'))) {
+      return fail('Approved path boundaries are missing or invalid');
+    }
+    for (const file of changedFiles) {
+      const normalized = file.replaceAll('\\', '/');
+      if (!within(root, normalized) || !approval.allowedPaths.some((p) => matchesPath(p, normalized))) {
+        return fail(`File outside approved plan scope: ${file}`);
+      }
+    }
+    return { ok: true, mode: 'scoped', planFile: relativePlan, planId: id, revision, approval };
+  } catch (error) {
+    return fail(`Approval verification failed: ${error.message}`);
+  }
+}
+
+module.exports = { validate, gitBlobSha, activePlan, matchesPath };

package/template/.issflow/hooks/plan-gate.js

@@ -1,64 +1,57 @@
 #!/usr/bin/env node
-// PreToolUse plan gate — hard rule 13 as code. While docs/PLAN.md carries
-// `> Approval: PENDING`, no SOURCE file may be created or edited: the plan
-// needs a human sign-off before build work starts. Docs, kit config, and
-// planning artifacts stay writable (planning is exactly what PENDING is for).
-// An active feature lane is exempt — its doc approval is its own rule-13-scoped
-// gate and it never touches the main PLAN. Fail-OPEN on any error: a hook bug
-// must never wedge the tool loop. Pure Node, cross-platform, zero deps.
 'use strict';
-const fs = require('fs');
-const path = require('path');
 
-const silent = () => process.exit(0);
-const deny = (reason) => {
-  process.stdout.write(JSON.stringify({
-    hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason },
-  }));
-  process.exit(0);
-};
-
-let input = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', (d) => (input += d));
-process.stdin.on('end', () => {
-  let evt;
-  try { evt = JSON.parse(input); } catch (_) { return silent(); }
-  try { run(evt); } catch (_) { silent(); }
-});
-
-function run(evt) {
-  const MUTATORS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
-  if (!MUTATORS.has(evt.tool_name || '')) return silent();
-
-  const projectDir = process.env.CLAUDE_PROJECT_DIR || evt.cwd || '.';
-  const read = (f) => { try { return fs.readFileSync(path.join(projectDir, f), 'utf8'); } catch (_) { return null; } };
-
-  const plan = read(path.join('docs', 'PLAN.md'));
-  if (!plan) return silent();                              // no plan world (e.g. /quick-only repo)
-  const approval = plan.match(/^>\s*Approval:\s*(.+)$/m);
-  if (!approval) return silent();                          // not our PLAN format — don't guess
-  if (!/pending/i.test(approval[1])) return silent();      // signed off — build away
+// Claude PreToolUse guard. Shell commands and other hosts require the CLI/CI verifier.
+const path = require('node:path');
+const { validate } = require('./approval-policy');
 
-  // the feature lane carries its own scoped approval and never edits the main PLAN.
-  const state = read(path.join('docs', 'STATE.md')) || '';
-  if (/^\s*feature:\s*\S+\s*\(active\)/m.test(state)) return silent();
+const MUTATORS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
 
-  const file = String((evt.tool_input || {}).file_path || (evt.tool_input || {}).notebook_path || '');
-  if (!file) return silent();
-  const rel = path.relative(projectDir, path.resolve(projectDir, file)).split(path.sep).join('/');
+function deny(reason) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  }) + '\n');
+}
 
-  // writable while PENDING: planning + docs + kit + repo meta — never product source.
-  const ALLOW = [
-    /^docs\//, /^\.issflow\//, /^\.claude\//, /^\.cursor\//, /^\.github\//, /^\.aider/, /^\.git/,
-    /^(README|AGENTS|CLAUDE|GEMINI|CHANGELOG|LICENSE)[^/]*$/i, /^[^/]+\.md$/,
-  ];
-  if (ALLOW.some((re) => re.test(rel))) return silent();
+function safePlanningPath(relative) {
+  return /^docs\/plans\/PLAN-[\w-]+\.md$/.test(relative) ||
+    /^docs\/features\/[\w.-]+\/(PLAN|FEATURE)\.md$/.test(relative) ||
+    relative === 'docs/ACTIVE-PLAN';
+}
 
-  deny(
-    `PLAN-APPROVAL gate (hard rule 13): docs/PLAN.md still reads "> Approval: PENDING", ` +
-    `so source changes are blocked (attempted: ${rel}). Get the plan signed off first — ` +
-    `run /overview's PLAN-APPROVAL step (or /replan, then re-approve) and stamp the header ` +
-    `"> Approval: approved <date> v<n>". Planning artifacts under docs/ stay writable.`
-  );
+function run(event) {
+  if (!MUTATORS.has(event.tool_name)) return;
+  const root = path.resolve(process.env.CLAUDE_PROJECT_DIR || event.cwd || process.cwd());
+  const input = event.tool_input || {};
+  const paths = event.tool_name === 'MultiEdit'
+    ? [input.file_path]
+    : [input.file_path || input.notebook_path];
+  if (paths.some((p) => typeof p !== 'string' || !p.trim())) {
+    return deny('Approval gate cannot determine target path');
+  }
+  const relative = paths.map((p) => path.relative(root, path.resolve(root, p)).split(path.sep).join('/'));
+  if (relative.some((p) => p.startsWith('..') || path.isAbsolute(p))) {
+    return deny('Cannot edit outside repository');
+  }
+  if (relative.every(safePlanningPath)) return;
+  if (relative.some((p) => /^docs\/approvals\//.test(p))) {
+    return deny('Approval records require a separate owner-controlled action');
+  }
+  const result = validate(root, { changedFiles: relative });
+  if (!result.ok) deny(`Plan approval required: ${result.reason}`);
 }
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { raw += chunk; });
+process.stdin.on('end', () => {
+  try {
+    run(JSON.parse(raw));
+  } catch (error) {
+    deny(`Approval gate error: ${error.message}`);
+  }
+});

package/template/.issflow/hooks/verify-approval.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+const path = require('node:path');
+const { validate } = require('./approval-policy');
+
+function main(args) {
+  const root = process.cwd();
+  const baseIndex = args.indexOf('--base');
+  const filesIndex = args.indexOf('--files');
+  const planIndex = args.indexOf('--plan');
+  if (baseIndex !== -1 && filesIndex !== -1) throw new Error('Choose --base or --files');
+  const planFile = planIndex < 0 ? undefined : args[planIndex + 1];
+  let changedFiles = [];
+  if (baseIndex >= 0) {
+    const base = args[baseIndex + 1];
+    if (!base || base.startsWith('--')) throw new Error('Missing --base value');
+    const mergeBase = execFileSync('git', ['merge-base', base, 'HEAD'], { cwd: root, encoding: 'utf8' }).trim();
+    const diff = execFileSync('git', ['diff', '--name-only', '--diff-filter=ACMRT', mergeBase, 'HEAD'], { cwd: root, encoding: 'utf8' });
+    changedFiles = diff.split(/\r?\n/).filter(Boolean);
+  } else if (filesIndex >= 0) {
+    const files = args[filesIndex + 1];
+    if (!files || files.startsWith('--')) throw new Error('Missing --files value');
+    changedFiles = files.split(',').map((f) => f.trim()).filter(Boolean);
+  }
+  const result = validate(root, { planFile, changedFiles });
+  if (!result.ok) {
+    console.error(`BLOCKED: ${result.reason}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`Approval verified: ${result.planId || 'legacy'}${result.revision ? ` revision ${result.revision}` : ''}`);
+  if (result.warning) console.warn(result.warning);
+  console.log(`Checked ${changedFiles.length} changed file(s)`);
+}
+
+try {
+  main(process.argv.slice(2));
+} catch (error) {
+  console.error(`BLOCKED: ${error.message}`);
+  process.exitCode = 1;
+}

package/template/.issflow/istartsoft-flow/METHODOLOGY.md

@@ -44,6 +44,49 @@ coding task.
 
 -----
 
+## Plan-scoped approvals (new work)
+
+For each new task, create one `docs/plans/PLAN-<id>.md` with a unique ID, revision,
+scope, changed-file boundaries, acceptance criteria, tests, and risks. Set
+`docs/ACTIVE-PLAN` to its relative path. One human approval authorizes exactly
+one plan revision, not other plans or future edits to that plan.
+
+Approval is recorded separately in `docs/approvals/PLAN-<id>.json` with
+`planId`, `revision`, `planBlobSha` (Git blob SHA-1 of the exact Markdown),
+`approvedBy`, `approvedAt`, `approvalSource`, and `allowedPaths`.
+The approval record is created only after explicit human consent. Revisions,
+including seemingly small edits, invalidate the old digest and require new approval.
+Do not let an agent self-approve a plan.
+
+Use `node .issflow/hooks/verify-approval.js --base origin/main` to check the
+active plan and changed paths. Run `node --test tests/approval-policy.test.js`
+when those tests are installed. For an existing project with only `docs/PLAN.md`,
+the verifier retains legacy `> Approval: approved ...` compatibility and warns
+that it is not revision-scoped. Migrate intentionally, not by silently rewriting
+existing plans.
+
+**Enforcement boundary:** The Claude PreToolUse hook protects supported file-edit
+tools; it does not intercept shell commands, GitHub API writes, or every Codex
+execution mode. The verifier checks the local checkout/PR diff, but a writable
+approval JSON is not cryptographic proof of the human approver. Require protected
+branches, required CI checks, and an actual human GitHub PR review for merge.
+No tool can treat a self-edited approval file as owner authorization.
+
+**Recovery:** If approval metadata is missing or malformed, stop implementation.
+A human should inspect the plan, restore the correct pointer and approval record,
+then rerun verification. Never bypass the gate by editing `STATE.md` or disabling
+checks. A scoped feature lane does not inherit approval from another plan.
+
+**Engineering:** Prefer feature-based modules and vertical slices. Keep route
+adapters thin; put business rules near their feature. Use idiomatic names,
+cohesive files, explicit contracts, and minimal abstractions. Comments explain
+non-obvious intent, not line-by-line mechanics. Use concise Conventional Commit
+subjects (`feat(scope): change`, `fix(scope): change`); avoid tool signatures
+and promotional boilerplate while preserving truthful Git author/committer
+metadata and any required disclosures.
+
+-----
+
 ## The loop
 
 `design-research -> grill (×2) -> plan -> implement -> test -> deploy`, one

package/template/.issflow/templates/PLAN-SCOPED.md

@@ -0,0 +1,36 @@
+# PLAN-XXXX — Task title
+
+> Revision: 1
+> Status: PENDING
+
+## Goal
+Describe the desired outcome.
+
+## Scope
+- In scope:
+- Out of scope:
+
+## Changed-file boundaries
+List the paths that the owner will approve in the approval record.
+
+## Approach
+1. Research the current implementation.
+2. Implement one vertical slice.
+3. Verify and review the diff.
+
+## Acceptance criteria
+- [ ] Observable behavior with test evidence.
+
+## Tests
+- Unit:
+- Integration:
+- Browser/manual:
+
+## Risks and rollback
+- Risks:
+- Recovery:
+
+## Owner approval
+Do not change source until the owner approves this exact plan revision.
+The approval record must bind the ID, revision, and Git blob hash.
+Merge and deployment require separate authorization.