@dotdotgod/cli 0.1.35 → 0.1.40

package/README.md

@@ -2,41 +2,45 @@
 
 [![npm version](https://img.shields.io/npm/v/@dotdotgod/cli.svg)](https://www.npmjs.com/package/@dotdotgod/cli) [![GitHub](https://img.shields.io/badge/GitHub-dotdotgod%2Fdotdotgod--kit-181717?logo=github)](https://github.com/dotdotgod/dotdotgod-kit/tree/main/packages/cli) [![License: Elastic 2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](../../LICENSE)
 
-> **Change a file, know what else must be checked.**
+Command-line tools for dotdotgod project memory.
+
+Use this package when you want to initialize a docs-first project scaffold, validate project-memory docs, build a local graph/cache, load bounded context snapshots, expand project references, or ask what should be checked after a file changes.
+
+## Start Here
+
+Run one command without installing globally:
 
 ```bash
-$ dotdotgod graph impact . --changed packages/cli/src/core.mjs --compact
+npx @dotdotgod/cli validate .
 ```
 
-```text
-docs:
-- docs/spec/REFERENCE_EXPANSION.md (91; incoming:implemented_by, semantic_similarity)
-- docs/test/REFERENCE_EXPANSION.md (65.3; verified_by, semantic_similarity)
-- docs/spec/LOAD_PROJECT.md (35.8; related_doc, semantic_similarity)
-
-tests:
-- packages/cli/test/core.test.mjs (78.6; semantic_similarity, incoming:semantic_similarity, verified_by)
-- packages/cli/test/e2e.test.mjs (51.4; verified_by)
+Install only if you want a persistent `dotdotgod` command:
 
-files:
-- packages/cli/src/core.mjs (100; changed-file)
-- packages/pi/extensions/plan-mode/index.ts (45; implemented_by, semantic_similarity)
+```bash
+npm install -g @dotdotgod/cli
 ```
 
-`graph impact` ranks the specs, tests, architecture notes, config docs, and source files most likely to matter for a change. `--compact` keeps a short text summary, `--yml`/`--yaml` returns a compact structured agent-facing summary, and `--json` returns machine-readable detail. It uses the project-memory graph built from Markdown links, README routes, headings, traceability blocks, package metadata, memory areas, and deterministic routing hints.
+Common first commands:
 
-Command-line tools for dotdotgod project memory. The CLI turns explicit, maintained project links into a local graph/cache: README routes, Markdown links, traceability blocks, memory areas, package metadata, commands, tests, and deterministic routing hints. That maintained graph powers `graph impact`, while the initialized docs surface keeps agent load context high signal.
+```bash
+dotdotgod init .
+dotdotgod validate .
+dotdotgod load-snapshot .
+dotdotgod graph impact . --changed <path> --compact
+```
 
-## Why Use It?
+## What It Does
 
-- Initialize `AGENTS.md`, thin agent entrypoints, docs indexes, active-plan space, archive map, and local cache ignores with `dotdotgod init`.
-- Replace ad-hoc docs checks with `dotdotgod validate`.
-- Keep generated Markdown traceability links synchronized with `dotdotgod traceability links`.
-- Build `.dotdotgod/` as a local ignored cache of file fingerprints and compact graph shards derived from maintained project links.
-- Use `load-snapshot` as a bounded first-pass map for high-quality agent loading.
-- Resolve explicit `[[...]]` references or high-signal fuzzy references before broad text search.
-- Query safe review scope for a changed file with grouped, bounded impact reports.
-- Inspect or initialize project config with `dotdotgod config` and `dotdotgod config init`.
+- `init` creates `AGENTS.md`, thin agent entrypoints, docs indexes, active-plan space, archive map, and local cache ignores.
+- `validate` checks the dotdotgod docs/project-memory structure, local links, traceability blocks, config validity, and optional index freshness.
+- `index` builds `.dotdotgod/manifest.json` and compact graph shards from maintained project files.
+- `load-snapshot` returns a bounded first-pass project map for AI agents.
+- `resolve` and `expand` map explicit or high-signal prompt references to project files.
+- `graph impact` ranks likely related specs, tests, docs, commands, and source files for a changed path.
+- `traceability links` checks or repairs generated Markdown traceability-link sections.
+- `plan validate` validates active plan artifacts and simplified Plan Generator checkpoints before execution.
+- `plan stage create` creates an internal `.dotdotgod-plan/NN_STAGE_NAME.md` checkpoint for a simplified Plan Generator stage.
+- `trello sync` plans or writes Trello linked-doc metadata from configured docs paths.
 
 ## Commands
 
@@ -56,60 +60,83 @@ dotdotgod expand . "Update [[PLAN_MODE]] and [[HOOKS]]"
 dotdotgod expand . "PLAN_MODE 수정하자" --fuzzy
 dotdotgod traceability links . --check
 dotdotgod traceability links . --write
+dotdotgod plan validate docs/plan/<task-slug>/README.md
+dotdotgod plan validate docs/plan/<task-slug>/README.md --stage 04
+dotdotgod plan stage create 02 docs/plan/<task-slug>/README.md
 dotdotgod graph impact . --changed <path>
 dotdotgod graph impact . --changed <path> --compact
 dotdotgod graph impact . --changed <path> --yml
 dotdotgod graph communities .
 ```
 
-`--help`, `-h`, and `help` print usage to stdout. Command-specific help is available with `dotdotgod <command> --help`, including nested commands such as `dotdotgod graph impact --help`, `dotdotgod config init --help`, and `dotdotgod traceability links --help`.
+`--help`, `-h`, and `help` print usage to stdout. Command-specific help is available with `dotdotgod <command> --help`, including nested commands such as `dotdotgod graph impact --help`, `dotdotgod config init --help`, `dotdotgod plan stage create --help`, and `dotdotgod traceability links --help`.
 
-## Validation and Verification Boundaries
+## Which Command Should I Use?
 
-| Command | Responsibility |
+| Need | Command |
 | --- | --- |
-| `dotdotgod validate <root>` | Checks dotdotgod docs/project-memory structure, local links, traceability blocks, generated traceability-link drift, config validity, and optional index freshness. |
-| `dotdotgod traceability links <root> --check` | Runs only the generated traceability-link and compact JSON drift check. |
-| `dotdotgod traceability links <root> --write` | Repairs generated traceability-link sections and rewrites canonical `json dotdotgod` blocks as compact JSON. |
-| `pnpm run verify` | Runs the repository-level quality gate: generated-resource checks, package verify contracts, tests, typecheck, and docs validation where each package defines it. |
+| Add the dotdotgod scaffold to a repository | `dotdotgod init .` |
+| Check docs, links, config, traceability, and optional index freshness | `dotdotgod validate . --check-index` |
+| Refresh the local graph/cache | `dotdotgod index .` |
+| Give an agent a bounded project map | `dotdotgod load-snapshot .` |
+| Resolve `[[...]]` references from a prompt | `dotdotgod expand . "Update [[PLAN_MODE]]"` |
+| Repair generated traceability-link sections | `dotdotgod traceability links . --write` |
+| Validate an active plan before execution | `dotdotgod plan validate docs/plan/<task>/README.md` |
+| Create an internal Plan Generator stage checkpoint | `dotdotgod plan stage create 03 docs/plan/<task>/README.md` |
+| See what else to inspect after a change | `dotdotgod graph impact . --changed <path> --compact` |
+| Preview Trello linked-doc updates | `dotdotgod trello sync . --dry-run` |
+
+## Changed-File Impact
 
-Most users start with `validate`. Use `traceability links --write` only when generated traceability output needs repair, and use `verify` before release-style handoff.
+```bash
+$ dotdotgod graph impact . --changed packages/cli/src/core.mjs --compact
+```
 
-## Graph, Cache, and Impact
+```text
+docs:
+- docs/spec/REFERENCE_EXPANSION.md (91; incoming:implemented_by, semantic_similarity)
+- docs/test/REFERENCE_EXPANSION.md (65.3; verified_by, semantic_similarity)
 
-The cache uses `.dotdotgod/manifest.json` plus graph shards under `.dotdotgod/graph/`. `status` is read-only. `load-snapshot`, `resolve`, `expand`, and `graph` commands lazily refresh missing or stale cache data before returning agent-facing output.
+files:
+- packages/cli/src/core.mjs (100; changed-file)
+- packages/pi/extensions/plan-mode/index.ts (45; implemented_by, semantic_similarity)
+```
 
-`graph impact` requires `--changed <path>` so ranking has a seed file. Raw JSON is useful for diagnostics; `--compact` returns a smaller text summary; `--yml`/`--yaml` returns structured compact groups for agents. Related nodes include scores, reasons, and retrieval metadata, and output stays bounded with omitted counts.
+`graph impact` needs `--changed <path>` so ranking has a seed file. Use `--compact` for short text, `--yml` or `--yaml` for compact structured agent-facing output, and `--json` for machine-readable detail.
 
-`graph communities` runs Leiden community detection through `leiden-ts` with a deterministic fallback for tiny or invalid graphs.
+The graph is built from maintained project files: Markdown links, README routes, headings, traceability blocks, package metadata, memory areas, imports, exports, commands, tests, and deterministic routing hints.
 
-## Reference Expansion
+## Validation and Verification Boundaries
 
-`resolve` maps one project-memory reference such as `PLAN_MODE` or `docs/spec/PLAN_MODE.md` to ranked graph candidates. `expand` scans prompt text for `[[refs]]`, resolves each target, and can include compact impact context with `--with-impact`.
+| Command | Responsibility |
+| --- | --- |
+| `dotdotgod validate <root>` | Checks dotdotgod docs/project-memory structure, local links, traceability blocks, generated traceability-link drift, config validity, and optional index freshness. |
+| `dotdotgod traceability links <root> --check` | Runs only the generated traceability-link and compact JSON drift check. |
+| `dotdotgod traceability links <root> --write` | Repairs generated traceability-link sections and rewrites canonical `json dotdotgod` blocks as compact JSON. |
+| `dotdotgod plan validate <plan-readme>` | Checks active-plan structure, required Markdown sections, decision/assumption blockers, atomic-task verification, and simplified Plan Generator checkpoints when present. |
+| `pnpm run verify` | Runs this repository's quality gate: generated-resource checks, package verify contracts, tests, typecheck, and docs validation where each package defines it. |
 
-Use `expand --fuzzy` for high-signal natural prompt references such as uppercase identifiers, path-like mentions, quoted phrases, and strong indexed aliases. Fuzzy low-signal terms use built-in defaults and can be adjusted in `dotdotgod.config.json` with `referenceExpansion.fuzzy.lowSignal.add` and `remove`. Archive bodies are excluded by default unless `--include-archive` is passed.
+Most users start with `validate`. Use `traceability links --write` only when generated traceability output needs repair, and use `verify` before release-style handoff in this repository.
 
 ## Memory, Specs, and Config
 
-The default docs scaffold gives files explicit project-memory meaning:
-
-- `docs/spec/**`: stable shared/fresh product truth and, by default, the traceability-enforced behavior-spec path.
-- `docs/arch/**`: stable shared/fresh architecture rationale.
-- `docs/test/**`: stable shared/fresh verification knowledge.
-- `docs/plan/**`: local fresh active-task intent.
-- `docs/archive/README.md`: local stale archive map included by default.
-- `docs/archive/**`: local stale archive bodies excluded by default.
+The default scaffold gives docs explicit roles:
 
-Those roles are configurable but separate. Use `memory.areas` to customize memory classification and retrieval priority. Use `traceability.required` / `traceability.exclude` to customize which markdown paths must end with `json dotdotgod` traceability blocks. Use `validation.markdown`, `impactRanking`, and `referenceExpansion` to tune size budgets, impact scoring, and fuzzy prompt matching.
+- `docs/spec/**`: product behavior and requirements. This path is traceability-enforced by default.
+- `docs/arch/**`: architecture rationale, boundaries, conventions, and decisions.
+- `docs/test/**`: verification strategy, regression coverage, fixtures, and commands.
+- `docs/plan/**`: local active-task intent.
+- `docs/archive/README.md`: local archive map included by default.
+- `docs/archive/**`: local archive bodies excluded by default unless targeted.
 
-See the [root README](../../README.md), [GitHub repository](https://github.com/dotdotgod/dotdotgod-kit), [`docs/concept/CONTEXT_CURATION.md`](../../docs/concept/CONTEXT_CURATION.md), [`docs/concept/CONTEXT_MECHANICS.md`](../../docs/concept/CONTEXT_MECHANICS.md), [`docs/spec/MEMORY_AREA_CONFIG.md`](../../docs/spec/MEMORY_AREA_CONFIG.md), and [`docs/spec/TRACEABILITY_CONFIG.md`](../../docs/spec/TRACEABILITY_CONFIG.md) for the deeper model.
+Use `memory.areas` to customize memory classification and retrieval priority. Use `traceability.required` and `traceability.exclude` to customize which Markdown paths need `json dotdotgod` traceability blocks. Use `validation.markdown`, `impactRanking`, and `referenceExpansion` to tune size budgets, impact scoring, and fuzzy prompt matching.
 
 ## Indexing Scope
 
-`dotdotgod index` is gitignore-aware by default. It uses `git ls-files --cached --others --exclude-standard` when possible, then filters to supported text, source, script, config, web, and infrastructure files. In non-git contexts it falls back to a conservative directory walk.
+`dotdotgod index` is gitignore-aware by default. It uses `git ls-files --cached --others --exclude-standard` when possible, then filters to supported text, source, script, config, web, and infrastructure files.
 
 Default exclusions include dependency, generated, cache, and secret-like paths such as `.git/`, `.dotdotgod/`, `node_modules/`, `dist/`, `build/`, `coverage/`, `.next/`, `target/`, `vendor/`, `.venv/`, and `.env`. Example env templates such as `.env.example` remain indexable.
 
-## Compared with Graphify-Style Reports
+## Learn More
 
-The CLI is not designed to make agents read a giant graph report. The full graph stays local; agent-facing output is bounded. The strength is explicit project-maintained links before extraction: docs areas, README indexes, traceability blocks, package metadata, commands, tests, and memory policy tell agents which files are behavior truth, architecture rationale, verification, current intent, or historical memory before they read source.
+See the [root README](../../README.md), [GitHub repository](https://github.com/dotdotgod/dotdotgod-kit), [Context curation](../../docs/concept/CONTEXT_CURATION.md), [Context mechanics](../../docs/concept/CONTEXT_MECHANICS.md), [Memory area config](../../docs/spec/MEMORY_AREA_CONFIG.md), and [Traceability config](../../docs/spec/TRACEABILITY_CONFIG.md).

package/bin/dotdotgod.mjs

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 import { runCli } from '../src/core.mjs';
 
-runCli();
+await runCli();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/cli",
-  "version": "0.1.35",
+  "version": "0.1.40",
   "description": "CLI for dotdotgod validation, project memory snapshots, and graph indexing.",
   "type": "module",
   "license": "Elastic-2.0",

package/src/cli/usage.mjs

@@ -34,12 +34,43 @@ Create dotdotgod.config.json with the built-in default memory, traceability, val
     case 'load-snapshot':
       return `Usage:
   dotdotgod load-snapshot <root> [--json]`;
+    case 'plan':
+      return `Usage:
+  dotdotgod plan validate docs/plan/<task-slug>/README.md [--stage stage] [--json]
+  dotdotgod plan stage create <stage> [docs/plan/<task-slug>/README.md] [--json]`;
+    case 'plan validate':
+      return `Usage:
+  dotdotgod plan validate docs/plan/<task-slug>/README.md [--stage stage] [--json]
+
+Validates an active plan artifact before execution. Supports simplified Plan Generator stages and optional .dotdotgod-plan/NN_STAGE_NAME.md workspaces. Use --stage with a stage name or numeric prefix such as 04 or 05 to validate only that stage.`;
+    case 'plan stage':
+      return `Usage:
+  dotdotgod plan stage create <stage> [docs/plan/<task-slug>/README.md] [--json]`;
+    case 'plan stage create':
+      return `Usage:
+  dotdotgod plan stage create <stage> [docs/plan/<task-slug>/README.md] [--json]
+
+Creates the matching .dotdotgod-plan/NN_STAGE_NAME.md internal stage checkpoint for a simplified Plan Generator stage. <stage> accepts a numeric prefix such as 02 or a canonical stage name such as 02-context-load. If the plan path is omitted, exactly one active docs/plan/<task-slug>/README.md candidate must exist.`;
     case 'resolve':
       return `Usage:
   dotdotgod resolve <root> <ref> [--max-results n] [--include-archive] [--json]`;
     case 'expand':
       return `Usage:
   dotdotgod expand <root> <prompt> [--max-results n] [--include-archive] [--with-impact] [--fuzzy] [--json]`;
+    case 'trello':
+      return `Usage:
+  dotdotgod trello sync <root> [--dry-run]`;
+    case 'trello sync':
+      return `Usage:
+  dotdotgod trello sync <root> [--dry-run]
+
+Options:
+  --dry-run  Preview planned Trello updates without calling Trello APIs.
+
+Write mode:
+  Omit --dry-run only in the trusted GitHub Actions default-branch push workflow.
+  Requires TRELLO_API_KEY and TRELLO_TOKEN in the trusted workflow environment.
+  Local/manual and pull request usage should run --dry-run.`;
     case 'traceability':
       return `Usage:
   dotdotgod traceability links <root> [--check|--write] [--json]`;
@@ -75,6 +106,9 @@ Ranks nodes related to a changed file. <root> is the project root; --changed is
   dotdotgod resolve <root> <ref> [--max-results n] [--include-archive] [--json]
   dotdotgod expand <root> <prompt> [--max-results n] [--include-archive] [--with-impact] [--fuzzy] [--json]
   dotdotgod traceability links <root> [--check|--write] [--json]
+  dotdotgod plan validate docs/plan/<task-slug>/README.md [--stage stage] [--json]
+  dotdotgod plan stage create <stage> [docs/plan/<task-slug>/README.md] [--json]
+  dotdotgod trello sync <root> [--dry-run]
   dotdotgod graph impact <root> --changed <path> [--compact|--json|--yml|--yaml]
   dotdotgod graph communities <root> [--json]`;
   }
@@ -120,7 +154,11 @@ export function printVersion() {
 export function helpCommandFromArgs(args) {
   const nonHelp = args.filter((arg) => !isHelpToken(arg));
   if (nonHelp[0] === 'graph' && nonHelp[1]) return `graph ${nonHelp[1]}`;
+  if (nonHelp[0] === 'trello' && nonHelp[1]) return `trello ${nonHelp[1]}`;
   if (nonHelp[0] === 'traceability' && nonHelp[1]) return `traceability ${nonHelp[1]}`;
+  if (nonHelp[0] === 'plan' && nonHelp[1] === 'stage' && nonHelp[2] === 'create') return 'plan stage create';
+  if (nonHelp[0] === 'plan' && nonHelp[1] === 'stage') return 'plan stage';
+  if (nonHelp[0] === 'plan' && nonHelp[1]) return `plan ${nonHelp[1]}`;
   if (nonHelp[0] === 'config' && nonHelp[1] === 'init') return 'config init';
   return nonHelp[0] ?? 'root';
 }

package/src/commands/config.mjs

@@ -0,0 +1,85 @@
+import { existsSync, statSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { usage } from '../cli/usage.mjs';
+import { defaultDotdotgodConfigText, memoryConfigSummary, readMemoryConfig } from '../memory/config.mjs';
+
+function parseConfigOptions(argv, allowForce = false, usageKey = 'config') {
+  const options = { root: '.', json: false, force: false };
+  let rootSet = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--json') options.json = true;
+    else if (allowForce && arg === '--force') options.force = true;
+    else if (!arg.startsWith('-') && !rootSet) {
+      options.root = arg;
+      rootSet = true;
+    } else if (!arg.startsWith('-')) usage(`Unexpected argument: ${arg}`, usageKey);
+    else usage(`Unknown option: ${arg}`, usageKey);
+  }
+  options.root = resolve(options.root);
+  return options;
+}
+
+function configSourcePath(root, source) {
+  return source && source !== 'default' ? join(root, source) : null;
+}
+
+function configInitError(options, code, message, path = null) {
+  const payload = { ok: false, command: 'config init', root: options.root, path, created: false, overwritten: false, error: { code, message } };
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    process.exit(2);
+  }
+  console.error(message);
+  process.exit(2);
+}
+
+function formatConfigOutput(payload) {
+  const errors = payload.errors ?? [];
+  const lines = [`dotdotgod config: ${payload.source}${errors.length > 0 ? ' (invalid; using defaults)' : ''}`];
+  lines.push(`- path: ${payload.path ?? 'none'}`);
+  lines.push(`- memory areas: ${payload.config.areas.length}`);
+  lines.push(`- traceability required: ${(payload.config.traceability.required ?? []).join(', ') || 'none'}`);
+  lines.push(`- traceability exclude: ${(payload.config.traceability.exclude ?? []).join(', ') || 'none'}`);
+  lines.push(`- validation markdown: maxLines=${payload.config.validation.markdown.maxLines}, maxChars=${payload.config.validation.markdown.maxChars}`);
+  lines.push(`- validation markdown exclude: ${(payload.config.validation.markdown.exclude ?? []).join(', ') || 'none'}`);
+  lines.push(`- impact ranking preset: ${payload.config.impactRanking.preset}`);
+  lines.push(`- trello sync paths: ${(payload.config.integrations?.trello?.syncPaths ?? []).join(', ') || 'none'}`);
+  const lowSignal = payload.config.referenceExpansion?.fuzzy?.lowSignal ?? { terms: [], add: [], remove: [] };
+  lines.push(`- fuzzy low-signal terms: ${(lowSignal.terms ?? []).join(', ') || 'none'} (add: ${(lowSignal.add ?? []).join(', ') || 'none'}; remove: ${(lowSignal.remove ?? []).join(', ') || 'none'})`);
+  if (errors.length > 0) {
+    lines.push('- errors:');
+    for (const error of errors) lines.push(`  - ${error.code} ${error.file}: ${error.message}`);
+  }
+  return lines.join('\n');
+}
+
+export function runConfig(argv) {
+  const isInit = argv[0] === 'init';
+  const options = parseConfigOptions(isInit ? argv.slice(1) : argv, isInit, isInit ? 'config init' : 'config');
+  if (isInit) {
+    if (!existsSync(options.root)) configInitError(options, 'ROOT_NOT_FOUND', `Project root not found: ${options.root}`);
+    try {
+      if (!statSync(options.root).isDirectory()) configInitError(options, 'ROOT_NOT_DIRECTORY', `Project root is not a directory: ${options.root}`);
+    } catch {
+      configInitError(options, 'ROOT_NOT_FOUND', `Project root not found: ${options.root}`);
+    }
+    const target = join(options.root, 'dotdotgod.config.json');
+    const rcPath = join(options.root, '.dotdotgodrc.json');
+    if (existsSync(rcPath)) configInitError(options, 'CONFIG_RC_EXISTS', `.dotdotgodrc.json already exists; remove or migrate it before initializing dotdotgod.config.json.`, rcPath);
+    const existed = existsSync(target);
+    if (existed && !options.force) configInitError(options, 'CONFIG_EXISTS', `dotdotgod.config.json already exists. Re-run with --force to overwrite it.`, target);
+    writeFileSync(target, defaultDotdotgodConfigText());
+    const payload = { ok: true, command: 'config init', root: options.root, path: target, created: !existed, overwritten: existed };
+    if (options.json) console.log(JSON.stringify(payload, null, 2));
+    else console.log(`dotdotgod config init: ${existed ? 'overwrote' : 'created'} ${target}`);
+    return;
+  }
+
+  const config = readMemoryConfig(options.root);
+  const errors = config.errors ?? [];
+  const payload = { ok: errors.length === 0, command: 'config', root: options.root, source: config.source ?? 'default', path: configSourcePath(options.root, config.source), config: memoryConfigSummary(config), errors };
+  if (options.json) console.log(JSON.stringify(payload, null, 2));
+  else console.log(formatConfigOutput(payload));
+  if (errors.length > 0) process.exit(1);
+}

package/src/commands/graph.mjs

@@ -0,0 +1,66 @@
+import { commandUsage, parseCommon, usage } from '../cli/usage.mjs';
+import { buildCommunities } from '../graph/communities.mjs';
+import { graphSummary, readFreshIndex } from '../index/cache.mjs';
+import { buildCompactImpactReport, buildImpactReport } from '../impact/report.mjs';
+import { formatCompactImpactOutput, formatYmlGraphImpactError, formatYmlImpactOutput } from '../impact/format.mjs';
+
+export function parseGraphOptions(argv) {
+  const filtered = [];
+  let changed;
+  let compact = false;
+  let yml = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--changed') {
+      const next = argv[i + 1];
+      if (next && !next.startsWith('-')) {
+        changed = next;
+        i += 1;
+      }
+    } else if (argv[i] === '--compact') compact = true;
+    else if (argv[i] === '--yml' || argv[i] === '--yaml') yml = true;
+    else filtered.push(argv[i]);
+  }
+  const options = parseCommon(filtered);
+  options.changed = changed;
+  options.compact = compact;
+  options.yml = yml;
+  return options;
+}
+
+export function runGraph(argv) {
+  const sub = argv[0];
+  const isImpact = sub === 'impact';
+  if (!['impact', 'communities'].includes(sub)) usage(sub ? `Unknown graph command: ${sub}` : 'Missing graph command.', 'graph');
+  const options = parseGraphOptions(argv.slice(1));
+  if (isImpact && [options.json, options.compact, options.yml].filter(Boolean).length > 1) {
+    const message = 'Choose only one graph impact output mode: --compact, --json, or --yml/--yaml.';
+    if (options.json) console.log(JSON.stringify({ ok: false, command: 'graph impact', compact: options.compact || undefined, yml: options.yml || undefined, root: options.root, error: { code: 'OUTPUT_MODE_CONFLICT', message }, usage: commandUsage('graph impact') }, null, 2));
+    else if (options.yml) console.log(formatYmlGraphImpactError(options, message, 'OUTPUT_MODE_CONFLICT'));
+    else usage(message, 'graph impact');
+    process.exit(2);
+  }
+  if (isImpact && !options.changed) {
+    const message = 'Missing required option: --changed <path>. Run `dotdotgod graph impact <root> --changed <path>`.';
+    if (options.json) {
+      console.log(JSON.stringify({ ok: false, command: 'graph impact', compact: options.compact || undefined, root: options.root, error: { code: 'MISSING_CHANGED', message }, usage: commandUsage('graph impact') }, null, 2));
+      process.exit(2);
+    }
+    if (options.yml) {
+      console.log(formatYmlGraphImpactError(options, message, 'MISSING_CHANGED'));
+      process.exit(2);
+    }
+    usage(message, 'graph impact');
+  }
+  const { status, index, metadata } = readFreshIndex(options.root);
+  const rawImpact = isImpact ? buildImpactReport(index, options.changed) : undefined;
+  const impact = isImpact && (options.compact || options.yml) ? buildCompactImpactReport(rawImpact) : rawImpact;
+  const payload = isImpact
+    ? { ok: status.ok, command: 'graph impact', compact: options.compact || undefined, root: options.root, status, metadata, changed: options.changed, related: impact.related, impact }
+    : { ok: status.ok, command: 'graph communities', root: options.root, status, metadata, graph: graphSummary(index), communities: buildCommunities(index) };
+  const refreshNote = metadata.cacheRefreshed ? ', refreshed' : '';
+  if (options.json) console.log(JSON.stringify(payload, null, 2));
+  else if (isImpact && options.yml) console.log(formatYmlImpactOutput(payload, impact));
+  else if (isImpact && options.compact) console.log(formatCompactImpactOutput(payload, impact));
+  else if (isImpact) console.log(`graph impact: ${payload.related.length} related node(s), ${impact.omittedRelated ?? 0} omitted (${status.status}${refreshNote} index)`);
+  else console.log(`graph communities: ${payload.communities.communities.length}/${payload.communities.total} shown, ${payload.communities.omitted} omitted (${status.status}${refreshNote} index)`);
+}

package/src/commands/load-snapshot.mjs

@@ -0,0 +1,40 @@
+import { parseCommon } from '../cli/usage.mjs';
+import { buildCommunities } from '../graph/communities.mjs';
+import { memoryConfigSummary, readMemoryConfig } from '../memory/config.mjs';
+import { buildMemoryAreas, detectCommandGuidance } from '../load-snapshot/summary.mjs';
+import { graphSummary, readFreshIndex } from '../index/cache.mjs';
+
+export function runLoadSnapshot(argv) {
+  const options = parseCommon(argv);
+  const { status, index, metadata } = readFreshIndex(options.root);
+  const summary = graphSummary(index);
+  const communities = buildCommunities(index, { communities: 5, items: 5 });
+  const memoryAreas = buildMemoryAreas(index, { items: 4 });
+  const memoryConfig = index.memoryConfig ?? memoryConfigSummary(readMemoryConfig(options.root));
+  const memoryPolicy = {
+    source: memoryConfig.source ?? 'default',
+    sharedAreas: (memoryConfig.areas ?? []).filter((area) => area.scope === 'shared').map((area) => area.id),
+    localAreas: (memoryConfig.areas ?? []).filter((area) => area.scope === 'local').map((area) => area.id),
+    freshAreas: (memoryConfig.areas ?? []).filter((area) => area.freshness === 'fresh').map((area) => area.id),
+    staleAreas: (memoryConfig.areas ?? []).filter((area) => area.freshness === 'stale').map((area) => area.id),
+  };
+  const bounds = { communities: 5, communityItems: 5, memoryAreaItems: 4, fullGraphIncluded: false, archiveBodiesIncluded: status.archiveBodiesIncluded, archiveMapIncluded: true };
+  const quality = {
+    indexedFiles: status.indexedFiles,
+    currentFiles: status.currentFiles,
+    shownCommunities: communities.communities.length,
+    totalCommunities: communities.total,
+    omittedCommunities: communities.omitted,
+    omittedCommunityItems: communities.communities.reduce((sum, community) => sum + (community.omitted ?? 0), 0),
+    memoryAreas: memoryAreas.total,
+    omittedMemoryAreaItems: memoryAreas.areas.reduce((sum, area) => sum + (area.omitted ?? 0), 0),
+    graphNodes: summary.nodes,
+    graphEdges: summary.edges,
+  };
+  const commandGuidance = detectCommandGuidance(options.root);
+  let payload = { root: options.root, cache: status, metadata, graph: summary, memoryConfig, memoryPolicy, memoryAreas, communities, bounds, quality, commandGuidance };
+  const serialized = JSON.stringify(payload);
+  payload = { ...payload, quality: { ...quality, snapshotBytes: Buffer.byteLength(serialized), approxSnapshotTokens: Math.ceil(serialized.length / 4) } };
+  if (options.json) console.log(JSON.stringify(payload, null, 2));
+  else console.log(`dotdotgod load snapshot\n- cache: ${status.status}${metadata.cacheRefreshed ? ' (refreshed)' : ''}\n- indexed files: ${status.indexedFiles}\n- current files: ${status.currentFiles}\n- archive bodies included: ${status.archiveBodiesIncluded ? 'yes' : 'no'}\n- graph: ${summary.nodes} nodes, ${summary.edges} edges\n- memory areas: ${memoryAreas.areas.length}/${memoryAreas.total} shown\n- communities: ${communities.communities.length}/${communities.total} shown, ${communities.omitted} omitted`);
+}

package/src/commands/plan-stage-contract.mjs

@@ -0,0 +1,63 @@
+export const PLAN_STAGE_DIRECTORIES = [
+  '01-intake',
+  '02-context-load',
+  '03-discovery',
+  '04-plan',
+];
+
+export const PLAN_INTERNAL_WORKSPACE = '.dotdotgod-plan';
+
+export const PLAN_INTERNAL_STAGE_DIRECTORIES = [
+  ...PLAN_STAGE_DIRECTORIES,
+  '05-workstream-handoff',
+];
+
+export const PLAN_REQUIRED_HEADERS = {
+  '01-intake': ['Request Summary', 'Goal', 'Scope', 'Non-goals', 'Constraints', 'Assumptions'],
+  '02-context-load': ['Memory Reads', 'Impact Candidates', 'Related Files'],
+  '03-discovery': ['Findings', 'Risks', 'Open Questions'],
+  '04-plan': ['Milestones', 'Atomic Tasks', 'Validation Plan', 'Resume Point'],
+  '05-workstream-handoff': ['Workstream Handoff', 'Todo Contract'],
+};
+
+export const PLAN_CONSTRUCTION_CHECKLISTS = {
+  '01-intake': ['Requirements', 'Constraints', 'Failure paths', 'Data shape', 'Verification', 'Integration impact'],
+  '02-context-load': ['Memory reads', 'Impact candidates', 'Related files', 'Boundary risk'],
+  '03-discovery': ['Findings', 'Risks', 'Open questions', 'Extension points'],
+  '04-plan': ['Milestones', 'Atomic tasks', 'Validation plan', 'Resume point'],
+  '05-workstream-handoff': ['Handoffs', 'Do-not rules', 'Focused verification', 'Chat-independent context'],
+};
+
+export const PLAN_BLOCKER_LABELS = new Map([
+  ['missing-plan', 'Plan file does not exist'],
+  ['invalid-plan-path', 'Plan file must be docs/plan/<task-slug>/README.md'],
+  ['invalid-task-slug', 'Plan task directory must be kebab-case'],
+  ['empty-plan', 'Plan README is empty'],
+  ['missing-stage', 'Missing required stage directory'],
+  ['missing-internal-stage', 'Missing internal stage file'],
+  ['missing-stage-readme', 'Missing stage README.md'],
+  ['invalid-markdown-name', 'Invalid Markdown file name'],
+  ['missing-section', 'Missing required section'],
+  ['empty-section', 'Required section has no content'],
+  ['placeholder-section', 'Required section only contains placeholder content'],
+  ['pending-workstream', 'Required workstream is pending'],
+  ['unresolved-discussion', 'Discussion Queue has unresolved items'],
+  ['unresolved-assumption', 'Assumptions contain unresolved items'],
+  ['missing-atomic-acceptance', 'Atomic Tasks must define acceptance criteria'],
+  ['missing-atomic-verification', 'Atomic Tasks must define verification'],
+  ['missing-construction-checklist', 'Missing construction checklist'],
+  ['missing-checklist-item', 'Missing construction checklist item'],
+  ['malformed-checklist-item', 'Malformed construction checklist item'],
+  ['open-checklist-item', 'Construction checklist item is open'],
+  ['placeholder-checklist-item', 'Construction checklist item only contains placeholder content'],
+]);
+
+export function buildPlanValidationNextStagePrompt(planPath, stage, stagePath) {
+  return [
+    `Continue Plan Mode stage advancement for ${planPath}.`,
+    `Current stage: ${stage}.`,
+    `Make ${planPath} satisfy the current stage's durable README requirements first. Use ${stagePath} only as an optional checkpoint/workflow note for this stage; do not make numbered checkpoint creation the goal and do not create later checkpoint files yet.`,
+    stage === '05-workstream-handoff' ? 'For this stage, ensure the durable README or split UPPER_SNAKE_CASE workstream plan files expose numbered `Plan:` sections so Pi can extract todos during execution. For small plans, explicitly state that no split is needed.' : undefined,
+    `After completing this stage, stop and rerun \`dotdotgod plan validate ${planPath} --stage ${stage} --json\`.`,
+  ].filter(Boolean).join('\n\n');
+}