@dotdotgod/cli 0.1.42 → 0.1.44

package/package.json

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

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

@@ -17,7 +17,14 @@ export const PLAN_REQUIRED_HEADERS = {
   '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'],
+  '05-workstream-handoff': [
+    'Workstream Handoff',
+    'Workstream Map',
+    'Shared Context',
+    'Workstreams',
+    'Integration Sequence',
+    'Todo Contract',
+  ],
 };
 
 export const PLAN_CONSTRUCTION_CHECKLISTS = {
@@ -34,8 +41,9 @@ export const PLAN_BLOCKER_LABELS = new Map([
   ['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'],
+  ['missing-internal-stage', 'Missing internal stage checkpoint'],
+  ['open-internal-stage', 'Internal stage checkpoint is not completed'],
   ['invalid-markdown-name', 'Invalid Markdown file name'],
   ['missing-section', 'Missing required section'],
   ['empty-section', 'Required section has no content'],
@@ -50,14 +58,18 @@ export const PLAN_BLOCKER_LABELS = new Map([
   ['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'],
+  ['missing-workstream-split-decision', 'Workstream Handoff must include an explicit split decision'],
+  ['incomplete-workstream-split', 'Split workstream handoff must include actionable workstream contracts'],
+  ['missing-workstream-no-split-rationale', 'No-split workstream handoff must include rationale'],
 ]);
 
 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,
+    `Update the durable plan for human readers, then make ${stagePath} the machine-readable checkpoint that satisfies the current stage validation contract. Do not create later checkpoint files yet.`,
+    `In ${stagePath}, set Status: completed and include the current stage required sections plus \`## Stage ${stage.slice(0, 2)} Construction Checklist\` rows in the canonical \`- [x] Category: evidence\` form.`,
+    stage === '05-workstream-handoff' ? 'For this stage checkpoint, record `Split decision: yes` or `Split decision: no` in `## Workstream Handoff`. If splitting, make `## Workstream Map`, `## Workstreams`, and `## Integration Sequence` describe multiple actionable workstreams with required context, allowed/forbidden edits, tasks, validation, dependencies, and handoff output. If not splitting, record the no-split rationale and keep `## Todo Contract` actionable so Pi can extract execution todos.' : undefined,
     `After completing this stage, stop and rerun \`dotdotgod plan validate ${planPath} --stage ${stage} --json\`.`,
   ].filter(Boolean).join('\n\n');
 }

package/src/commands/plan.mjs

@@ -201,17 +201,37 @@ function readInternalStageState(taskDir, stageName) {
 
 function validateInternalStageState(root, taskDir, stageName, blockers) {
   const state = readInternalStageState(taskDir, stageName);
-  if (!state) return;
+  const expectedPath = internalStageFile(taskDir, stageName);
+  const rel = projectRelative(root, state?.file ?? expectedPath);
+  if (!state) {
+    addBlocker(blockers, 'missing-internal-stage', `Missing internal stage checkpoint: ${rel}`, { path: rel, stage: stageName });
+    return { state: undefined, valid: false };
+  }
+
+  let valid = true;
   const stage = contentMatch(state.content, /^Stage:\s*(\S+)\s*$/m);
   const status = contentMatch(state.content, /^Status:\s*(created|blocked|completed)\s*$/m);
   const updated = contentMatch(state.content, /^Updated:\s*(\S+)\s*$/m);
-  const rel = projectRelative(root, state.file);
-  const looksLikeGeneratorState = /^Stage:\s*\S+\s*$/m.test(state.content) || /^Status:\s*\S+\s*$/m.test(state.content) || /^Updated:\s*\S+\s*$/m.test(state.content);
-  if (!looksLikeGeneratorState) return;
-  if (stage && stage !== stageName) addBlocker(blockers, 'missing-internal-stage', `Internal stage file has wrong Stage field: ${rel}`, { path: rel, stage: stageName });
-  if (!stage) addBlocker(blockers, 'missing-internal-stage', `Internal stage file is missing Stage: ${rel}`, { path: rel, stage: stageName });
-  if (!status) addBlocker(blockers, 'missing-internal-stage', `Internal stage file is missing valid Status: ${rel}`, { path: rel, stage: stageName });
-  if (!updated) addBlocker(blockers, 'missing-internal-stage', `Internal stage file is missing Updated: ${rel}`, { path: rel, stage: stageName });
+  if (stage && stage !== stageName) {
+    valid = false;
+    addBlocker(blockers, 'missing-internal-stage', `Internal stage file has wrong Stage field: ${rel}`, { path: rel, stage: stageName });
+  }
+  if (!stage) {
+    valid = false;
+    addBlocker(blockers, 'missing-internal-stage', `Internal stage file is missing Stage: ${rel}`, { path: rel, stage: stageName });
+  }
+  if (!status) {
+    valid = false;
+    addBlocker(blockers, 'missing-internal-stage', `Internal stage file is missing valid Status: ${rel}`, { path: rel, stage: stageName });
+  } else if (status !== 'completed') {
+    valid = false;
+    addBlocker(blockers, 'open-internal-stage', `Internal stage checkpoint is not completed: ${rel}`, { path: rel, stage: stageName });
+  }
+  if (!updated) {
+    valid = false;
+    addBlocker(blockers, 'missing-internal-stage', `Internal stage file is missing Updated: ${rel}`, { path: rel, stage: stageName });
+  }
+  return { state, valid };
 }
 
 function contentMatch(content, pattern) {
@@ -273,6 +293,82 @@ function hasUnresolvedAssumption(content) {
   });
 }
 
+function workstreamSplitDecision(content) {
+  const match = /\bsplit\s+decision\s*:\s*(yes|no)\b/i.exec(content);
+  return match?.[1].toLowerCase();
+}
+
+function hasNoSplitRationale(content) {
+  return /\b(?:rationale|reason|because)\b/i.test(content);
+}
+
+function hasMultipleWorkstreams(content) {
+  const normalized = removeCodeBlocks(content).toLowerCase();
+  const explicitIds = new Set([...normalized.matchAll(/\b(?:workstream|ws)\s*[-:#]?\s*([a-z0-9]+)\b/g)].map((match) => match[1]));
+  if (explicitIds.size >= 2) return true;
+  const workstreamMentions = normalized.match(/\bworkstreams?\b/g) ?? [];
+  return workstreamMentions.length >= 2 && /\b(?:multiple|parallel|split)\b/.test(normalized);
+}
+
+function hasActionableWorkstreamFields(content) {
+  const normalized = content.toLowerCase();
+  const fieldGroups = [
+    ['purpose', 'objective'],
+    ['required context', 'read'],
+    ['allowed edit'],
+    ['forbidden edit', 'do not edit', 'do-not edit'],
+    ['task'],
+    ['validation', 'verify'],
+    ['handoff output', 'output'],
+    ['dependenc'],
+  ];
+  return fieldGroups.every((group) => group.some((term) => normalized.includes(term)));
+}
+
+function hasActionableIntegrationFields(content) {
+  const normalized = content.toLowerCase();
+  return ['sequence', 'integrat'].every((term) => normalized.includes(term)) && ['validation', 'verify', 'handoff'].some((term) => normalized.includes(term));
+}
+
+function validateWorkstreamHandoffContract(root, files, stageName, blockers) {
+  if (stageName !== '05-workstream-handoff') return true;
+  let valid = true;
+  const handoff = findSection(files, 'Workstream Handoff');
+  const todo = findSection(files, 'Todo Contract');
+  const relHandoff = projectRelative(root, handoff?.file ?? files[0]);
+  const decision = workstreamSplitDecision(handoff?.content ?? '');
+  if (!decision) {
+    addBlocker(blockers, 'missing-workstream-split-decision', 'Workstream Handoff must include `Split decision: yes` or `Split decision: no`.', { path: relHandoff, stage: stageName, section: 'Workstream Handoff' });
+    return false;
+  }
+  if (decision === 'no') {
+    if (!hasNoSplitRationale(handoff.content)) {
+      valid = false;
+      addBlocker(blockers, 'missing-workstream-no-split-rationale', 'Workstream Handoff with `Split decision: no` must include a rationale.', { path: relHandoff, stage: stageName, section: 'Workstream Handoff' });
+    }
+    if (!todo || !contentHasValue(todo.content) || isPlaceholderContent(todo.content)) valid = false;
+    return valid;
+  }
+
+  const map = findSection(files, 'Workstream Map');
+  const workstreams = findSection(files, 'Workstreams');
+  const integration = findSection(files, 'Integration Sequence');
+  const splitContent = [map?.content, workstreams?.content, integration?.content].filter(Boolean).join('\n');
+  if (!hasMultipleWorkstreams(splitContent)) {
+    valid = false;
+    addBlocker(blockers, 'incomplete-workstream-split', 'Split Stage 05 handoff must indicate multiple workstreams in Workstream Map, Workstreams, or Integration Sequence.', { path: projectRelative(root, map?.file ?? workstreams?.file ?? integration?.file ?? handoff.file), stage: stageName, section: 'Workstream Map' });
+  }
+  if (!workstreams || !hasActionableWorkstreamFields(workstreams.content)) {
+    valid = false;
+    addBlocker(blockers, 'incomplete-workstream-split', 'Workstreams must mention purpose/objective, required context/read, allowed edits, forbidden edits/do-not-edit, tasks, validation, handoff output, and dependencies.', { path: projectRelative(root, workstreams?.file ?? handoff.file), stage: stageName, section: 'Workstreams' });
+  }
+  if (!integration || !hasActionableIntegrationFields(integration.content)) {
+    valid = false;
+    addBlocker(blockers, 'incomplete-workstream-split', 'Integration Sequence must describe actionable integration sequence and validation/handoff expectations.', { path: projectRelative(root, integration?.file ?? handoff.file), stage: stageName, section: 'Integration Sequence' });
+  }
+  return valid;
+}
+
 function constructionChecklistHeader(stageName) {
   const match = /^(\d{2})-/.exec(stageName);
   return `Stage ${match?.[1] ?? stageName} Construction Checklist`;
@@ -416,28 +512,28 @@ export function validatePlanArtifact(planPath, options = {}) {
   const durableFiles = discoverDurablePlanMarkdownFiles(taskDir);
   if (durableFiles.length > 1) summary.splitFiles.detected = true;
   for (const stageName of stagesToValidate) {
-    validateInternalStageState(root, taskDir, stageName, blockers);
-    const files = durableFiles.length > 0 ? durableFiles : [absolutePlanPath];
-    const stageReadme = absolutePlanPath;
-    summary.stages.present += 1;
-    let stageValid = true;
+    const internal = validateInternalStageState(root, taskDir, stageName, blockers);
+    summary.stages.present += internal.state ? 1 : 0;
+    let stageValid = internal.valid;
+    const files = internal.state ? [internal.state.file] : [];
+    const fallbackPath = projectRelative(root, internalStageFile(taskDir, stageName));
     for (const header of PLAN_REQUIRED_HEADERS[stageName]) {
-      const found = findSection(files, header);
+      const found = files.length > 0 ? findSection(files, header) : undefined;
       if (!found) {
         stageValid = false;
-        addBlocker(blockers, 'missing-section', `Missing required section: ## ${header}`, { path: projectRelative(root, stageReadme), stage: stageName, section: header });
+        addBlocker(blockers, 'missing-section', `Missing required section in internal checkpoint: ## ${header}`, { path: fallbackPath, stage: stageName, section: header });
         continue;
       }
       summary.requiredSections.present += 1;
       const relFound = projectRelative(root, found.file);
       if (!contentHasValue(found.content)) {
         stageValid = false;
-        addBlocker(blockers, 'empty-section', `Required section has no content: ## ${header}`, { path: relFound, stage: stageName, section: header });
+        addBlocker(blockers, 'empty-section', `Required checkpoint section has no content: ## ${header}`, { path: relFound, stage: stageName, section: header });
         continue;
       }
       if (isPlaceholderContent(found.content)) {
         stageValid = false;
-        addBlocker(blockers, 'placeholder-section', `Required section only contains placeholder content: ## ${header}`, { path: relFound, stage: stageName, section: header });
+        addBlocker(blockers, 'placeholder-section', `Required checkpoint section only contains placeholder content: ## ${header}`, { path: relFound, stage: stageName, section: header });
         continue;
       }
       summary.requiredSections.valid += 1;
@@ -465,7 +561,8 @@ export function validatePlanArtifact(planPath, options = {}) {
         addBlocker(blockers, 'unresolved-assumption', 'Assumptions contain unresolved items.', { path: relFound, stage: stageName, section: header });
       }
     }
-    if (!validateConstructionChecklist(root, files, stageName, blockers)) stageValid = false;
+    if (files.length > 0 && !validateWorkstreamHandoffContract(root, files, stageName, blockers)) stageValid = false;
+    if (files.length > 0 && !validateConstructionChecklist(root, files, stageName, blockers)) stageValid = false;
     if (stageValid) summary.stages.valid += 1;
   }
 

package/src/validate/run.mjs

@@ -35,6 +35,7 @@ export function runValidate(argv) {
     if (path.includes('/node_modules') || path === 'node_modules') return true;
     if (path.includes('/.git') || path === '.git') return true;
     if (path === CACHE_DIR || path.startsWith(`${CACHE_DIR}/`)) return true;
+    if (/^docs\/(?:plan|archive\/plan)\/[a-z0-9]+(?:-[a-z0-9]+)*\/\.dotdotgod-plan(?:\/|$)/.test(path)) return true;
     if (!options.includeLocalMemory && (path === 'docs/plan' || path.startsWith('docs/plan/') || path === 'docs/archive' || path.startsWith('docs/archive/'))) return true;
     return false;
   };