@pareto4/pp-core 1.5.0

package/pp-core/bin/verify-reapply-patches.cjs

@@ -0,0 +1,400 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Deterministic verifier for the /gsd-reapply-patches Step 5 "Hunk Verification
+ * Gate". For each backed-up patch file, asserts that the user's added lines
+ * (computed from a real diff against the pristine baseline, not from the
+ * LLM's prose summary) survive into the merged output.
+ *
+ * Usage:
+ *   node scripts/verify-reapply-patches.cjs \
+ *     --patches-dir <path>        \  # gsd-local-patches/
+ *     --config-dir <path>         \  # ~/.claude (or runtime equivalent)
+ *     [--pristine-dir <path>]        # gsd-pristine/; if absent, falls back to
+ *                                    # treating every significant backup line as
+ *                                    # required (over-broad but safe for #2969:
+ *                                    # false-positive halts beat silent successes
+ *                                    # on lost content)
+ *     [--json]                       # emit JSON report instead of human text
+ *
+ * Exit codes:
+ *   0 — every user-added line is present in the merged file (gate passes)
+ *   1 — at least one missing line in at least one file (gate fails)
+ *   2 — usage / structural error (e.g. patches dir missing)
+ *
+ * Bug #2969: the Step 5 gate previously trusted Claude's free-text "verified:
+ * yes/no" reporting per hunk. The LLM was filling in `yes` even when content
+ * had been silently dropped. Moving the check to a deterministic script is the
+ * durability fix.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const SIGNIFICANT_MIN_CHARS = 12;
+const GSD_HOOK_VERSION_LINE_RE = /^(?:\/\/|#)\s*(?:gsd|pp)-hook-version:\s*\S+\s*$/i;
+
+function parseArgs(argv) {
+  const opts = { patchesDir: null, configDir: null, pristineDir: null, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--patches-dir') opts.patchesDir = argv[++i];
+    else if (arg === '--config-dir') opts.configDir = argv[++i];
+    else if (arg === '--pristine-dir') opts.pristineDir = argv[++i];
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '--help' || arg === '-h') {
+      process.stdout.write(
+        'usage: verify-reapply-patches.cjs --patches-dir <path> --config-dir <path> [--pristine-dir <path>] [--json]\n',
+      );
+      throw new ExitError(0);
+    } else {
+      throw new ExitError(2, `unknown argument: ${arg}`);
+    }
+  }
+  return opts;
+}
+
+function isSignificantLine(line) {
+  const trimmed = line.trim();
+  if (trimmed.length < SIGNIFICANT_MIN_CHARS) return false;
+  // Pure punctuation / closing brackets carry too little structural info to
+  // reliably distinguish a survived hunk from incidental similarity.
+  if (/^[\s})\];,]+$/.test(trimmed)) return false;
+  // Generic decorative comments like `// ----` similarly fail the test.
+  if (/^[\s\-=#*/]+$/.test(trimmed)) return false;
+  return true;
+}
+
+function normalizeUpstreamOwnedLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return line;
+  if (GSD_HOOK_VERSION_LINE_RE.test(trimmed)) {
+    const prefix = trimmed.startsWith('#') ? '#' : '//';
+    const marker = trimmed.includes('pp-hook-version') ? 'pp-hook-version' : 'gsd-hook-version';
+    return `${prefix} ${marker}: __VERSION_TOKEN__`;
+  }
+  return line;
+}
+
+/**
+ * Compute the SHA-256 hex digest of a string (UTF-8 encoded).
+ */
+function sha256(content) {
+  return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+}
+
+/**
+ * Read the `pristine_hashes` map from backup-meta.json in the patches dir.
+ * Returns an empty object if backup-meta.json is absent, unreadable, or has no
+ * `pristine_hashes` field — callers must treat an empty map as "no recorded
+ * hash for any file" (no hash-validation possible, not an error).
+ */
+function readPristineHashes(patchesDir) {
+  const metaPath = path.join(patchesDir, 'backup-meta.json');
+  try {
+    const raw = fs.readFileSync(metaPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.pristine_hashes === 'object' && parsed.pristine_hashes !== null) {
+      return parsed.pristine_hashes;
+    }
+  } catch {
+    // absent or unreadable — not an error, just no recorded hashes
+  }
+  return {};
+}
+
+/**
+ * Walk a directory, returning every file's path relative to the root.
+ */
+function walk(rootDir, relPrefix = '') {
+  const out = [];
+  if (!fs.existsSync(rootDir)) return out;
+  for (const entry of fs.readdirSync(rootDir, { withFileTypes: true })) {
+    const rel = relPrefix ? path.join(relPrefix, entry.name) : entry.name;
+    const abs = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...walk(abs, rel));
+    } else if (entry.isFile()) {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+/**
+ * Compute the set of "user-added" lines: lines present in the backup but
+ * absent from the pristine baseline. If no pristine is provided, falls back
+ * to using every significant line in the backup (over-broad but safe — favours
+ * false-positive failures over silent successes, which is the right side to
+ * err on for #2969).
+ */
+function computeUserAddedLines(backupContent, pristineContent) {
+  const backupLines = backupContent.split(/\r?\n/);
+  if (!pristineContent) {
+    return backupLines.filter(isSignificantLine);
+  }
+  const pristineSet = new Set(
+    pristineContent.split(/\r?\n/).map(normalizeUpstreamOwnedLine),
+  );
+  return backupLines.filter((line) => {
+    if (!isSignificantLine(line)) return false;
+    return !pristineSet.has(normalizeUpstreamOwnedLine(line));
+  });
+}
+
+/**
+ * Stable reason codes for the per-file result. Tests assert via
+ * `assert.equal(result.reason, REASON.X)` rather than regex-matching prose,
+ * so the diagnostic surface is a typed enum, not free text.
+ *
+ * Adding a new reason requires updating the REASON map AND the tests'
+ * shape assertion that locks the documented set of codes.
+ */
+const REASON = Object.freeze({
+  OK_NO_USER_LINES_VS_PRISTINE: 'ok_no_user_lines_vs_pristine',
+  OK_NO_SIGNIFICANT_BACKUP_LINES: 'ok_no_significant_backup_lines',
+  // Bug #3657: the on-disk gsd-pristine/ file's SHA-256 does not match the
+  // hash recorded in backup-meta.json.pristine_hashes.  This means the
+  // pristine snapshot was refreshed to a newer GSD version after the backup
+  // was captured.  Using the wrong-version pristine as the diff baseline would
+  // invert the delta (upstream removals appear as "missing user lines").
+  // The verifier skips this file rather than false-failing it.  A separate
+  // re-anchor step (or the git-aware fallback in the workflow) is needed to
+  // resolve this file; the guard here ensures the gate does not report spurious
+  // failures in the meantime.
+  OK_PRISTINE_DRIFT_DETECTED: 'ok_pristine_drift_detected',
+  // Bug #934: backup-meta.json records a pristine_hash for this file but the
+  // gsd-pristine/ file is absent from disk.  This happens on post-#604-rename
+  // installs where saveLocalPatches discarded the only pristine candidate
+  // because its hash did not match the old-release hash (the file changed
+  // upstream between releases).  Without a baseline the verifier cannot
+  // distinguish user-added lines from upstream-changed lines, so falling to
+  // over-broad mode would produce FAIL_USER_LINES_MISSING false positives for
+  // every upstream-removed line.  The correct posture is advisory/non-blocking:
+  // report OK_NO_BASELINE so the caller can log a warning without halting the
+  // gate on a spurious failure.  This is a bounded "cannot reason → do not
+  // block" rather than "ignore everything" — it only applies when the hash was
+  // recorded (modern installer) but the file is absent (specific gap).
+  OK_NO_BASELINE: 'ok_no_baseline',
+  FAIL_INSTALLED_MISSING: 'fail_installed_missing',
+  FAIL_INSTALLED_NOT_REGULAR_FILE: 'fail_installed_not_regular_file',
+  FAIL_READ_ERROR: 'fail_read_error',
+  FAIL_USER_LINES_MISSING: 'fail_user_lines_missing',
+});
+
+function verifyFile({ relPath, patchesDir, configDir, pristineDir, pristineHashes }) {
+  const backupPath = path.join(patchesDir, relPath);
+  const installedPath = path.join(configDir, relPath);
+  const result = { file: relPath, status: 'ok', missing: [], reason: null };
+
+  if (!fs.existsSync(backupPath) || !fs.statSync(backupPath).isFile()) {
+    return result; // walked entry no longer exists — non-fatal
+  }
+
+  // Installed path checks: must exist, must be a regular file, must be
+  // readable. Anything else is a fail-with-diagnostic, not a crash that
+  // aborts the whole gate run and drops structured output.
+  let installedStat;
+  try {
+    installedStat = fs.statSync(installedPath);
+  } catch {
+    result.status = 'fail';
+    result.reason = REASON.FAIL_INSTALLED_MISSING;
+    return result;
+  }
+  if (!installedStat.isFile()) {
+    result.status = 'fail';
+    result.reason = REASON.FAIL_INSTALLED_NOT_REGULAR_FILE;
+    return result;
+  }
+
+  let backupContent;
+  let installedContent;
+  try {
+    backupContent = fs.readFileSync(backupPath, 'utf8');
+    installedContent = fs.readFileSync(installedPath, 'utf8');
+  } catch {
+    result.status = 'fail';
+    result.reason = REASON.FAIL_READ_ERROR;
+    return result;
+  }
+
+  // Normalize to forward slashes so the key lookup matches on Windows
+  // where path.join produces backslash-separated relPath values but
+  // backup-meta.json stores keys written with forward slashes.
+  const hashKey = relPath.replace(/\\/g, '/');
+  const recordedHash = pristineHashes && pristineHashes[hashKey];
+
+  let pristineContent = null;
+  if (pristineDir) {
+    const pristinePath = path.join(pristineDir, relPath);
+    // Bug #934: track whether the pristine path EXISTS on disk (stat did not
+    // throw ENOENT).  A regular file that fails to read, or a non-file path
+    // (e.g. a directory accidentally placed at the pristine path), is treated
+    // as "present but unusable" — we fall to over-broad mode (safe side).
+    // OK_NO_BASELINE is reserved for the strictly absent case: stat throws,
+    // meaning the file was never written (the gap the bug describes).
+    let pristinePathExists = false;
+    try {
+      const stat = fs.statSync(pristinePath);
+      pristinePathExists = true; // path exists (any type)
+      if (stat.isFile()) {
+        const candidate = fs.readFileSync(pristinePath, 'utf8');
+        // Bug #3657: if backup-meta.json recorded a pristine_hash for this
+        // file, validate that the on-disk pristine matches it.  A mismatch
+        // means the installer refreshed gsd-pristine/ to a newer GSD version
+        // after the backup was captured.  Using the wrong-version pristine as
+        // the diff baseline inverts the delta: upstream removals appear as
+        // "user-added lines that must survive", causing FAIL_USER_LINES_MISSING
+        // false positives.  When the hash is stale, skip the pristine and fall
+        // through to over-broad mode (every significant backup line is checked).
+        // Over-broad mode never false-fails for a different reason because all
+        // backup lines that are genuinely user-added will still be present in a
+        // correctly merged install.
+        if (recordedHash) {
+          if (sha256(candidate) === recordedHash) {
+            // Hash matches: the on-disk pristine is the correct baseline.
+            pristineContent = candidate;
+          } else {
+            // Hash mismatch: the on-disk gsd-pristine/ was refreshed to a newer
+            // GSD version after the backup was captured.  Using it as the diff
+            // baseline would invert the delta and produce false FAIL_USER_LINES_MISSING
+            // reports (Bug #3657).  Report the file as ok with a diagnostic code
+            // so the gate does not false-fail; a re-anchor or git-aware baseline
+            // step is required to verify this file correctly.
+            result.reason = REASON.OK_PRISTINE_DRIFT_DETECTED;
+            return result;
+          }
+        } else {
+          // No recorded hash for this file (older installer or absent
+          // backup-meta) — use the on-disk pristine as-is (pre-fix behaviour).
+          pristineContent = candidate;
+        }
+      }
+      // Non-file at pristinePath (e.g. a directory): stat succeeded so
+      // pristinePathExists is true; we fall through to over-broad mode below,
+      // which is safe and conservative.
+    } catch {
+      // Pristine stat threw — path is absent (ENOENT) or inaccessible.
+      // pristinePathExists stays false.
+    }
+
+    // Bug #934: recordedHash is present (modern installer) but the pristine
+    // path does not exist on disk at all (stat threw above).  This means
+    // saveLocalPatches recorded a hash but could not write the corresponding
+    // gsd-pristine/ file (the only candidate was discarded because it was from
+    // a newer release).  Falling to over-broad mode here would treat every
+    // upstream-changed line as a "user-added line that must survive", producing
+    // false FAIL_USER_LINES_MISSING for each upstream removal.  Since we
+    // cannot reason correctly without a baseline, the safe answer is advisory/
+    // non-blocking: return OK_NO_BASELINE and let the caller decide.
+    // NOTE: this guard fires ONLY when stat threw (path absent), not when the
+    // path is present but non-file — in that case over-broad mode is safer.
+    if (!pristinePathExists && recordedHash) {
+      result.reason = REASON.OK_NO_BASELINE;
+      return result;
+    }
+  }
+
+  const userAdded = computeUserAddedLines(backupContent, pristineContent);
+  if (userAdded.length === 0) {
+    // Backup and pristine match exactly (or no significant content) — nothing
+    // to verify but also nothing to lose. Report as ok with diagnostic code.
+    result.reason = pristineContent
+      ? REASON.OK_NO_USER_LINES_VS_PRISTINE
+      : REASON.OK_NO_SIGNIFICANT_BACKUP_LINES;
+    return result;
+  }
+
+  for (const line of userAdded) {
+    if (!installedContent.includes(line)) {
+      result.missing.push(line.trim());
+    }
+  }
+  if (result.missing.length > 0) {
+    result.status = 'fail';
+    result.reason = REASON.FAIL_USER_LINES_MISSING;
+  }
+  return result;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (!opts.patchesDir || !opts.configDir) {
+    throw new ExitError(2, '--patches-dir and --config-dir are required');
+  }
+  if (!fs.existsSync(opts.patchesDir)) {
+    throw new ExitError(2, `patches dir not found: ${opts.patchesDir}`);
+  }
+  if (!fs.existsSync(opts.configDir)) {
+    throw new ExitError(2, `config dir not found: ${opts.configDir}`);
+  }
+
+  const files = walk(opts.patchesDir).filter((f) => !f.endsWith('backup-meta.json'));
+  // Bug #3657: read pristine_hashes from backup-meta.json once and share
+  // across all per-file verifications so each can detect drift independently.
+  const pristineHashes = readPristineHashes(opts.patchesDir);
+  const results = files.map((relPath) =>
+    verifyFile({
+      relPath,
+      patchesDir: opts.patchesDir,
+      configDir: opts.configDir,
+      pristineDir: opts.pristineDir,
+      pristineHashes,
+    }),
+  );
+
+  const failures = results.filter((r) => r.status === 'fail');
+
+  // Bug #3657 (Finding 1): aggregate drifted files into top-level report fields
+  // so workflow Step 5a can gate on drift distinctly from failures.  Drift is
+  // NOT a failure (exit code stays 0) but the workflow now has structured data
+  // to decide whether to proceed.  Per-file shape is unchanged: each drifted
+  // result still has status:'ok' + reason:OK_PRISTINE_DRIFT_DETECTED for
+  // backward compat.  The new top-level fields are purely additive.
+  const driftedResults = results.filter((r) => r.reason === REASON.OK_PRISTINE_DRIFT_DETECTED);
+  const drifted = driftedResults.length;
+  const drifted_files = driftedResults.map((r) => r.file);
+
+  // Bug #934: aggregate no-baseline files into top-level report fields so the
+  // workflow can log a warning about files that could not be verified.  Like
+  // drift, this is NOT a failure (exit code stays 0) but gives the caller
+  // structured data to surface the advisory condition.
+  const noBaselineResults = results.filter((r) => r.reason === REASON.OK_NO_BASELINE);
+  const no_baseline = noBaselineResults.length;
+  const no_baseline_files = noBaselineResults.map((r) => r.file);
+
+  if (opts.json) {
+    process.stdout.write(
+      JSON.stringify({ checked: results.length, failures: failures.length, drifted, drifted_files, no_baseline, no_baseline_files, results }, null, 2) + '\n',
+    );
+  } else {
+    process.stdout.write(`# Hunk Verification Gate (#2969)\n\n`);
+    process.stdout.write(`Checked: ${results.length} file(s)\n`);
+    process.stdout.write(`Failures: ${failures.length}\n\n`);
+    if (failures.length > 0) {
+      process.stdout.write(`## Files with missing user-added content\n\n`);
+      for (const r of failures) {
+        process.stdout.write(`- ${r.file}\n`);
+        if (r.reason) process.stdout.write(`  reason: ${r.reason}\n`);
+        for (const line of r.missing.slice(0, 5)) {
+          process.stdout.write(`  missing: ${line}\n`);
+        }
+        if (r.missing.length > 5) {
+          process.stdout.write(`  …and ${r.missing.length - 5} more line(s)\n`);
+        }
+      }
+    }
+  }
+
+  return failures.length > 0 ? 1 : 0;
+}
+
+if (require.main === module) {
+  runMain(main);
+}
+
+module.exports = { computeUserAddedLines, isSignificantLine, verifyFile, walk, REASON, readPristineHashes, sha256 };

package/pp-core/contexts/dev.md

@@ -0,0 +1,21 @@
+# Dev Context Profile
+
+Agent output guidance for dev mode. Loaded when `context: dev` is set in config.json.
+
+## Output Style
+
+- Concise, action-oriented responses
+- Lead with the code change or command, follow with brief rationale
+- Skip preamble — assume the developer has full context
+- Use inline code references (`file:line`) over prose descriptions
+
+## Focus Areas
+
+- Working code that compiles and passes tests
+- Minimal diff — change only what is necessary
+- Flag side effects or breaking changes immediately
+- Surface the next actionable step at the end of every response
+
+## Verbosity
+
+Low. One-liner explanations unless the change is non-obvious. Omit background theory, alternative approaches, and caveats that do not affect the current task.

package/pp-core/contexts/research.md

@@ -0,0 +1,22 @@
+# Research Context Profile
+
+Agent output guidance for research mode. Loaded when `context: research` is set in config.json.
+
+## Output Style
+
+- Verbose, exploratory responses that surface trade-offs and alternatives
+- Present multiple approaches with pros and cons before recommending one
+- Include links, references, and citations where available
+- Use structured headings and bullet lists for scan-ability
+
+## Focus Areas
+
+- Breadth of options — enumerate before narrowing
+- Prior art and ecosystem conventions
+- Risks, edge cases, and failure modes
+- Dependencies and compatibility implications
+- Long-term maintainability of each approach
+
+## Verbosity
+
+High. Explain reasoning, show evidence, and document assumptions. Include background context even if the developer likely knows it — research artifacts are read by future contributors who may not.

package/pp-core/contexts/review.md

@@ -0,0 +1,23 @@
+# Review Context Profile
+
+Agent output guidance for review mode. Loaded when `context: review` is set in config.json.
+
+## Output Style
+
+- Critical, detail-focused responses that prioritize correctness
+- Organize findings by severity: blocking, important, nit
+- Reference specific lines and files for every finding
+- State what is correct as well as what needs change — confirm the good parts
+
+## Focus Areas
+
+- Correctness — logic errors, off-by-ones, missing edge cases
+- Security — input validation, injection vectors, secret exposure
+- Performance — unnecessary allocations, O(n^2) patterns, missing caching
+- Style and consistency — naming, formatting, import order
+- Test coverage — untested branches, missing assertions, flaky patterns
+- Structural Findings (fallow) — machine-derived cross-module facts injected as `<structural_findings>{ findings: [...], summary: { total, unusedExports, duplicates, circularDependencies } }</structural_findings>`. Render in REVIEW.md under `## Structural Findings (fallow)` as a separate section from narrative findings. Treat as ground truth for cross-module facts; do not re-derive.
+
+## Verbosity
+
+Medium. Be thorough on findings but terse in explanation. Each issue should be one to three sentences: what is wrong, why it matters, and how to fix it.

package/pp-core/references/agent-contracts.md

@@ -0,0 +1,79 @@
+# Agent Contracts
+
+Completion markers and handoff schemas for all GSD agents. Workflows use these markers to detect agent completion and route accordingly.
+
+This doc describes what IS, not what should be. Casing inconsistencies are documented as they appear in agent source files.
+
+---
+
+## Agent Registry
+
+| Agent | Role | Completion Markers |
+|-------|------|--------------------|
+| pp-planner | Plan creation | `## PLANNING COMPLETE` |
+| pp-executor | Plan execution | `## PLAN COMPLETE`, `## CHECKPOINT REACHED` |
+| pp-phase-researcher | Phase-scoped research | `## RESEARCH COMPLETE`, `## RESEARCH BLOCKED` |
+| pp-project-researcher | Project-wide research | `## RESEARCH COMPLETE`, `## RESEARCH BLOCKED` |
+| pp-plan-checker | Plan validation | `## VERIFICATION PASSED`, `## ISSUES FOUND` |
+| pp-research-synthesizer | Multi-research synthesis | `## SYNTHESIS COMPLETE`, `## SYNTHESIS BLOCKED` |
+| pp-debugger | Debug investigation | `## DEBUG COMPLETE`, `## ROOT CAUSE FOUND`, `## CHECKPOINT REACHED` |
+| pp-roadmapper | Roadmap creation/revision | `## ROADMAP CREATED`, `## ROADMAP REVISED`, `## ROADMAP BLOCKED` |
+| pp-ui-auditor | UI review | `## UI REVIEW COMPLETE` |
+| pp-ui-checker | UI validation | `## ISSUES FOUND` |
+| pp-ui-researcher | UI spec creation | `## UI-SPEC COMPLETE`, `## UI-SPEC BLOCKED` |
+| pp-verifier | Post-execution verification | `## Verification Complete` (title case) |
+| pp-integration-checker | Cross-phase integration check | `## Integration Check Complete` (title case) |
+| pp-nyquist-auditor | Sampling audit | `## PARTIAL`, `## ESCALATE` (non-standard) |
+| pp-security-auditor | Security audit | `## OPEN_THREATS`, `## ESCALATE` (non-standard) |
+| pp-codebase-mapper | Codebase analysis | No marker (writes docs directly) |
+| pp-assumptions-analyzer | Assumption extraction | No marker (returns `## Assumptions` sections) |
+| pp-doc-verifier | Doc validation | No marker (writes JSON to `.planning/tmp/`) |
+| pp-doc-writer | Doc generation | No marker (writes docs directly) |
+| pp-advisor-researcher | Advisory research | No marker (utility agent) |
+| pp-user-profiler | User profiling | No marker (returns JSON in analysis tags) |
+| pp-intel-updater | Codebase intelligence analysis | `## INTEL UPDATE COMPLETE`, `## INTEL UPDATE FAILED` |
+
+## Marker Rules
+
+1. **ALL-CAPS markers** (e.g., `## PLANNING COMPLETE`) are the standard convention
+2. **Title-case markers** (e.g., `## Verification Complete`) exist in pp-verifier and pp-integration-checker -- these are intentional as-is, not bugs
+3. **Non-standard markers** (e.g., `## PARTIAL`, `## ESCALATE`) in audit agents indicate partial results requiring orchestrator judgment
+4. **Agents without markers** either write artifacts directly to disk or return structured data (JSON/sections) that the caller parses
+5. Markers must appear as H2 headings (`## `) at the start of a line in the agent's final output
+
+## Key Handoff Contracts
+
+### Planner -> Executor (via PLAN.md)
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Frontmatter | Yes | phase, plan, type, wave, depends_on, files_modified, autonomous, requirements |
+| `<objective>` | Yes | What the plan achieves |
+| `<tasks>` | Yes | Ordered task list with type, files, action, verify, acceptance_criteria |
+| `<verification>` | Yes | Overall verification steps |
+| `<success_criteria>` | Yes | Measurable completion criteria |
+
+### Executor -> Verifier (via SUMMARY.md)
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Frontmatter | Yes | phase, plan, subsystem, tags, key-files, metrics |
+| Commits table | Yes | Per-task commit hashes and descriptions |
+| Deviations section | Yes | Auto-fixed issues or "None" |
+| Self-Check | Yes | PASSED or FAILED with details |
+
+## Workflow Regex Patterns
+
+Workflows match these markers to detect agent completion:
+
+**plan-phase.md matches:**
+- `## RESEARCH COMPLETE` / `## RESEARCH BLOCKED` (researcher output)
+- `## PLANNING COMPLETE` (planner output)
+- `## CHECKPOINT REACHED` (planner/executor pause)
+- `## VERIFICATION PASSED` / `## ISSUES FOUND` (plan-checker output)
+
+**execute-phase.md matches:**
+- `## PHASE COMPLETE` (all plans in phase done)
+- `## Self-Check: FAILED` (summary self-check)
+
+> **NOTE:** `## PLAN COMPLETE` is the pp-executor's completion marker but execute-phase.md does not regex-match it. Instead, it detects executor completion via spot-checks (SUMMARY.md existence, git commit state). This is intentional behavior, not a mismatch.