@dotdotgod/cli 0.1.35 → 0.1.36

package/README.md

@@ -32,6 +32,7 @@ Command-line tools for dotdotgod project memory. The CLI turns explicit, maintai
 - 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`.
+- Validate executable active plans with `dotdotgod plan validate docs/plan/<task-slug>/README.md`.
 - 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.
@@ -56,6 +57,7 @@ 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 graph impact . --changed <path>
 dotdotgod graph impact . --changed <path> --compact
 dotdotgod graph impact . --changed <path> --yml
@@ -71,6 +73,7 @@ dotdotgod graph communities .
 | `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 canonical eight-stage active-plan structure, required Markdown sections, role/area workstreams, decision/assumption blockers, and atomic-task verification before execution. |
 | `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. |
 
 Most users start with `validate`. Use `traceability links --write` only when generated traceability output needs repair, and use `verify` before release-style handoff.

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.36",
   "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');
+}