source-command-review

Use this skill when the user asks to run the migrated source command review.

Command Template

Code Review

Perform a thorough code review of the current changes AND run the cumulative regression suite to ensure all previously built features still work.

Phase 0: Contract Check

Before starting the standard review, check if the most recent contract-bearing plan has a contract:

# Find the most recently modified plan file that actually contains a contract.
# Evidence/proof notes may also live in .codex/plans/ and must not mask the feature plan.
for f in $(ls -t .codex/plans/*.md 2>/dev/null); do
  if rg -q '^## Contract$' "$f"; then
    printf '%s\n' "$f"
    break
  fi
done

If a plan file exists, read its ## Contract section. If a contract is found:

1. Note the tier and criteria in the review output
2. After Phase 3 (Code Review), add a Phase 3.5: Contract Evaluation that spawns a fresh sub-agent to grade the implementation against the contract (see /evaluate for the full evaluator protocol)
3. Include the contract evaluation results in the final output

If no contract exists, skip this and proceed normally. The contract evaluation is additive — it does not replace the standard code review phases.

Phase 0.5: Database Migration Check

This project uses SQLite via better-sqlite3 with schema migrations gated on the user_version pragma (see src/core/db/database.ts). There is no separate migration tool — migrations apply at runtime when getDatabase() is called.

Step 1: Check for schema drift

# Check whether the schema file was modified without bumping SCHEMA_VERSION
git diff HEAD --name-only -- 'src/core/db/schema.ts' 'src/core/db/types.ts' 2>/dev/null
git diff HEAD -- 'src/core/db/schema.ts' | grep -E '^\+.*SCHEMA_VERSION' 2>/dev/null

If src/core/db/schema.ts was modified (new tables, columns, or constraints) but SCHEMA_VERSION was NOT incremented, flag as Critical — existing databases will not pick up the change. The fix is:

1. Bump SCHEMA_VERSION by 1 in src/core/db/schema.ts
2. Add an if (fromVersion < N) block to the migrate() function in src/core/db/database.ts
3. Put the ALTER TABLE or CREATE TABLE statements in the new block
4. Update src/core/db/types.ts to match the new columns

Step 2: Apply migrations

Migrations apply automatically on database open. To verify a fresh init works with the current schema:

rm -rf .blog-agent/
npx tsc -p . && node dist/cli/index.js init

If this fails, flag as Critical.

Phase 1: Regression Suite

Run these tests FIRST to verify that all previously shipped features are intact. This suite grows with every feature — when you ship a feature, add its tests here. If any fail, flag them as Critical and investigate before proceeding with the code review.

# Run all regression suite tests
npx vitest run \
  tests/db.test.ts \
  tests/config.test.ts \
  tests/import.test.ts \
  tests/ideas.test.ts \
  tests/content-types.test.ts \
  tests/cli.test.ts \
  tests/db-migration.test.ts \
  tests/research-state.test.ts \
  tests/research-sources.test.ts \
  tests/research-document.test.ts \
  tests/research-cli.test.ts \
  tests/research-set-section.test.ts \
  tests/research-project-linking.test.ts \
  tests/benchmark-environment.test.ts \
  tests/benchmark-state.test.ts \
  tests/benchmark-results.test.ts \
  tests/benchmark-companion.test.ts \
  tests/benchmark-cli.test.ts \
  tests/benchmark-repair-cli.test.ts \
  tests/draft-frontmatter.test.ts \
  tests/draft-state.test.ts \
  tests/draft-benchmark-data.test.ts \
  tests/draft-tags.test.ts \
  tests/draft-cli.test.ts \
  tests/draft-regenerate-frontmatter.test.ts \
  tests/evaluate-reviewer.test.ts \
  tests/evaluate-autocheck.test.ts \
  tests/evaluate-synthesize.test.ts \
  tests/evaluate-report.test.ts \
  tests/evaluate-state.test.ts \
  tests/evaluate-cli.test.ts \
  tests/publish-state.test.ts \
  tests/publish-pipeline.test.ts \
  tests/publish-convert.test.ts \
  tests/publish-table-assets.test.ts \
  tests/publish-site.test.ts \
  tests/publish-crosspost.test.ts \
  tests/platform-images.test.ts \
  tests/publish-social.test.ts \
  tests/distribution-kit.test.ts \
  tests/publish-distribution-kit.test.ts \
  tests/publish-research-page.test.ts \
  tests/publish-repo.test.ts \
  tests/publish-cli.test.ts \
  tests/publish-site-updates.test.ts \
  tests/publish-origin-divergence.test.ts \
  tests/publish-seed-on-start.test.ts \
  tests/publish-verify-artifacts.test.ts \
  tests/preview-gate-urls.test.ts \
  tests/db-migration-v3.test.ts \
  tests/update-cycles.test.ts \
  tests/update-notice.test.ts \
  tests/update-cli.test.ts \
  tests/update-devto.test.ts \
  tests/update-publish-pipeline.test.ts \
  tests/publish-guard.test.ts \
  tests/unpublish-state.test.ts \
  tests/unpublish-cli.test.ts \
  tests/unpublish-readme.test.ts \
  tests/unpublish-site.test.ts \
  tests/unpublish-devto.test.ts \
  tests/unpublish-pipeline.test.ts \
  tests/skills-crossref.test.ts \
  tests/guidance-docs.test.ts \
  tests/review-inventory.test.ts \
  tests/update-runner-pipeline.test.ts \
  tests/cross-flow-lock.test.ts \
  tests/frontmatter-phase7.test.ts \
  tests/origin-guard.test.ts \
  tests/pipeline-registry-integrity.test.ts \
  tests/paths.test.ts \
  tests/cli-templates-cwd-independence.test.ts \
  tests/build-bin-executable.test.ts \
  tests/voice-parity.test.ts \
  tests/workspace-root.test.ts \
  tests/cli-json.test.ts \
  tests/plan-file.test.ts \
  tests/skill-smoke.test.ts \
  tests/skill-fixture-integration.test.ts

What each test covers

Phase 1 — Foundation (feature/phase-1-foundation)

Phase 2 — Research (feature/phase-2-research)

Phase 3 — Benchmark (feature/phase-3-benchmark)

Phase 4 — Draft (feature/phase-4-draft)

Phase 5 — Evaluate (feature/phase-5-evaluate)

Phase 6 — Publish (feature/phase-6-publish)

Phase 7 — Lifecycle (feature/phase-7-lifecycle)

Release Prep (feature/release-prep-v0-1)

Ships the v0.1.0-readiness bundle: a shared package-root resolver that fixes a latent CWD-relative template-loading bug, a four-layer packaging gate (verify-pack.mjs), clean build (rm -rf dist && tsc), adversarially-reviewed release runbook, and CI. Validated against a Tier-2 contract with seven adversarial passes (1 Claude evaluator + 6 Codex GPT-5.5 high passes — final verdict clean / approve).

/blog Skill Plugin (feature/blog-skill-plugin)

Ships the /blog Claude Code plugin + blog agent CLI subcommand family. Single skill with SHA256-bound plan artifacts as the structural safety boundary; destructive execution only via blog agent apply.

v0.3 Dogfood Hardening (feature/v0.3.0-dogfood-hardening)

Five connected fixes surfaced by the first live dogfood run of blog publish: project-launch posts now require a resolvable project ID at research-init, generateFrontmatter resolves companion_repo from config.projects[id] + git origin, createSitePR refuses when local main is ahead of origin/main, runPublishStart always seeds pipeline_steps, the preview-gate surfaces canonical/supplementary/companion URLs in its JSON envelope, and a new blog draft regenerate-frontmatter recovery command rewrites the local draft from the current post+config. See CHANGELOG.md § 0.3.0 for the full accounting.

Source files these tests protect

• src/core/db/schema.ts — SQL schema for all 8 tables, SCHEMA_VERSION constant
• src/core/db/database.ts — getDatabase, closeDatabase, migration logic, WAL + foreign keys
• src/core/db/types.ts — Row interfaces, ContentType/Phase/Mode/etc. enums
• src/core/config/loader.ts — loadConfig, validateConfig, path resolution, defaults
• src/core/config/types.ts — BlogConfig and subsection interfaces
• src/core/migrate/import-posts.ts — importPosts with frontmatter parsing and content_dir parameter
• src/core/draft/content-types.ts — detectContentType, BENCHMARK_KEYWORDS list
• src/cli/index.ts — Commander.js entry point, command registration
• src/cli/init.ts — runInit with injectable baseDir, subdirectory + DB + template copy
• src/cli/status.ts — runStatus with formatted table output
• src/cli/metrics.ts — runMetrics, computeMetrics with aggregate queries
• src/cli/ideas.ts — addIdea/listIdeas/startIdea/removeIdea, YAML persistence
• src/cli/research.ts — runResearchInit/runResearchAddSource/runResearchShow/runResearchFinalize/runResearchSetSection, slug validation, phase boundary
• src/core/research/state.ts — initResearchPost, getResearchPost, advancePhase, phase boundary enforcement
• src/core/research/sources.ts — addSource, listSources, countSources, phase boundary enforcement
• src/core/research/document.ts — writeResearchDocument, readResearchDocument, validateResearchDocument, setResearchSection + SECTION_KEYS const, validateSlug, path traversal guard
• src/cli/benchmark.ts — runBenchmarkInit/runBenchmarkEnv/runBenchmarkRun/runBenchmarkShow/runBenchmarkSkip/runBenchmarkComplete/runBenchmarkRepair, BenchmarkPaths, slug validation, phase boundary
• src/core/benchmark/environment.ts — captureEnvironment, formatEnvironmentMarkdown
• src/core/benchmark/state.ts — initBenchmark, getBenchmarkPost, skipBenchmark, completeBenchmark, repairBenchmarkResults, repairSkipOptionalBenchmark, createBenchmarkRun, updateBenchmarkStatus, listBenchmarkRuns, getBenchmarkRequirement
• src/core/benchmark/results.ts — input/canonical result parsing, canonicalizeBenchmarkResults, writeResults, readResults, readBenchmarkSummary, writeEnvironment, readEnvironment, slug validation
• src/core/benchmark/companion.ts — scaffoldCompanionRepo, writeMethodology, template rendering
• templates/benchmark/methodology.md — METHODOLOGY.md scaffold template
• src/cli/draft.ts — runDraftInit/runDraftShow/runDraftValidate/runDraftAddAsset/runDraftComplete, DraftPaths, slug validation, phase boundary
• src/core/draft/frontmatter.ts — PostFrontmatter schema, generateFrontmatter, validateFrontmatter, serializeFrontmatter, parseFrontmatter
• src/core/draft/state.ts — getDraftPost, initDraft, completeDraft, registerAsset, listAssets, PLACEHOLDER_PATTERN
• src/core/draft/benchmark-data.ts — formatBenchmarkTable, formatMethodologyRef, getBenchmarkContext (config-driven githubUser)
• src/core/draft/tags.ts — readExistingTags with graceful fallback
• src/core/draft/template.ts — renderDraftTemplate, content-type-aware sections
• src/cli/evaluate.ts — runEvaluateInit/runEvaluateAutocheck/runEvaluateRecord/runEvaluateShow/runEvaluateSynthesize/runEvaluateComplete/runEvaluateReject, EvaluatePaths, slug validation, phase boundary
• src/core/evaluate/reviewer.ts — Issue/ReviewerOutput types, normalizeText, issueFingerprint, validateReviewerOutput, parseReviewerOutput
• src/core/evaluate/autocheck.ts — runStructuralAutocheck (deterministic lints: frontmatter, placeholders, broken links, MDX parse, benchmark claims, companion repo)
• src/core/evaluate/synthesize.ts — tokenize, jaccardSimilarity, matchIssues, categorize, computeVerdict, synthesize, JACCARD_THRESHOLD
• src/core/evaluate/report.ts — renderSynthesisReport
• src/core/evaluate/state.ts — getEvaluatePost, expectedReviewers, initEvaluation, recordReview, runSynthesis, completeEvaluation, rejectEvaluation, phase boundary enforcement
• skills/blog-evaluate.md — three-reviewer workflow, Codex CLI invocation templates, degraded-mode fallback
• .claude/commands/evaluate.md, .claude/commands/plan-feature.md, .claude/commands/review.md, .agents/skills/source-command-evaluate/SKILL.md, .agents/skills/source-command-plan-feature/SKILL.md, .agents/skills/source-command-review/SKILL.md, .windsurf/workflows/review.md — command guidance protected by tests/guidance-docs.test.ts
• .claude/rules/drafting.md, .codex/rules/drafting.md, .claude/rules/lifecycle.md, .codex/rules/lifecycle.md, .claude/rules/release.md, .codex/rules/release.md, .codex/rules/testing.md — cross-surface rule guidance for frontmatter, Dev.to API contracts, fallback keys, and review-suite registration
• src/cli/publish.ts — runPublishStart/runPublishShow, PublishCliPaths, slug validation, phase dispatch (evaluate→promote, publish→resume), ctx.urls hydration from posts row
• src/core/publish/types.ts — PUBLISH_STEP_NAMES 11-tuple (authoritative ordering), PublishStepName/PublishStepStatus enums, PipelineStepRow, PublishUrls, PublishPaths, PostRow re-export
• src/core/publish/lock.ts — acquirePublishLock (O_CREAT|O_EXCL + PID stamp, stale-PID reclaim via process.kill(pid,0), empty/garbage lockfile reclaim, Atomics.wait spin, release is idempotent)
• src/core/publish/phase.ts — getPublishPost, initPublishFromEvaluate, initPublish, completePublish, completePublishUnderLock (no lock re-entry, idempotent on published, runtime lock-ownership guardrail: reads lockfile + verifies PID matches process.pid), persistPublishUrls (COALESCE first-writer-wins)
• src/core/publish/steps-crud.ts — createPipelineSteps (content-type + config pre-skips), getNextPendingStep, markStepRunning/Completed/Failed/Skipped, getPipelineSteps, allStepsComplete, reclaimStaleRunning (crash-safety), reconcilePipelineSteps (resume-time re-application of config-driven skips so optional destinations can be disabled between runs)
• src/core/publish/convert.ts — mdxToMarkdown, stripFrontmatter, removeImports, removeJsxComponents, resolveAssetUrls, fence-aware state machine with nested-backtick handling
• src/core/publish/table-assets.ts — deterministic Markdown table detection, portable table PNG rendering, stale generated table cleanup, manifest metadata
• src/core/publish/platform-copy.ts — natural platform copy fitting, abrupt-ellipsis detection, and shared character budgets for LinkedIn/Substack copy surfaces
• src/core/publish/research-page.ts — generateResearchPage (reads thesis/findings/bibliography from research doc + benchmark summary from results.json; description from draft frontmatter; skips analysis-opinion without artifacts)
• src/core/publish/platform-images.ts — ensurePlatformImages, platform specs, safe asset resolver, local Sharp transforms, deterministic fallback SVG, receipt/frontmatter updates
• src/core/publish/site.ts — createSitePR (dirty-state guardrail with rename/copy-aware porcelain parsing + path-scoped staging: content/posts/{slug} + optional content/research/{slug}, no git add .), checkPreviewGate, resolveSiteRepoPath, git/gh subprocess wrappers (execFileSync only)
• src/core/publish/devto.ts — crosspostToDevTo, probeDevToForCanonical (paginated GET + canonical match + trailing-slash normalization), mapDevToTags
• src/core/publish/medium.ts — generateMediumPaste (H1 title + canonical footer)
• src/core/publish/substack.ts — generateSubstackPaste (H1 title + H2 subtitle layout)
• src/core/publish/repo.ts — pushCompanionRepo (gh repo view probe → gh repo create --source=. --push, with "already exists" race fallback), parseGitHubRemoteUrl helper (SSH/HTTPS normalization), assertOriginMatches (trust-boundary guardrail: throws when local origin does not match expected {author.github}/{slug})
• src/core/publish/frontmatter.ts — updateFrontmatter (direct push to main, chore(post): prefix, checkout-before-mutation ordering, assertIndexClean precheck against operator-staged files, inspectAheadCommits helper with strict subject + file match for crash-replay push-ahead)
• src/core/publish/readme.ts — updateProjectReadme (direct push to main, chore: prefix, config.projects[id] resolved against dirname(configPath), checkout-before-mutation ordering, shared assertIndexClean guardrail, strict crash-replay push-ahead via shared inspectAheadCommits)
• src/core/publish/social.ts — generateSocialText, generateLinkedIn, generateHackerNews, containsEmoji (throws on emojis in generated output)
• src/core/publish/pipeline-types.ts — PipelineContext, StepOutcome, StepResult, StepDefinition
• src/core/publish/pipeline-registry.ts — PIPELINE_STEPS array (ordered 11 step-to-module bindings, translates module results to StepResult)
• src/core/publish/pipeline-runner.ts — runPipeline (acquires lock, reclaims stale running, reconciles pending rows against current config, executes steps in order, per-step transactional URL persistence, calls completePublishUnderLock without lock re-entry)
• templates/research-page/template.mdx — research page scaffold with {{thesis}}, {{findings}}, {{bibliography}}, {{methodology_summary}}, {{open_questions}}, {{repo_link}} placeholders
• templates/social/linkedin.md — LinkedIn template with {{hook}}, {{body}}, {{canonical_url}}, {{hashtags}}, {{timing}} placeholders
• templates/social/hackernews.md — HN template with {{title}}, {{canonical_url}}, {{first_comment}}, {{repo_url}}, {{timing}} placeholders
• skills/blog-publish.md — publish workflow narration, 11-step descriptions, manual preview-gate at step 4, resume semantics, troubleshooting (missing DEVTO_API_KEY, gh auth, PR not merged)

Phase 7 — Lifecycle source files:

• src/core/db/schema.ts — SCHEMA_VERSION=3, SCHEMA_V3_SQL (pipeline_steps canonical table-rebuild adding cycle_id + UNIQUE(post_slug, cycle_id, step_name)), update_cycles + unpublish_steps tables, partial-unique-index idx_update_cycles_open
• src/core/db/database.ts — v3 migration block with FK-off toggle around transactional rebuild
• src/core/db/types.ts — UpdateCycleRow, UnpublishStepRow, UpdateCycleEndedReason types
• src/core/publish/types.ts — UPDATE_STEP_NAMES tuple, PublishMode union, stepNamesForMode() helper, cycle_id on PipelineStepRow
• src/core/publish/pipeline-types.ts — PipelineContext.publishMode + .cycleId + .lockTimeoutMs (test-only)
• src/core/publish/pipeline-runner.ts — mode-aware finalization (completePublishUnderLock vs completeUpdateUnderLock); passes ctx.lockTimeoutMs through to acquirePublishLock
• src/core/publish/pipeline-registry.ts — mode-aware verify step (checks evaluation_passed for initial, is_update_review + cycle timing for update); site-update step entry; updateDevToArticle dispatch for update mode
• src/core/publish/phase.ts — finalizePipelineUnderLock shared PID-ownership helper, completeUpdateUnderLock (closes update_cycles row, increments update_count, writes update_completed metric, phase stays published); completeUnpublishUnderLock wired in via state.ts
• src/core/publish/steps-crud.ts — every CRUD function gained trailing optional cycleId: number = 0 and publishMode: PublishMode = 'initial' parameters; createPipelineSteps seeds step_number from tuple position per mode
• src/core/publish/site.ts — createSitePR calls requireOriginMatch(expectedSiteCoords(config)); accepts SitePROverrides; checkPreviewGate also guards origin
• src/core/publish/site-update.ts — createSiteUpdate wraps createSitePR with update-cycle-scoped branch/commit/PR strings derived from update_cycles row
• src/core/publish/devto.ts — updateDevToArticle probe-then-PUT with POST fallthrough on probe miss
• src/core/publish/origin-guard.ts — SHARED trust-boundary module: parseGitHubRemoteUrl, getOriginState (tolerant), requireOriginMatch (strict), expectedSiteCoords (config-driven coords resolver), coordsMatch case-insensitive helper, readOriginUrl with LC_ALL=C locale pin and narrowed stderr catch
• src/core/config/types.ts — SiteConfig.github_repo optional, SiteUpdateMode, UnpublishConfig, extended UpdatesConfig (devto_update, refresh_paste_files, notice_template, require_summary, site_update_mode)
• src/core/config/loader.ts — DEFAULT_UNPUBLISH, extended DEFAULT_UPDATES, github_repo shape validation (owner/name)
• src/core/update/cycles.ts — openUpdateCycle / getOpenUpdateCycle / closeUpdateCycle / listUpdateCycles / requirePublishedPost; metrics writes inside transactions ('update_opened', 'update_aborted', 'update_completed')
• src/core/update/notice.ts — appendUpdateNotice with cycle-keyed HTML comment regex, atomic temp+rename write
• src/cli/update.ts — runUpdateStart/Benchmark/Draft/Evaluate/Publish/Abort/Show + registerUpdate(program); slug validation + phase boundary + process.exitCode=1 pattern; passes { isUpdateReview: true } to initEvaluation
• src/core/unpublish/state.ts — initUnpublish with already-unpublished idempotency, completeUnpublishUnderLock via shared finalizePipelineUnderLock; writes 'unpublish_started' + 'unpublished' metrics
• src/core/unpublish/steps-crud.ts — parallel to publish/steps-crud but no cycle_id (unpublish has only one pass per post)
• src/core/unpublish/steps-registry.ts — UNPUBLISH_STEP_NAMES 7-tuple
• src/core/unpublish/runner.ts — mirrors publish runner; uses acquirePublishLock for mutual exclusion; accepts optional lockTimeoutMs (test-only injection seam)
• src/core/unpublish/devto.ts — PUT { article: { published: false } } per spike, probe-then-mutate, probe-miss is skip not error
• src/core/unpublish/medium.ts / src/core/unpublish/substack.ts — manual-removal instruction markdown generators (no API)
• src/core/unpublish/site.ts — createSiteRevertPR (PR-only, no direct-push grep-verified); flipPublishedToFalse; checkUnpublishPreviewGate; calls requireOriginMatch(expectedSiteCoords(config)) before any push
• src/core/unpublish/readme.ts — revertProjectReadmeLink with THREE explicit skip paths; assertIndexClean before git add + requireOriginMatch before git push origin main (Phase 6 symmetry documented in lifecycle.md)
• src/cli/unpublish.ts — runUnpublishStart --confirm / runUnpublishShow, slug validation, --confirm required before any DB/network work
• src/cli/publish.ts — publish guard: refuses on open update cycle, actionable error message
• src/core/draft/frontmatter.ts — PostFrontmatter interface extended with unpublished_at, updated_at, update_count, substack_url; serializer + parser round-trip, with update_count normalized to number even when YAML emits string
• src/core/evaluate/state.ts — initEvaluation({ isUpdateReview: true }) option sets manifest is_update_cycle=true; recordReview reads the flag and sets is_update_review=1 on every inserted row (explicit, not inferred from cycles.length)
• fixtures/frontmatter-phase7/*.mdx — 6 canonical Phase 7 frontmatter shapes (legacy, initial-published, updated-once, updated-twice, unpublished, updated-then-unpublished) + README documenting the cross-repo contract between m0lz.01 and m0lz.00
• skills/blog-pipeline.md / skills/blog-update.md / skills/blog-unpublish.md — orchestrator skills with exact H2 set {Preflight, Workflow, CLI Reference, Troubleshooting, Degraded Mode}; cross-checked mechanically against src/cli/index.ts registrations
• .codex/rules/lifecycle.md — path-scoped rule doc: publishMode dispatch, first-class update_cycles rows, partial-unique-index constraint, explicit isUpdateReview flag, cycle-keyed notice marker, publish guard, shared per-slug lock, shared finalize helper, metrics audit log, unpublish trust boundaries, origin-guard tolerant/strict APIs, readme-revert direct-push policy clarification
• docs/spikes/forem-put-semantics.md — canonical source for Forem PUT body shapes (unpublish + update), referenced by devto.ts implementations

v0.3 Dogfood Hardening source files:

• src/core/draft/content-types.ts — extractProjectIdFromPrompt helper (generic catalog-style /\b([a-z][a-z0-9]*\.\d+)\b/i regex, lowercased first match)
• src/core/research/state.ts — initResearchPost accepts trailing optional projectId parameter, inserts into posts.project_id, throws [AGENT_ERROR] PROJECT_UNLINKED when contentType is project-launch and projectId is null/empty
• src/cli/research.ts — runResearchInit resolves projectId via --project flag → prompt-regex fallback → null, threads into initResearchPost; --project <id> Commander option registered
• src/core/draft/frontmatter.ts — generateFrontmatter(post, config, configPath) resolves companion_repo via resolveCompanionRepoFromProject (reads git origin of config.projects[post.project_id], normalizes to canonical HTTPS, best-effort on failure); falls back to has_benchmarks heuristic only when project resolution is null
• src/core/draft/state.ts — initDraft threads configPath through to generateFrontmatter; regenerateDraftFrontmatter exported (rewrites frontmatter block in place preserving body byte-for-byte, rejects phase=published, writes .frontmatter-regenerated.json audit receipt)
• src/core/publish/origin-guard.ts — readOriginUrl + parseGitHubRemoteUrl exported for reuse; assertOriginInSync(repoPath, branch) fetches + runs rev-list --count origin/<branch>..<branch> and throws [AGENT_ERROR] ORIGIN_OUT_OF_SYNC on non-zero ahead count or "couldn't find remote ref" fetch error
• src/core/publish/site.ts — SitePROverrides.allowMainAhead optional flag; createSitePR calls assertOriginInSync before mutations unless override set, emits [WARN] site-pr: --allow-main-ahead bypassed origin sync check on bypass; checkPreviewGate takes db parameter and returns PreviewGateResult extends PreviewUrls
• src/core/publish/preview-urls.ts — new module: PreviewUrls type + computePreviewUrls(post, config, configPath, researchPagesDir) helper (canonicalUrl always emitted, supplementaryUrl from research-pages file existence, companionRepoUrl prefers post.repo_url then config.projects origin lookup)
• src/core/publish/pipeline-registry.ts — site-pr step passes allowMainAhead from ctx; preview-gate step includes preview URLs in data
• src/core/publish/pipeline-types.ts — PipelineContext.allowMainAhead optional field
• src/cli/publish.ts — runPublishStart removes phase-conditional skip of initPublish (now called for both evaluate and publish phases); logs seeded N pipeline_steps for <slug> when insertion occurs; rejects phase=published with actionable error; --allow-main-ahead Commander option registered; tryLoadPreviewUrls helper surfaces data.preview_urls in the PublishPipeline JSON envelope
• src/cli/draft.ts — runDraftRegenerateFrontmatter CLI handler + Commander regenerate-frontmatter <slug> registration
• src/core/plan-file/schema.ts — 'blog draft regenerate-frontmatter' added to SLUG_BEARING_STEP_COMMANDS (inherits KNOWN_LEAF_COMMANDS via spread)
• .claude-plugin/skills/blog/JOURNEYS.md — Journey E added (frontmatter-recovery pattern)
• .claude-plugin/skills/blog/REFERENCES.md — Draft-frontmatter recovery section documenting regenerate-frontmatter semantics

Release Prep source files:

• src/core/paths.ts — shared package-root resolver: findPackageRoot(moduleUrl) walks up from a module URL until it finds a package.json, PACKAGE_ROOT = the package directory computed eagerly at module load via import.meta.url, TEMPLATES_ROOT = resolve(PACKAGE_ROOT, 'templates'). Every template-reading code path in the repo routes through one of these two constants — no inline fileURLToPath / offset-arithmetic incantations remain
• src/cli/init.ts — hard-fail on missing shipped example files (.blogrc.example.yaml / .env.example) with diagnostic pointing at a packaging bug; packageRoot is an injectable third parameter (defaults to PACKAGE_ROOT) so regression tests can exercise the hard-fail path via a tmpdir without monkey-patching the module
• src/cli/publish.ts / src/cli/update.ts — use TEMPLATES_ROOT for package-shipped template reads; all .blog-agent/... and .blogrc.yaml paths remain CWD-relative (operator state, not package state — Negative contract criterion #11 locks this distinction in)
• src/core/benchmark/companion.ts / src/core/research/document.ts — same refactor symmetrically applied: resolve(TEMPLATES_ROOT, '<subpath>') instead of inline fileURLToPath
• scripts/verify-pack.mjs — four-layer packaging gate wired into both npm run verify-pack and prepublishOnly: (1) ALLOWED_PATTERNS whitelist, (2) FORBIDDEN_PATTERNS denylist (no secrets, .js.map, state.db, .blog-agent/, src/, tests/, .codex/), (3) REQUIRED_FILES manifest of 12 runtime-critical paths (catches silent deletions the allowlist alone would miss — Release Prep Pass 1 Codex Finding #3), (4) src→dist compiled-closure check walking src/**/*.ts and asserting every corresponding dist/**/*.js is in the tarball (Release Prep Pass 2 Codex Finding #1 — the allowlist glob + single-entrypoint REQUIRED_FILES would silently pass a missing compiled module without this)
• package.json — build: "clean-dist && tsc && chmod-bin" (prevents stale compiled artifacts from shipping AND restores owner-execute bit on the CLI entrypoint that tsc strips on every rebuild — see scripts/chmod-bin.mjs); prepublishOnly: "lint && build && test && verify-pack" (publish-time gate that cannot be bypassed); files uses globs (dist/**/*.js, dist/**/*.d.ts — excludes .js.map without a second build config); publish surface fields (repository, homepage, bugs, keywords, author); engines.node: ">=20.3.0" (pinned for sharp + recursive readdirSync)
• scripts/chmod-bin.mjs — post-tsc step that chmodSync(dist/cli/index.js, 0o755). Covers the failure mode where tsc regenerates dist/cli/index.js as 0644 and a pre-existing npm link symlink (/opt/homebrew/bin/blog → dist/cli/index.js) dereferences to a non-executable target. Grep-verifiable: the build script's terminal step imports this file; tests/build-bin-executable.test.ts asserts the final mode bit.
• .claude/rules/voice.md — dev-facing voice rule (path-scoped auto-load for draft/evaluate/skill files). Hard rules: no hedges, no tricolon stacks, no topic-restatement transitions, no smarmy openers, no undefined jargon, ~1 em dash per 500 words max with period/comma/parens/cut substitution test, no emojis. Two accessibility tests (newcomer + expert). Structural reviewer loads these hard rules and emits category='voice' issues when the draft drifts. Must stay byte-parity with .claude-plugin/skills/blog/VOICE.md (enforced by tests/voice-parity.test.ts).
• .claude-plugin/skills/blog/VOICE.md — plugin-shipped voice rule (no frontmatter; plugin skills don't path-scope). Loaded by /blog SKILL.md when composing blog research set-section prose so hash-bound section content is voice-compliant before entering the hash gate. Byte-identical to .claude/rules/voice.md body (parity test blocks drift).
• src/core/draft/template.ts — renderDraftTemplate prepends a VOICE_COMMENT JSX block between frontmatter and the first ## section; MDX strips JSX comments at compile time so the comment survives as context for the draft author/agent but is invisible in the rendered hub output.
• .github/workflows/ci.yml — single Node 20 job, step order: checkout → setup-node → npm ci → lint → build → test → verify-pack (build BEFORE test — Release Prep Pass 1 Codex Finding #1; ensures the CWD-independence integration test always runs against fresh dist)
• CHANGELOG.md — Keep-a-Changelog format, single [0.1.0] section covering Phases 1–7 plus the template-path fix
• RELEASING.md — literal v0.1.0 sequence + subsequent-releases template; both sections have main-branch + clean-tree fail-fast preflight guards; pre-publish git push --atomic --dry-run check; atomic git push --atomic origin main refs/tags/vX.Y.Z (not --follow-tags) so branch + tag move together; gh release create --verify-tag prevents silent wrong-commit tag creation; Recovery section structured around registry-state check (npm view m0lz-01@X.Y.Z version) with three cases: A=live/push-only-with-rebase-and-re-tag, B=E404/safe-retry, C=abandon (uses --mixed reset with git status/git log preflights); subsequent-release flow has its own two-commit recovery block with HEAD~2 (not HEAD~1)
• .github/PULL_REQUEST_TEMPLATE.md — ≤10 line checklist with absolute GitHub URLs to AGENTS.md (relative paths 404 in GitHub's PR body rendering)
• .nvmrc — 20.3.0 (contributor convenience; matches the package engines.node floor required by sharp)
• README.md — CI badge at top; ## Install leads with npx m0lz-01 init --import (dev install moved to new ## Development section); ## Changelog + ## Project Status one-liners

/blog Skill Plugin source files:

• src/core/workspace/root.ts — findWorkspaceRoot(cwd, {override, envVar}) ancestor-walks to .blog-agent/state.db; throws WorkspaceNotFoundError with actionable hint citing --workspace + BLOG_WORKSPACE
• src/core/workspace/user-path.ts — resolveUserPath(p) uses _BLOG_ORIGINAL_CWD env (set by startup shim) to resolve relative path flags against the operator's original cwd, not the chdir'd workspace root
• src/core/workspace/resolve.ts — workspaceRelative(subpath) helper for explicit workspace-relative path construction (optional; module-level resolve(...) constants work after chdir)
• src/cli/index.ts — startup shim: parse --workspace early, findWorkspaceRoot + process.chdir() BEFORE dynamic-importing command modules (so module-level resolve('.blog-agent/...') constants evaluate against post-chdir cwd); whitelists init, help, agent, --help, --version to skip the check; registers agent alongside the other commands
• src/core/json-envelope.ts — JsonEnvelope<K, D> type + makeEnvelope(kind, data) + printEnvelope(kind, data) writing to stdout with 2-space indent
• src/core/plan-file/schema.ts — PlanFile type (schema v2), PLAN_CONTENT_TYPES, PLAN_DEPTHS, KNOWN_SUBCOMMANDS, DENY_STEP_SUBCOMMANDS (banned agent nesting), BANNED_ARG_FLAGS (--workspace/--help/-h/--version/-V + = forms; the CLI startup shim hoists --workspace from any argv position — plan steps must not carry it), SLUG_BEARING_STEP_COMMANDS (every blog X Y <slug> subcommand — validator requires args[0] === plan.slug), KNOWN_LEAF_COMMANDS (exhaustive allowlist of TRUE leaves: blog status / blog metrics + SLUG_BEARING; namespace parents like blog ideas / blog research excluded to prevent args-smuggling via Commander's default-action pattern)
• src/core/plan-file/hash.ts — canonicalPlanJSON(plan) drops approved_at + payload_hash and stable-stringifies (recursive key sort, arrays preserve order); computePlanHash(plan) = sha256(canonicalPlanJSON(plan))
• src/core/plan-file/validator.ts — validatePlanSchema(raw) validates required fields + enums + step shape + validateSlug(plan.slug) at schema layer (hand-authored traversal slugs rejected, not just CLI-generated ones); per-step: command starts with "blog ", first word in KNOWN_SUBCOMMANDS, no flag-like tokens in command, canonical single-space form (no whitespace variants), exact match in KNOWN_LEAF_COMMANDS, banned flags in args, args[0] === plan.slug for slug-bearing commands; validatePlanForApply(raw, {workspaceRoot}) adds NO_APPROVAL / HASH_MISMATCH / WORKSPACE_MISMATCH; readPlanFile(path) parses JSON with SCHEMA_INVALID on parse failure
• src/core/plan-file/apply.ts — applyPlan(plan, opts) holds slug-scoped lock, DB-authoritative step state (schema v4 agent_plan_runs + agent_plan_steps), pre-spawn sentinel for crash recovery, pins spawned child to plan.workspace_root (prepend --workspace + scrub BLOG_WORKSPACE from child env), captures exit/stdout_tail/stderr_tail/duration_ms per step, writes receipt at .blog-agent/plans/<slug>.receipt.json atomically via renameSync (audit mirror, NOT trust input), resumes via completed-step skip derived from DB, --restart clears all open runs for slug + sentinels, throws ApplyError with UNKNOWN_COMMAND/STEP_FAILED/RECEIPT_CONFLICT/RECEIPT_HASH_MISMATCH/CRASH_RECOVERY_REQUIRED
• src/core/plan-file/apply-lock.ts — slug-scoped O_CREAT|O_EXCL lockfile with JSON stamp (pid + acquiredAt); honest PID-liveness policy (no false PID-reuse hardening claim); tolerant of legacy bare-PID format; reclaims ESRCH-dead holders + corrupt/empty lockfiles
• src/core/db/schema.ts — SCHEMA_VERSION=4, SCHEMA_V4_SQL adds agent_plan_runs + agent_plan_steps tables with FK CASCADE; receipt JSON is demoted to audit mirror
• src/core/db/database.ts — v4 migration block in migrate() transaction
• src/cli/agent.ts — preflight (trusts post-chdir process.cwd(), omits envVar fallthrough so --workspace > BLOG_WORKSPACE precedence holds), plan (writes skeleton with approved_at: null, validateSlug at CLI boundary, clampOutputPath enforces <workspace>/.blog-agent/plans/*.plan.json with realpath-aware parent + lstat-based leaf symlink rejection), approve (atomically sets approved_at + payload_hash), verify (dry-run validation), apply (validate + execute + write receipt); error taxonomy emitted as [AGENT_ERROR] <CODE>: <msg> on stderr with exit 2 (validation) or 1 (STEP_FAILED)
• src/cli/index.ts — startup shim: parses both --workspace <path> and --workspace=<path> compact form, rejects empty operands explicitly, excludes workspace-operand slots from positional walk so firstPositional correctly identifies subcommand; WORKSPACE_FREE_COMMANDS narrowed to init, help; AGENT_WORKSPACE_FREE_SUBCOMMANDS=preflight (plan/approve/verify/apply require real workspace)
• src/cli/status.ts, src/cli/publish.ts, src/cli/update.ts, src/cli/unpublish.ts, src/cli/evaluate.ts — --json flag on show commands; branches before human-table render, prints envelope + returns
• .claude-plugin/plugin.json — manifest declaring the blog skill
• .claude-plugin/skills/blog/SKILL.md — ≤200-line orchestration prose: preflight via blog agent preflight --json, intent classification, slug collision, plan proposal, approval gate invoking approve → verify → apply, error taxonomy
• .claude-plugin/skills/blog/REFERENCES.md — CLI surface + phase state machine + plan schema + receipt shape + legacy skills/blog-*.md pointers
• .claude-plugin/skills/blog/JOURNEYS.md — four worked journeys: new project launch, technical deep-dive with benchmark, update, unpublish
• .claude-plugin/skills/blog/CHECKPOINTS.md — every human-in-the-loop moment, pre-apply (skill-owned) and post-apply (CLI-owned)
• .claude/skills/blog — relative symlink → ../../.claude-plugin/skills/blog for contributor sessions
• .claude/rules/skills.md — path-scoped rules for .claude-plugin/skills/** (destructive-only-via-apply, --json discipline, no hardcoded identity)
• scripts/verify-pack.mjs — allowlist .claude-plugin/**; REQUIRED_FILES adds .claude-plugin/plugin.json + .claude-plugin/skills/blog/SKILL.md
• package.json — files array adds .claude-plugin/**
• docs/plugin-install.md — three install paths (npm-bundled, repo clone, contributor) + troubleshooting

Expected results

All tests should pass. If any fail after your changes:

1. Check if you modified the source files listed above
2. Read the failing test to understand what behavior it expects
3. Fix your code to preserve the expected behavior, or update the test if the behavior change is intentional

Updating the regression suite

After running the regression suite and before finishing the review, check if any test files touched in this session are NOT already in the suite above:

# Compare test files modified in uncommitted changes against the suite list
git diff --name-only HEAD -- 'tests/*.test.ts'
git status --short -- 'tests/*.test.ts'

For each test file that exercises a newly shipped or migrated feature and is NOT already in the regression suite:

1. Add it to the npx vitest run command in the bash block above
2. Add a row to the "What each test covers" table with: file name, test count, feature name, what it validates
3. Add any new source files to the "Source files these tests protect" list
4. Add a line to the Phase 4 output format checklist under the current milestone
5. Start a new milestone section (e.g., **Phase 2 — Research (feature/phase-2-research)**) when the next phase ships

This ensures the suite is always exhaustive: every feature we ship gets regression-protected automatically.

Phase 2: Full Validation

After regression tests pass, run the full suite:

npx tsc --noEmit
npm test
npm run build

Expected baseline: 0 TypeScript errors, 1137 tests passing across 79 suites, clean build. v0.3 dogfood-hardening added +43 tests across +5 new suites — research-project-linking (15), publish-origin-divergence (6), publish-seed-on-start (4), preview-gate-urls (9), draft-regenerate-frontmatter (9) — plus +8 tests in draft-frontmatter.test.ts for companion_repo resolution. Platform article images added Dev.to/Medium/Substack-preview coverage and expanded draft/crosspost coverage. Durable distribution kits add distribution-kit.test.ts, publish-distribution-kit.test.ts, publish-table-assets.test.ts, and CLI/config/plan-file coverage. Benchmark phase-gates, publish artifact verification, review-inventory tripwires, natural Substack subtitle fitting/failure, pre-clipped subtitle rejection, public-only LinkedIn copy, no-ellipsis HN copy, sanitized image prompts, bounded local-card SVG text, local-card LinkedIn image defaults, copyable chart paste output, portable table image assets, complete-bundle backfill, disabled-channel cleanup, paste-step table verification, stale deletion crash-replay coverage, Medium/Substack upload-checklist handoff, site/direct-push cleanup staging, mirrored Claude review inventory coverage, readable row-card table images with snake_case preservation, pre-clipped LinkedIn fallback copy, legacy prompt-only manifest loading, symlink-protected local-card writes, expected-hash manifest reuse, social-text tamper regeneration, and self-heal source-plan selection bring the current suite to 1137/79; any drift from this baseline is a signal to investigate before merging.

Phase 3: Code Review of Current Changes

git branch --show-current
git status

If on a feature branch, diff against main to see the full feature scope:

git diff main...HEAD
git diff main...HEAD --stat

If on main, diff against the last commit:

git diff HEAD

If reviewing a specific commit, check it out or diff against it.

Focus Areas

1. Logic errors and incorrect behavior
2. Edge cases that aren't handled
3. Null/undefined reference issues
4. Race conditions or concurrency issues — especially relevant when CLI and Codex skills both write to state.db
5. Security vulnerabilities — SQL injection (check for string interpolation instead of ? placeholders), path traversal in import, env var leakage
6. Resource management — unclosed database connections (closeDatabase called on all paths?), leaked file handles, temp dirs not cleaned in tests
7. API contract violations — PostFrontmatter schema drift vs m0lz.00, CLI flag changes that break scripts
8. Caching bugs — the SQLite layer has no caching, but watch for prepared-statement reuse across closed DBs
9. Pattern violations — check AGENTS.md and .codex/rules/ for project conventions:
   • ESM imports MUST use .js extension on internal imports
   • SQL queries MUST use parameterized statements (? or @named)
   • better-sqlite3 is synchronous — no async/await for DB operations
   • CLI commands are non-interactive (Commander.js options only, no readline prompts)
   • No emojis in content or user-facing output
   • Pipeline operations must be idempotent

Rules

• Use sub-agents to explore the codebase in parallel for efficiency
• Report pre-existing bugs found near the changed code — code quality matters everywhere
• Do NOT report speculative or low-confidence issues — conclusions must be based on actual code understanding
• If reviewing a specific git commit, note that local code may differ from that commit

Phase 4: Output Format

Migration Status

Schema Drift: NONE / DETECTED (tables/columns affected)
SCHEMA_VERSION Bumped: YES / NO / N/A
Fresh init works: PASS / FAIL
Action: Bump SCHEMA_VERSION and add migration block, or N/A

Regression Suite Results

Regression Suite: PASS / FAIL

Phase 1 — Foundation:
  - Database schema + connection (7 tests): ✓ / ✗
  - Config loader (10 tests): ✓ / ✗
  - Post import (5 tests): ✓ / ✗
  - Ideas backlog CRUD (11 tests): ✓ / ✗
  - Content type detection (6 tests): ✓ / ✗
  - CLI handlers (13 tests): ✓ / ✗

Phase 2 — Research:
  - Schema v1->v2 migration (3 tests): ✓ / ✗
  - Research post lifecycle (9 tests): ✓ / ✗
  - Source management (11 tests): ✓ / ✗
  - Research documents (18 tests): ✓ / ✗
  - Research CLI handlers (13 tests): ✓ / ✗

Phase 3 — Benchmark:
  - Environment capture (4 tests): ✓ / ✗
  - Benchmark state lifecycle (17 tests): ✓ / ✗
  - Results storage (11 tests): ✓ / ✗
  - Companion repo scaffolding (6 tests): ✓ / ✗
  - Benchmark CLI handlers (19 tests): ✓ / ✗
  - Benchmark repair CLI (7 tests): ✓ / ✗

Phase 4 — Draft:
  - PostFrontmatter schema (32 tests): ✓ / ✗
  - Draft state lifecycle (17 tests): ✓ / ✗
  - Benchmark data formatting (9 tests): ✓ / ✗
  - Tag taxonomy reader (6 tests): ✓ / ✗
  - Draft CLI handlers (33 tests): ✓ / ✗

Phase 5 — Evaluate:
  - ReviewerOutput schema (21 tests): ✓ / ✗
  - Structural autocheck lints (15 tests): ✓ / ✗
  - Synthesis + matching (24 tests): ✓ / ✗
  - Report renderer (4 tests): ✓ / ✗
  - Evaluation state lifecycle (81 tests): ✓ / ✗
  - Evaluate CLI handlers (24 tests): ✓ / ✗

Phase 6 — Publish:
  - Phase + steps-crud + lock + crash-safety + reconcile (43 tests): ✓ / ✗
  - Pipeline runner + crash-safety + reconcile regressions (20 tests): ✓ / ✗
  - MDX → Markdown converter (15 tests): ✓ / ✗
  - Portable table asset rendering (11 tests): ✓ / ✗
  - Site PR + preview gate + dirty-state + rename/copy guardrail (21 tests): ✓ / ✗
  - Dev.to probe-then-create + Medium + Substack paste (40 tests): ✓ / ✗
  - Deterministic platform image generation (22 tests): ✓ / ✗
  - Social text: LinkedIn + Hacker News (17 tests): ✓ / ✗
  - Durable distribution-kit generation (28 tests): ✓ / ✗
  - Pre-site generation + strict distribution persistence (26 tests): ✓ / ✗
  - Research page generator (15 tests): ✓ / ✗
  - Companion repo probe-then-create + origin-URL guardrail (21 tests): ✓ / ✗
  - Publish CLI handlers + ctx.urls hydration + distribution-kit backfill (20 tests): ✓ / ✗
  - updateFrontmatter + updateProjectReadme + index-clean + crash-replay (20 tests): ✓ / ✗

Phase 7 — Lifecycle:
  - Schema v3 canonical table-rebuild + partial-unique-index (12 tests): ✓ / ✗
  - Update-cycle lifecycle (17 tests): ✓ / ✗
  - Cycle-keyed update-notice marker (13 tests): ✓ / ✗
  - Update CLI handlers (abort artifact preservation) (7 tests): ✓ / ✗
  - Update Dev.to probe→PUT / miss→POST (4 tests): ✓ / ✗
  - Update publish unit coverage: site-update + completeUpdateUnderLock (5 tests): ✓ / ✗
  - Publish guard: refuses on open update cycle (2 tests): ✓ / ✗
  - Unpublish state lifecycle (6 tests): ✓ / ✗
  - Unpublish CLI + --confirm + fetch-spy (3 tests): ✓ / ✗
  - Unpublish readme-revert trust boundaries (5 tests): ✓ / ✗
  - Unpublish site revert PR-only (5 tests): ✓ / ✗
  - Unpublish Dev.to PUT published:false (7 tests): ✓ / ✗
  - Unpublish pipeline E2E (4 tests): ✓ / ✗
  - Orchestrator skills cross-reference (2 tests): ✓ / ✗
  - TRUE E2E update-mode runPipeline (3 tests): ✓ / ✗
  - Cross-flow lock contention (same-slug + disjoint) (3 tests): ✓ / ✗
  - PostFrontmatter Phase 7 round-trip + cross-repo fixtures (15 tests): ✓ / ✗
  - Split origin-guard tolerant/strict APIs (16 tests): ✓ / ✗
  - Pipeline registry ↔ step-tuple invariants (8 tests): ✓ / ✗

Release Prep:
  - Shared package-root resolver (4 tests): ✓ / ✗
  - CLI CWD-independence integration (1 test): ✓ / ✗
  - init.ts hard-fail regression — absent shipped templates (2 tests in cli.test.ts): ✓ / ✗

/blog Skill Plugin:
  - Workspace-root detection (11 tests): ✓ / ✗
  - `--json` envelope surface (6 tests): ✓ / ✗
  - Plan schema + hash + validator + apply + receipt + lock (64 tests): ✓ / ✗
  - Plugin static shape + SKILL discipline + sibling-doc parity + install-docs (22 tests): ✓ / ✗
  - Real skill-to-CLI handoff end-to-end + crash recovery + workspace pinning (25 tests): ✓ / ✗

v0.3 Dogfood Hardening:
  - Research project linking: `--project` flag + prompt regex + PROJECT_UNLINKED guard (15 tests): ✓ / ✗
  - Publish site-pr origin-sync divergence refusal + allow-main-ahead override (6 tests): ✓ / ✗
  - runPublishStart always seeds pipeline_steps on phase=publish (4 tests): ✓ / ✗
  - Preview-gate emits canonical/supplementary/companion URLs in JSON envelope (9 tests): ✓ / ✗
  - blog draft regenerate-frontmatter recovery command (9 tests): ✓ / ✗

Full Suite: X passing, Y failing  (baseline: 1137 passing across 79 suites)
Lint: {error count} errors  (baseline: 0)
Build: PASS / FAIL

Contract Evaluation (if applicable)

Contract: {feature name} — Tier {N}
Evaluator: Isolated sub-agent (no implementation context)

| Criterion | Threshold | Score | Pass |
|-----------|-----------|-------|------|
| {name} | {T}/10 | {S}/10 | YES/NO |

Overall: PASS / FAIL

If no contract was found in the plan, output: Contract: N/A — no contract in plan

Code Review Findings

Group findings by severity:

Critical — Must fix before merge (bugs, security, data loss)

• file:line — description of the issue and recommended fix

Warning — Should fix (performance, maintainability, pattern violations)

• file:line — description and suggestion

Suggestion — Consider improving (readability, minor optimizations)

• file:line — description and suggestion

Positive — What's done well (reinforce good patterns)

• Description of what was done right