sdd-agent-platform 0.4.1 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/registries/agent-registry.ts

@@ -1,146 +1,230 @@
-import { readFile } from 'node:fs/promises';
-import { AGENT_REGISTRY_CONTRACT_VERSION } from '../contracts.js';
-import { parseProjectConfig } from '../config/project-config.js';
-import { getProjectConfigPath } from '../runtime-paths.js';
-
-export type AgentAutonomyCeiling = 'read_only' | 'foreground_write' | 'validation_only' | 'review_only';
-
-export interface AgentRegistryEntry {
-  version: typeof AGENT_REGISTRY_CONTRACT_VERSION;
-  id: string;
-  role: string;
-  allowedStages: string[];
-  capabilities: string[];
-  readBoundary: string[];
-  writeBoundary: string[];
-  toolAllowlist: string[];
-  requiredArtifact: string;
-  verificationExpectation: string;
-  autonomyCeiling: AgentAutonomyCeiling;
-  stopCondition: string;
-}
-
-export interface AgentRegistry {
-  version: typeof AGENT_REGISTRY_CONTRACT_VERSION;
-  agents: AgentRegistryEntry[];
-}
-
-const BUILT_IN_AGENT_REGISTRY: AgentRegistryEntry[] = [
-  {
-    version: AGENT_REGISTRY_CONTRACT_VERSION,
-    id: 'scout',
-    role: 'Collect bounded local context and uncertainty without editing files.',
-    allowedStages: ['spec', 'plan', 'do', 'doctor'],
-    capabilities: ['read files', 'search symbols', 'summarize evidence', 'identify gaps'],
-    readBoundary: ['project files', 'spec/plan/task snippets', 'existing artifacts'],
-    writeBoundary: ['artifacts/scout-<task>.md only when explicitly requested'],
-    toolAllowlist: ['read', 'grep', 'glob', 'semantic search'],
-    requiredArtifact: 'artifacts/scout-<task>.md',
-    verificationExpectation: 'Findings are evidence-backed and scoped to the exploration question.',
-    autonomyCeiling: 'read_only',
-    stopCondition: 'Stop when evidence paths and remaining uncertainty are clear.'
-  },
-  {
-    version: AGENT_REGISTRY_CONTRACT_VERSION,
-    id: 'spec-reviewer',
-    role: 'Review requirements, scope, non-goals, and acceptance clarity.',
-    allowedStages: ['spec', 'plan'],
-    capabilities: ['requirements review', 'gap detection', 'acceptance clarity check'],
-    readBoundary: ['spec document', 'user request', 'related plan snippets'],
-    writeBoundary: ['review artifact or proposed spec edits after approval'],
-    toolAllowlist: ['read', 'grep'],
-    requiredArtifact: 'artifacts/spec-review-<task>.md',
-    verificationExpectation: 'Spec gaps are explicit and do not silently advance to plan.',
-    autonomyCeiling: 'review_only',
-    stopCondition: 'Stop when spec is ready for plan or blocking gaps are listed.'
-  },
-  {
-    version: AGENT_REGISTRY_CONTRACT_VERSION,
-    id: 'planner',
-    role: 'Design the task-ready technical solution, including architecture impact, risk controls, validation strategy, and implementation slices.',
-    allowedStages: ['plan', 'tasks'],
-    capabilities: ['impact analysis', 'technical solution design', 'PlantUML diagramming', 'slice planning', 'validation planning'],
-    readBoundary: ['approved spec', 'existing architecture docs', 'relevant files'],
-    writeBoundary: ['specs/<branch>/plan.md or planning artifact'],
-    toolAllowlist: ['read', 'grep', 'glob'],
-    requiredArtifact: 'specs/<branch>/plan.md',
-    verificationExpectation: 'Plan includes current state, target design, risk-driven technical sections, validation matrix, task breakdown rationale, and unresolved gaps.',
-    autonomyCeiling: 'review_only',
-    stopCondition: 'Stop before implementation or when task readiness gaps remain.'
-  },
-  {
-    version: AGENT_REGISTRY_CONTRACT_VERSION,
-    id: 'implementer',
-    role: 'Apply minimal foreground changes for one selected task boundary.',
-    allowedStages: ['do'],
-    capabilities: ['edit files', 'run bounded validation', 'produce implementation evidence'],
-    readBoundary: ['selected task', 'approved spec/plan', 'affected files'],
-    writeBoundary: ['declared affected files', 'artifacts/implement-<task>.md'],
-    toolAllowlist: ['read', 'edit', 'write scoped artifacts', 'validation command'],
-    requiredArtifact: 'artifacts/implement-<task>.md',
-    verificationExpectation: 'Changes stay inside boundary and are ready for independent review.',
-    autonomyCeiling: 'foreground_write',
-    stopCondition: 'Stop on boundary expansion, missing validation, or required human checkpoint.'
-  },
-  {
-    version: AGENT_REGISTRY_CONTRACT_VERSION,
-    id: 'reviewer',
-    role: 'Review diff and task evidence against boundary and acceptance.',
-    allowedStages: ['do', 'verify'],
-    capabilities: ['diff review', 'risk check', 'gap report'],
-    readBoundary: ['diff', 'task metadata', 'implementation artifact'],
-    writeBoundary: ['artifacts/review-<task>.md'],
-    toolAllowlist: ['read', 'grep', 'git diff'],
-    requiredArtifact: 'artifacts/review-<task>.md',
-    verificationExpectation: 'Review decision is traceable to task boundary and acceptance.',
-    autonomyCeiling: 'review_only',
-    stopCondition: 'Stop when approval, requested changes, or blocking gaps are explicit.'
-  },
-  {
-    version: AGENT_REGISTRY_CONTRACT_VERSION,
-    id: 'debugger',
-    role: 'Investigate one validation failure without broad retry loops.',
-    allowedStages: ['do'],
-    capabilities: ['failure triage', 'minimal fix proposal', 'gap isolation'],
-    readBoundary: ['validation output', 'changed files', 'task boundary'],
-    writeBoundary: ['artifacts/debug-<task>.md', 'minimal fix only after checkpoint'],
-    toolAllowlist: ['read', 'grep', 'validation command'],
-    requiredArtifact: 'artifacts/debug-<task>.md',
-    verificationExpectation: 'Failure cause and fix boundary are explicit.',
-    autonomyCeiling: 'foreground_write',
-    stopCondition: 'Stop after one bounded attempt or when cause is unclear.'
-  },
-  {
-    version: AGENT_REGISTRY_CONTRACT_VERSION,
-    id: 'validator',
-    role: 'Map acceptance criteria to review, diff, and command evidence.',
-    allowedStages: ['verify'],
-    capabilities: ['run declared validation', 'acceptance mapping', 'evidence sufficiency summary'],
-    readBoundary: ['task acceptance', 'review artifact', 'validation outputs'],
-    writeBoundary: ['artifacts/validation-<task>.md'],
-    toolAllowlist: ['read', 'validation command'],
-    requiredArtifact: 'artifacts/validation-<task>.md',
-    verificationExpectation: 'PASS requires acceptance evidence, not just command success.',
-    autonomyCeiling: 'validation_only',
-    stopCondition: 'Stop when acceptance evidence mapping and unresolved gaps are clear.'
-  }
-];
-
-export async function listAgentRegistry(projectRoot: string): Promise<AgentRegistry> {
-  await assertProjectConfigReadable(projectRoot);
-  return {
-    version: AGENT_REGISTRY_CONTRACT_VERSION,
-    agents: [...BUILT_IN_AGENT_REGISTRY].sort((left, right) => left.id.localeCompare(right.id))
-  };
-}
-
-export async function inspectAgentRegistryEntry(projectRoot: string, agentId: string): Promise<AgentRegistryEntry | null> {
-  const registry = await listAgentRegistry(projectRoot);
-  return registry.agents.find((agent) => agent.id === agentId) ?? null;
-}
-
-async function assertProjectConfigReadable(projectRoot: string): Promise<void> {
-  const configPath = getProjectConfigPath(projectRoot);
-  const raw = await readFile(configPath, 'utf8');
-  parseProjectConfig(raw, configPath);
-}
+import { readFile } from 'node:fs/promises';
+import { AGENT_REGISTRY_CONTRACT_VERSION } from '../contracts.js';
+import { parseProjectConfig } from '../config/project-config.js';
+import { getProjectConfigPath } from '../runtime-paths.js';
+
+export type AgentAutonomyCeiling = 'read_only' | 'foreground_write' | 'validation_only' | 'review_only';
+
+export interface AgentRegistryEntry {
+  version: typeof AGENT_REGISTRY_CONTRACT_VERSION;
+  id: string;
+  role: string;
+  allowedStages: string[];
+  capabilities: string[];
+  readBoundary: string[];
+  writeBoundary: string[];
+  toolAllowlist: string[];
+  requiredArtifact: string;
+  verificationExpectation: string;
+  autonomyCeiling: AgentAutonomyCeiling;
+  stopCondition: string;
+}
+
+export interface AgentRegistry {
+  version: typeof AGENT_REGISTRY_CONTRACT_VERSION;
+  agents: AgentRegistryEntry[];
+}
+
+const BUILT_IN_AGENT_REGISTRY: AgentRegistryEntry[] = [
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'scout',
+    role: 'Resolve bounded researchable uncertainty with evidence without editing files.',
+    allowedStages: ['spec', 'plan', 'execute', 'doctor'],
+    capabilities: ['read files', 'search symbols', 'summarize evidence', 'resolve researchable uncertainty', 'separate evidence inference and assumption', 'identify remaining gaps'],
+    readBoundary: ['project files', 'spec/plan/task snippets', 'accepted stage evidence', 'authorized external references'],
+    writeBoundary: ['.sdd/runs/<branch>/<stage>/scout-vN.md only when explicitly requested'],
+    toolAllowlist: ['read', 'grep', 'glob', 'semantic search'],
+    requiredArtifact: '.sdd/runs/<branch>/<stage>/scout-vN.md',
+    verificationExpectation: 'Findings are evidence-backed, scoped to the researchable question, and explicit about remaining uncertainty.',
+    autonomyCeiling: 'read_only',
+    stopCondition: 'Stop when researchable uncertainty is resolved or clearly classified as remaining uncertainty.'
+  },
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'spec-manager',
+    role: 'Own spec-stage synthesis, problem reframing, ambiguity routing, final spec.md writing, and close readiness evidence.',
+    allowedStages: ['spec'],
+    capabilities: ['intent discovery', 'problem reframing', 'content quality chain', 'ambiguity classification', 'research delegation', 'spec synthesis', 'close quality evidence'],
+    readBoundary: ['user request', 'current spec document', 'template', 'spec-stage work order', 'scout and review evidence'],
+    writeBoundary: ['specs/<branch>/spec.md', '.sdd/runs/<branch>/spec/spec-manager-vN.md'],
+    toolAllowlist: ['read', 'grep', 'glob', 'write final spec', 'write scoped evidence'],
+    requiredArtifact: 'specs/<branch>/spec.md',
+    verificationExpectation: 'Final spec is problem-reframed, delta-focused, explicit about ambiguity, and ready for runtime close review.',
+    autonomyCeiling: 'foreground_write',
+    stopCondition: 'Stop before runtime close when blocking user decisions remain or review finds unresolved spec gaps.'
+  },
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'spec-reviewer',
+    role: 'Pressure-review problem reframing, intent confidence, scope, non-goals, acceptance evidence, and ambiguity routing.',
+    allowedStages: ['spec'],
+    capabilities: ['problem reframing review', 'change delta quality check', 'acceptance evidence check', 'ambiguity routing review', 'candidate wording detection', 'plan task leakage check', 'repairable finding output'],
+    readBoundary: ['spec document', 'user request', 'scout evidence', 'spec-manager side evidence'],
+    writeBoundary: ['.sdd/runs/<branch>/spec/spec-review-vN.md'],
+    toolAllowlist: ['read', 'grep'],
+    requiredArtifact: '.sdd/runs/<branch>/spec/spec-review-vN.md',
+    verificationExpectation: 'Spec gaps are explicit, correctly classified, and do not silently advance to plan.',
+    autonomyCeiling: 'review_only',
+    stopCondition: 'Stop when spec is ready for runtime close review or blocking gaps are listed.'
+  },
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'plan-manager',
+    role: 'Own plan-stage synthesis, bounded domain scouting coordination, final technical design writing, and close readiness evidence.',
+    allowedStages: ['plan'],
+    capabilities: ['accepted spec trace', 'technical design synthesis', 'grounded implementation mapping', 'fact to decision reasoning', 'field api sql mapping', 'state failure rollback modeling', 'scenario validation strategy', 'task-stage constraint framing'],
+    readBoundary: ['accepted spec', 'current plan document', 'plan template', 'plan-stage work order', 'project files', 'plan-scout and review evidence'],
+    writeBoundary: ['specs/<branch>/plan.md', '.sdd/runs/<branch>/plan/plan-manager-vN.md'],
+    toolAllowlist: ['read', 'grep', 'glob', 'write final plan', 'write scoped evidence'],
+    requiredArtifact: 'specs/<branch>/plan.md',
+    verificationExpectation: 'Final plan is an AI-ready technical design with concrete surfaces, mappings, state/failure depth, risk controls, validation scenarios, and no task decomposition.',
+    autonomyCeiling: 'foreground_write',
+    stopCondition: 'Stop before runtime close when blocking design decisions remain or review finds unresolved plan gaps.'
+  },
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'plan-scout',
+    role: 'Resolve bounded plan-stage domain uncertainty with evidence-to-plan obligations under a requested domain lens.',
+    allowedStages: ['plan'],
+    capabilities: ['domain evidence scouting', 'implementation surface discovery', 'design implication discovery', 'constraint discovery', 'risk discovery', 'validation hook discovery', 'evidence inference separation'],
+    readBoundary: ['accepted spec', 'current plan snippets', 'requested domain references', 'project files', 'authorized external references'],
+    writeBoundary: ['.sdd/runs/<branch>/plan/plan-scout-vN.md'],
+    toolAllowlist: ['read', 'grep', 'glob', 'semantic search'],
+    requiredArtifact: '.sdd/runs/<branch>/plan/plan-scout-vN.md',
+    verificationExpectation: 'Findings are scoped to the requested domain and state evidence, design implications, target plan sections, and remaining uncertainty.',
+    autonomyCeiling: 'read_only',
+    stopCondition: 'Stop when the requested domain question has evidence, constraints, risks, validation hooks, and remaining uncertainty.'
+  },
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'plan-review-agent',
+    role: 'Pressure-review final plan.md V3 for technical design depth, spec trace, mapping coverage, state/failure model, validation strategy, and task-list leakage.',
+    allowedStages: ['plan'],
+    capabilities: ['reasoning-depth review', 'spec trace review', 'field api sql mapping review', 'state failure rollback review', 'risk validation review', 'scenario validation review', 'dense but shallow detection', 'task-list leakage review'],
+    readBoundary: ['accepted spec', 'final plan draft', 'plan-scout findings', 'plan template rubric'],
+    writeBoundary: ['.sdd/runs/<branch>/plan/plan-review-vN.md'],
+    toolAllowlist: ['read', 'grep'],
+    requiredArtifact: '.sdd/runs/<branch>/plan/plan-review-vN.md',
+    verificationExpectation: 'Review signal is explicit and cannot declare runtime accepted truth.',
+    autonomyCeiling: 'review_only',
+    stopCondition: 'Stop when approve, revise, or blocked findings are explicit.'
+  },
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'tasks-manager',
+    role: 'Own tasks-stage synthesis, coverage mapping, final tasks.md writing, and close readiness evidence.',
+    allowedStages: ['tasks'],
+    capabilities: ['accepted spec plan trace', 'task decomposition synthesis', 'readable task brief synthesis', 'rollback unit framing', 'internal execution sequence framing', 'one-to-one validation mapping', 'dependency rationale framing', 'completion evidence design', 'failure route framing'],
+    readBoundary: ['accepted spec', 'accepted plan', 'current tasks document', 'tasks template', 'tasks-stage work order', 'task-slicer and review evidence'],
+    writeBoundary: ['specs/<branch>/tasks.md', '.sdd/runs/<branch>/tasks/tasks-manager-vN.md'],
+    toolAllowlist: ['read', 'grep', 'glob', 'write final tasks', 'write scoped evidence'],
+    requiredArtifact: 'specs/<branch>/tasks.md',
+    verificationExpectation: 'Final tasks are executable work units with context, upstream trace, boundaries, rollback units, internal sequence for broad units, dependency rationale, completion evidence, one-to-one validation mapping, validation expected results, and failure routes.',
+    autonomyCeiling: 'foreground_write',
+    stopCondition: 'Stop before runtime close when task boundaries, rollback units, validation expectations, or failure routes remain unresolved.'
+  },
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'task-slicer',
+    role: 'Propose task decomposition by rollback unit, dependency unlock, validation closure, and shared writable ownership.',
+    allowedStages: ['tasks'],
+    capabilities: ['rollback unit analysis', 'internal sequence analysis', 'dependency unlock analysis', 'one-to-one validation closure analysis', 'parallelism safety review', 'boundary conflict detection'],
+    readBoundary: ['accepted spec', 'accepted plan', 'current tasks snippets', 'requested slicing question'],
+    writeBoundary: ['.sdd/runs/<branch>/tasks/task-slicer-vN.md'],
+    toolAllowlist: ['read', 'grep'],
+    requiredArtifact: '.sdd/runs/<branch>/tasks/task-slicer-vN.md',
+    verificationExpectation: 'Findings explain proposed work units, rollback units, internal sequence for broad units, dependency rationale, one-to-one validation closure, parallelism safety, and boundary conflicts without becoming runtime truth.',
+    autonomyCeiling: 'review_only',
+    stopCondition: 'Stop when slicing recommendation and conflicts are explicit.'
+  },
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'task-review-agent',
+    role: 'Pressure-review final tasks.md for execute usability, boundaries, rollback, dependency rationale, validation expected results, and failure routes.',
+    allowedStages: ['tasks'],
+    capabilities: ['execute usability review', 'upstream trace review', 'modification boundary review', 'rollback unit review', 'internal sequence review', 'dependency rationale review', 'schema first task detection', 'one-to-one validation mapping review', 'validation expected result review', 'failure route review'],
+    readBoundary: ['accepted spec', 'accepted plan', 'final tasks draft', 'task-slicer findings'],
+    writeBoundary: ['.sdd/runs/<branch>/tasks/task-review-vN.md'],
+    toolAllowlist: ['read', 'grep'],
+    requiredArtifact: '.sdd/runs/<branch>/tasks/task-review-vN.md',
+    verificationExpectation: 'Review identifies too-thin tasks, checklist tasks, oversized tasks without sequence, many-to-one validation, boundary conflicts, validation gaps, and scope expansion before runtime close.',
+    autonomyCeiling: 'review_only',
+    stopCondition: 'Stop when pass, revise, or blocked findings are explicit.'
+  },
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'implementer',
+    role: 'Apply minimal foreground changes for one selected task boundary.',
+    allowedStages: ['execute'],
+    capabilities: ['edit files', 'run bounded validation', 'produce implementation evidence'],
+    readBoundary: ['selected task', 'approved spec/plan', 'affected files'],
+    writeBoundary: ['declared affected files', '.sdd/runs/<branch>/execute/implementation-vN.md'],
+    toolAllowlist: ['read', 'edit', 'write scoped evidence', 'validation command'],
+    requiredArtifact: '.sdd/runs/<branch>/execute/implementation-vN.md',
+    verificationExpectation: 'Changes stay inside boundary and are ready for independent review.',
+    autonomyCeiling: 'foreground_write',
+    stopCondition: 'Stop on boundary expansion, missing validation, or required human checkpoint.'
+  },
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'reviewer',
+    role: 'Review diff and task evidence against boundary and acceptance.',
+    allowedStages: ['execute'],
+    capabilities: ['diff review', 'risk check', 'gap report'],
+    readBoundary: ['diff', 'task metadata', 'implementation evidence'],
+    writeBoundary: ['.sdd/runs/<branch>/execute/code-review-vN.md'],
+    toolAllowlist: ['read', 'grep', 'git diff'],
+    requiredArtifact: '.sdd/runs/<branch>/execute/code-review-vN.md',
+    verificationExpectation: 'Review decision is traceable to task boundary and acceptance.',
+    autonomyCeiling: 'review_only',
+    stopCondition: 'Stop when approval, requested changes, or blocking gaps are explicit.'
+  },
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'debugger',
+    role: 'Investigate one validation failure without broad retry loops.',
+    allowedStages: ['execute'],
+    capabilities: ['failure triage', 'minimal fix proposal', 'gap isolation'],
+    readBoundary: ['validation output', 'changed files', 'task boundary'],
+    writeBoundary: ['.sdd/runs/<branch>/execute/debug-vN.md', 'minimal fix only after checkpoint'],
+    toolAllowlist: ['read', 'grep', 'validation command'],
+    requiredArtifact: '.sdd/runs/<branch>/execute/debug-vN.md',
+    verificationExpectation: 'Failure cause and fix boundary are explicit.',
+    autonomyCeiling: 'foreground_write',
+    stopCondition: 'Stop after one bounded attempt or when cause is unclear.'
+  },
+  {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    id: 'validator',
+    role: 'Map acceptance criteria to review, diff, and command evidence.',
+    allowedStages: ['execute'],
+    capabilities: ['run declared validation', 'acceptance mapping', 'evidence sufficiency summary'],
+    readBoundary: ['task acceptance', 'review evidence', 'validation outputs'],
+    writeBoundary: ['.sdd/runs/<branch>/execute/validation-vN.md'],
+    toolAllowlist: ['read', 'validation command'],
+    requiredArtifact: '.sdd/runs/<branch>/execute/validation-vN.md',
+    verificationExpectation: 'PASS requires acceptance evidence, not just command success.',
+    autonomyCeiling: 'validation_only',
+    stopCondition: 'Stop when acceptance evidence mapping and unresolved gaps are clear.'
+  }
+];
+
+export async function listAgentRegistry(projectRoot: string): Promise<AgentRegistry> {
+  await assertProjectConfigReadable(projectRoot);
+  return {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    agents: [...BUILT_IN_AGENT_REGISTRY].sort((left, right) => left.id.localeCompare(right.id))
+  };
+}
+
+export async function inspectAgentRegistryEntry(projectRoot: string, agentId: string): Promise<AgentRegistryEntry | null> {
+  const registry = await listAgentRegistry(projectRoot);
+  return registry.agents.find((agent) => agent.id === agentId) ?? null;
+}
+
+async function assertProjectConfigReadable(projectRoot: string): Promise<void> {
+  const configPath = getProjectConfigPath(projectRoot);
+  const raw = await readFile(configPath, 'utf8');
+  parseProjectConfig(raw, configPath);
+}