@jaimevalasek/aioson 1.7.0 → 1.8.0

package/src/parser.js

@@ -19,7 +19,14 @@ function parseArgv(argv) {
       // Boolean-only flags that never consume the next token
       const boolOnly = new Set([
         'all', 'force', 'dry-run', 'no-interactive', 'fix', 'json',
-        'help', 'version', 'no-launch', 'attach'
+        'help', 'version', 'no-launch', 'attach', 'tmux',
+        'allow-warnings', 'install-hook', 'uninstall-hook', 'remove-hook',
+        'agent-safe',
+        'status', 'suggest', 'apply',
+        // `--resume` alone means "resume last"; `--resume=<id>` carries a value
+        // and is handled by the `=` branch above. Without this entry, `--resume`
+        // followed by `--tool=claude` would swallow the next token as its value.
+        'resume'
       ]);
 
       const next = tokens[i + 1];

package/src/path-guard.js

@@ -0,0 +1,47 @@
+'use strict';
+
+/**
+ * path-guard — canonical path resolution helpers for agent prompts.
+ *
+ * Prevents agents from misplacing files by injecting the project map
+ * into implementation agent prompts.
+ */
+
+const path = require('node:path');
+const { readFileSafe, fileExists } = require('./preflight-engine');
+
+const PROJECT_MAP_PATH = '.aioson/context/project-map.md';
+
+const FALLBACK_RULES = `
+## Path Conventions (fallback)
+
+- When the user says \`/docs/\`, they mean the project root \`docs/\` folder, not \`.aioson/docs/\`.
+- When the user specifies a target directory, confirm the exact path before creating files.
+- Never replace or remove existing content (log entries, list items, config entries) unless explicitly asked. Only append or modify the targeted item.
+- Framework artifacts (specs, state, handoffs) belong in \`.aioson/context/\`.
+`.trim();
+
+async function loadProjectMap(targetDir) {
+  const mapPath = path.join(targetDir, PROJECT_MAP_PATH);
+  if (await fileExists(mapPath)) {
+    const content = await readFileSafe(mapPath);
+    if (content) return content.trim();
+  }
+  return FALLBACK_RULES;
+}
+
+async function buildPathGuardBlock(targetDir) {
+  const map = await loadProjectMap(targetDir);
+  return [
+    '## Canonical Path Rules',
+    '> Resolve all file paths using the map below. Confirm ambiguous paths with the user before creating files.',
+    '',
+    map
+  ].join('\n');
+}
+
+module.exports = {
+  buildPathGuardBlock,
+  loadProjectMap,
+  PROJECT_MAP_PATH
+};

package/src/preflight-engine.js

@@ -145,6 +145,10 @@ function rulesDir(targetDir) {
   return path.join(targetDir, '.aioson', 'rules');
 }
 
+function designDocsDir(targetDir) {
+  return path.join(targetDir, '.aioson', 'design-docs');
+}
+
 function artifactPath(targetDir, name, slug) {
   const dir = contextDir(targetDir);
   if (slug) return path.join(dir, `${name}-${slug}.md`);
@@ -161,6 +165,61 @@ async function loadProjectContext(targetDir) {
   return { exists: true, data, content };
 }
 
+// ─── Sheldon manifest scanner ─────────────────────────────────────────────────
+
+function parseManifestPhaseTable(content) {
+  if (!content) return [];
+  const phases = [];
+  const tableRe = /^\|([^|]+)\|([^|]+)\|([^|]+)\|([^|]+)\|$/gm;
+  let match;
+  let headerPassed = false;
+  while ((match = tableRe.exec(content)) !== null) {
+    const cols = [match[1], match[2], match[3], match[4]].map((c) => c.trim());
+    if (!headerPassed) {
+      // Skip header row and separator row
+      if (cols[0].toLowerCase() === 'phase' || /^-+$/.test(cols[0])) {
+        headerPassed = cols[0].toLowerCase() === 'phase';
+        continue;
+      }
+    }
+    if (!headerPassed) continue;
+    if (/^-+$/.test(cols[0])) continue;
+    const phaseNum = parseInt(cols[0], 10);
+    if (!Number.isFinite(phaseNum)) continue;
+    phases.push({ phase: phaseNum, file: cols[1].replace(/`/g, ''), status: cols[2], purpose: cols[3] });
+  }
+  return phases;
+}
+
+async function scanActiveManifest(targetDir, slug) {
+  if (!slug) return { exists: false };
+  const manifestPath = path.join(targetDir, '.aioson', 'plans', slug, 'manifest.md');
+  const stat = await fileStat(manifestPath);
+  if (!stat) return { exists: false };
+  const content = await readFileSafe(manifestPath);
+  const fm = content ? parseFrontmatter(content) : {};
+  const status = fm.status || null;
+  const isDone = status === 'complete' || status === 'done';
+
+  // Parse phase table to find the first pending phase (AC-SDLC-27)
+  const phases = parseManifestPhaseTable(content);
+  const DONE_STATUSES = new Set(['done', 'complete', 'qa_approved', 'completed']);
+  const nextPendingPhase = phases.find((p) => !DONE_STATUSES.has(String(p.status).toLowerCase())) || null;
+
+  return {
+    exists: true,
+    path: `.aioson/plans/${slug}/manifest.md`,
+    status,
+    is_active: !isDone,
+    phases,
+    next_pending_phase: nextPendingPhase ? {
+      phase: nextPendingPhase.phase,
+      file: nextPendingPhase.file,
+      status: nextPendingPhase.status
+    } : null
+  };
+}
+
 // ─── Artifact scanner ─────────────────────────────────────────────────────────
 
 async function scanArtifacts(targetDir, slug) {
@@ -305,6 +364,31 @@ async function detectClassification(targetDir, slug) {
 
 // ─── Rules discovery ──────────────────────────────────────────────────────────
 
+function parseAgentList(value) {
+  if (value === undefined || value === null) return null;
+  const raw = String(value).trim();
+  if (!raw) return [];
+  if (raw === '[]') return [];
+  if (raw.startsWith('[') && raw.endsWith(']')) {
+    return raw
+      .slice(1, -1)
+      .split(',')
+      .map((item) => item.trim().replace(/^["']|["']$/g, ''))
+      .filter(Boolean);
+  }
+  return raw
+    .split(',')
+    .map((item) => item.trim().replace(/^["']|["']$/g, ''))
+    .filter(Boolean);
+}
+
+function appliesToAgent(frontmatter, agent) {
+  const agents = parseAgentList(frontmatter.agents);
+  if (agents === null) return true;
+  if (agents.length === 0) return true;
+  return agents.includes('all') || agents.includes(agent);
+}
+
 async function discoverRules(targetDir, agent) {
   const dir = rulesDir(targetDir);
   const rules = [];
@@ -318,76 +402,197 @@ async function discoverRules(targetDir, agent) {
 
   for (const entry of entries) {
     if (!entry.endsWith('.md')) continue;
+    if (entry.toLowerCase() === 'readme.md') continue;
     const content = await readFileSafe(path.join(dir, entry));
     if (!content) continue;
 
     // Check applicability: universal rules or agent-specific
     const fm = parseFrontmatter(content);
-    const applies = !fm.agents || fm.agents.includes('all') || fm.agents.includes(agent);
-    if (applies) rules.push(entry);
+    if (appliesToAgent(fm, agent)) rules.push(entry);
   }
 
-  return rules;
+  return rules.sort();
+}
+
+async function discoverDesignDocs(targetDir, agent) {
+  const dir = designDocsDir(targetDir);
+  const docs = [];
+
+  let entries;
+  try {
+    entries = await fs.readdir(dir);
+  } catch {
+    return docs;
+  }
+
+  for (const entry of entries) {
+    if (!entry.endsWith('.md')) continue;
+    if (entry.toLowerCase() === 'readme.md') continue;
+    const content = await readFileSafe(path.join(dir, entry));
+    if (!content) continue;
+
+    const fm = parseFrontmatter(content);
+    if (!appliesToAgent(fm, agent)) continue;
+    docs.push(path.join('.aioson', 'design-docs', entry).split(path.sep).join('/'));
+  }
+
+  return docs.sort();
 }
 
 // ─── Context package builder ──────────────────────────────────────────────────
 
-function buildContextPackage(agent, slug, classification, artifacts, devState) {
+function buildContextPackage(agent, slug, classification, artifacts, devState, manifest) {
   const pkg = [];
 
   if (artifacts.project_context.exists) pkg.push(artifacts.project_context.path);
 
   if (slug) {
-    // Feature-specific context
-    if (artifacts.spec.exists) pkg.push(artifacts.spec.path);
-    if (artifacts.implementation_plan.exists) pkg.push(artifacts.implementation_plan.path);
-    if (artifacts.requirements.exists && ['analyst', 'architect', 'dev'].includes(agent)) {
+    const downstreamAgents = ['pm', 'orchestrator', 'dev', 'deyvin', 'qa'];
+    const shouldCarryFullFeatureContext = downstreamAgents.includes(agent);
+
+    if (shouldCarryFullFeatureContext && artifacts.prd.exists) pkg.push(artifacts.prd.path);
+    if (shouldCarryFullFeatureContext && artifacts.sheldon_enrichment.exists) pkg.push(artifacts.sheldon_enrichment.path);
+    if ((shouldCarryFullFeatureContext || ['analyst', 'architect'].includes(agent)) && artifacts.requirements.exists) {
       pkg.push(artifacts.requirements.path);
     }
+
+    if (artifacts.spec.exists) pkg.push(artifacts.spec.path);
+
+    if (shouldCarryFullFeatureContext && artifacts.architecture.exists) pkg.push(artifacts.architecture.path);
+    if (shouldCarryFullFeatureContext && artifacts.conformance.exists) pkg.push(artifacts.conformance.path);
+
+    // Manifest precedence (AC-SDLC-24, AC-SDLC-25):
+    // If active Sheldon manifest exists and is not done, it is the primary execution artifact.
+    // implementation-plan is supporting context only.
+    if (manifest && manifest.exists && manifest.is_active && (agent === 'dev' || agent === 'deyvin')) {
+      pkg.push(manifest.path + ' [PRIMARY — active Sheldon manifest]');
+      if (manifest.next_pending_phase && manifest.next_pending_phase.file) {
+        pkg.push(path.join(path.dirname(manifest.path), manifest.next_pending_phase.file).split(path.sep).join('/') + ' [current phase]');
+      }
+      if (artifacts.implementation_plan.exists) {
+        pkg.push(artifacts.implementation_plan.path + ' [supporting context only]');
+      }
+    } else if (artifacts.implementation_plan.exists) {
+      pkg.push(artifacts.implementation_plan.path);
+    }
   }
 
   // Agent-specific additions
-  if (agent === 'dev' && artifacts.dev_state.exists) pkg.push('dev-state.md (check for active state)');
-  if (agent === 'qa' && artifacts.spec.exists) pkg.push(artifacts.spec.path);
+  if (agent === 'dev' && artifacts.dev_state.exists) pkg.push('dev-state.md (check for stale state before using)');
   if (agent === 'architect' && artifacts.architecture.exists) pkg.push(artifacts.architecture.path);
 
   return [...new Set(pkg)];
 }
 
+// ─── Stale dev-state detection ───────────────────────────────────────────────
+
+function detectStaleDevState(devState, slug) {
+  if (!devState.exists) return null;
+  if (devState.status === 'done') {
+    return `dev-state.md is marked done (feature: ${devState.active_feature || 'unknown'}) — it belongs to a completed session and should not be used as active context`;
+  }
+  if (slug && devState.active_feature && devState.active_feature !== slug) {
+    return `dev-state.md belongs to feature "${devState.active_feature}", not "${slug}" — load the correct dev-state or ignore this one`;
+  }
+  return null;
+}
+
 // ─── Readiness evaluator ─────────────────────────────────────────────────────
 
-function evaluateReadiness(artifacts, phaseGates, classification, agent) {
+function evaluateReadiness(artifacts, phaseGates, classification, agent, devState, slug) {
   const blockers = [];
+  const warnings = [];
 
   if (!artifacts.project_context.exists) blockers.push('project.context.md missing');
 
-  if (agent === 'dev') {
+  if (agent === 'sheldon') {
+    if (!artifacts.prd.exists) {
+      blockers.push('prd file missing — @product must produce prd-{slug}.md first');
+    }
+    if (!artifacts.sheldon_enrichment.exists) {
+      warnings.push('sheldon-enrichment file not found — this will be a first-session enrichment');
+    }
+  }
+
+  if (agent === 'analyst') {
+    if (!artifacts.prd.exists) blockers.push('prd file missing — @product must produce prd-{slug}.md first');
+  }
+
+  if (agent === 'architect') {
+    if (!artifacts.requirements.exists) {
+      blockers.push('requirements file missing — @analyst must produce requirements-{slug}.md first (Gate A)');
+    }
+  }
+
+  if (agent === 'pm') {
+    if (!artifacts.architecture.exists) {
+      blockers.push('architecture.md missing — @architect must complete design first (Gate B)');
+    }
+    if (!artifacts.requirements.exists) {
+      warnings.push('requirements file missing — @pm should review it before writing the implementation plan');
+    }
+  }
+
+  if (agent === 'orchestrator') {
+    if (!artifacts.requirements.exists) {
+      blockers.push('requirements file missing — Gate A not satisfied');
+    }
+    if (!artifacts.spec.exists) {
+      blockers.push('spec file missing — Gate C not satisfied');
+    }
+    const implementationPlan = artifacts.implementation_plan || { exists: false, frontmatter: {} };
+    if (classification === 'MEDIUM' && !implementationPlan.exists) {
+      blockers.push('implementation-plan-{slug}.md missing — @pm must produce it before orchestration');
+    } else if (classification === 'MEDIUM' && implementationPlan.frontmatter.status !== 'approved') {
+      blockers.push(`implementation plan is not approved: ${implementationPlan.frontmatter.status || 'missing status'} — @pm must approve it`);
+    }
+    if (phaseGates.plan !== 'approved') {
+      blockers.push(`Gate C (plan) not approved: ${phaseGates.plan || 'pending'} — @pm must produce and approve implementation-plan-{slug}.md`);
+    }
+  }
+
+  if (agent === 'dev' || agent === 'deyvin') {
     if (!artifacts.spec.exists) blockers.push('spec file missing');
-    if (phaseGates.plan && phaseGates.plan !== 'approved') {
-      blockers.push(`Gate C (plan) not approved: ${phaseGates.plan || 'pending'}`);
+    if (classification === 'MEDIUM') {
+      const implementationPlan = artifacts.implementation_plan || { exists: false, frontmatter: {} };
+      if (!implementationPlan.exists) {
+        blockers.push('implementation-plan-{slug}.md missing — @pm must produce it before implementation');
+      } else if (implementationPlan.frontmatter.status !== 'approved') {
+        blockers.push(`implementation plan is not approved: ${implementationPlan.frontmatter.status || 'missing status'}`);
+      }
+    }
+    if (classification && classification !== 'MICRO') {
+      if (phaseGates.plan !== 'approved') {
+        blockers.push(`Gate C (plan) not approved: ${phaseGates.plan || 'pending'} — run "aioson gate:check . --feature=${slug || '<slug>'} --gate=C"`);
+      }
+    }
+    // Dev-state stale check
+    if (devState) {
+      const staleWarning = detectStaleDevState(devState, slug);
+      if (staleWarning) warnings.push(`dev-state stale: ${staleWarning}`);
     }
   }
 
   if (agent === 'qa') {
     if (!artifacts.spec.exists) blockers.push('spec file missing');
+    if (classification === 'MEDIUM') {
+      const implementationPlan = artifacts.implementation_plan || { exists: false, frontmatter: {} };
+      if (!implementationPlan.exists) {
+        blockers.push('implementation-plan-{slug}.md missing');
+      } else if (implementationPlan.frontmatter.status !== 'approved') {
+        blockers.push(`implementation plan is not approved: ${implementationPlan.frontmatter.status || 'missing status'}`);
+      }
+    }
     if (classification && classification !== 'MICRO') {
-      if (phaseGates.plan && phaseGates.plan !== 'approved') {
+      if (phaseGates.plan !== 'approved') {
         blockers.push(`Gate C (plan) not approved: ${phaseGates.plan || 'pending'}`);
       }
     }
   }
 
-  if (agent === 'analyst') {
-    if (!artifacts.prd.exists) blockers.push('prd file missing');
-  }
-
-  if (agent === 'architect') {
-    if (!artifacts.requirements.exists) blockers.push('requirements file missing');
-  }
-
-  return blockers.length === 0
-    ? { status: 'READY', blockers: [] }
-    : { status: 'BLOCKED', blockers };
+  if (blockers.length > 0) return { status: 'BLOCKED', blockers, warnings };
+  if (warnings.length > 0) return { status: 'READY_WITH_WARNINGS', blockers: [], warnings };
+  return { status: 'READY', blockers: [], warnings: [] };
 }
 
 // ─── Spec version extractor ───────────────────────────────────────────────────
@@ -425,17 +630,23 @@ module.exports = {
   detectTestRunner,
   contextDir,
   rulesDir,
+  designDocsDir,
   artifactPath,
   loadProjectContext,
   scanArtifacts,
+  scanActiveManifest,
   parseGatesFromSpec,
   readPhaseGates,
   readDevState,
   readProjectPulse,
   detectClassification,
+  parseAgentList,
+  appliesToAgent,
   discoverRules,
+  discoverDesignDocs,
   buildContextPackage,
   evaluateReadiness,
+  detectStaleDevState,
   extractSpecVersion,
   extractLastCheckpoint,
   GATE_NAMES,

package/src/self-healing.js

@@ -0,0 +1,142 @@
+'use strict';
+
+/**
+ * self-healing — auto-retry state and prompt building for failed agent stages.
+ *
+ * Keeps retry counters and error logs so `workflow:heal` can re-run a stage
+ * with corrective context without human re-prompting.
+ */
+
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const { ensureDir } = require('./utils');
+
+const MAX_RETRIES = 3;
+const RETRIES_DIR = '.aioson/context/pipeline-retries';
+const ERRORS_PATH = '.aioson/context/workflow.errors.jsonl';
+
+async function readJsonlLast(filePath, predicate) {
+  try {
+    const content = await fs.readFile(filePath, 'utf8');
+    const lines = content.trim().split('\n').filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const obj = JSON.parse(lines[i]);
+      if (!predicate || predicate(obj)) return obj;
+    }
+  } catch {
+    // ignore read/parse errors
+  }
+  return null;
+}
+
+async function getRetryCount(targetDir, stage) {
+  const retriesPath = path.join(targetDir, RETRIES_DIR, `${stage}.json`);
+  try {
+    const raw = await fs.readFile(retriesPath, 'utf8');
+    const data = JSON.parse(raw);
+    return Number(data.count || 0);
+  } catch {
+    return 0;
+  }
+}
+
+async function incrementRetryCount(targetDir, stage, errorSummary) {
+  const retriesPath = path.join(targetDir, RETRIES_DIR, `${stage}.json`);
+  await ensureDir(path.dirname(retriesPath));
+  const count = await getRetryCount(targetDir, stage);
+  const payload = {
+    stage,
+    count: count + 1,
+    lastError: errorSummary || '',
+    updatedAt: new Date().toISOString()
+  };
+  await fs.writeFile(retriesPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+  return payload.count;
+}
+
+async function logError(targetDir, stage, errorMessage, gateType) {
+  const errorsPath = path.join(targetDir, ERRORS_PATH);
+  await ensureDir(path.dirname(errorsPath));
+  const entry = {
+    ts: new Date().toISOString(),
+    stage,
+    gateType: gateType || 'technical',
+    error: errorMessage || ''
+  };
+  await fs.appendFile(errorsPath, `${JSON.stringify(entry)}\n`, 'utf8');
+}
+
+async function getLastError(targetDir, stage) {
+  const errorsPath = path.join(targetDir, ERRORS_PATH);
+  return readJsonlLast(errorsPath, (obj) => obj.stage === stage);
+}
+
+function canRetry(targetDir, stage) {
+  return getRetryCount(targetDir, stage).then((c) => c < MAX_RETRIES);
+}
+
+function buildHealingPrompt(basePrompt, stage, lastError, retryCount) {
+  const remaining = MAX_RETRIES - retryCount;
+  const healingBlock = [
+    '',
+    '## 🩹 Self-Healing Context (auto-injected by AIOSON motor)',
+    '',
+    `> This is retry attempt **${retryCount}** of **${MAX_RETRIES}** for stage @${stage}.`,
+    `> **${remaining}** attempt(s) remain before escalation to the user.`,
+    '',
+    '### Error that caused the previous failure',
+    '```',
+    lastError.error || 'Unknown error',
+    '```',
+    '',
+    '### Your task now',
+    `1. Read the error above carefully.`,
+    `2. Identify the root cause in the codebase (files, types, mocks, paths, etc.).`,
+    `3. Apply the minimal fix needed to resolve the error.`,
+    `4. Re-run the verification command (e.g., \`tsc --noEmit\`, \`cargo check\`, tests) to confirm the fix.`,
+    `5. Only then finish the stage.`,
+    '',
+    '> Do NOT change unrelated code. Focus only on the error shown above.',
+    ''
+  ].join('\n');
+
+  return basePrompt + healingBlock;
+}
+
+async function buildHealingActivation(targetDir, state, stage, locale, tool, activateStageFn) {
+  const retryCount = await getRetryCount(targetDir, stage);
+  const lastError = await getLastError(targetDir, stage);
+
+  if (!lastError) {
+    throw new Error(`No recorded error found for stage @${stage}. Run the stage normally first.`);
+  }
+
+  const baseActivation = await activateStageFn(targetDir, state, locale, tool, stage);
+  const healingPrompt = buildHealingPrompt(
+    baseActivation.prompt || '',
+    stage,
+    lastError,
+    retryCount + 1
+  );
+
+  return {
+    ...baseActivation,
+    prompt: healingPrompt,
+    healing: true,
+    retryCount: retryCount + 1,
+    maxRetries: MAX_RETRIES
+  };
+}
+
+module.exports = {
+  MAX_RETRIES,
+  RETRIES_DIR,
+  ERRORS_PATH,
+  getRetryCount,
+  incrementRetryCount,
+  logError,
+  getLastError,
+  canRetry,
+  buildHealingPrompt,
+  buildHealingActivation
+};