@popoverai/dotrequirements 0.24.2 → 0.25.0

package/dist/templates/workflows/specify-codebase.js

@@ -0,0 +1,372 @@
+export const meta = {
+  name: 'specify-codebase',
+  description:
+    'Codebase-to-spec: autonomously plan a behavioral outline, fan out specifiers across its areas, and converge each area via independent review + editor passes — no mid-run human input',
+  whenToUse:
+    'Invoked by the codebase-to-spec skill after `cts pack`. Not run directly.',
+  phases: [
+    { title: 'Outline' },
+    { title: 'Specify' },
+    { title: 'Converge' },
+    { title: 'Reconcile' },
+  ],
+}
+
+// Injected globals: agent, pipeline, parallel, phase, log, args.
+//
+// args:
+//   cli              — resolved dotrequirements CLI invocation workers shell out to
+//                      (e.g. "dotrequirements" or "node /abs/path/packages/cli/dist/cli.js")
+//   roundsCap        — max review→edit rounds per area before giving up (default 5)
+//   outlineRoundsCap — max plan→review→revise rounds for the outline (default 4)
+//   crossAreaRoundsCap — max cross-area review→edit rounds on the composed spec (default 5)
+//
+// The caps are a runaway backstop, not a target: an area stops the moment its
+// reviewer approves, and reports `unconverged` if it can't converge in N rounds.
+// Defaults are set high enough to give careful review room on messy codebases.
+//
+// args may arrive as a JSON string depending on how the caller passes it; normalize.
+const input = typeof args === 'string' ? JSON.parse(args) : args || {}
+// `cli` defaults to the PATH binary for installed users; the dev repo passes a
+// `node <repo>/dist/cli.js` invocation explicitly.
+const {
+  cli = 'dotrequirements',
+  roundsCap = 5,
+  outlineRoundsCap = 4,
+  crossAreaRoundsCap = 5,
+} = input
+
+// --- Schemas (mirrors of the JSON Schemas in schemas.ts; a sync test guards drift) ---
+
+const PARTIAL_RESULT_SCHEMA = {
+  type: 'object',
+  properties: {
+    area_prefix: { type: 'string' },
+    partial_path: { type: 'string' },
+    status: { type: 'string', enum: ['drafted', 'skipped-resume'] },
+    requirement_count: { type: 'integer', minimum: 0 },
+  },
+  required: ['area_prefix', 'partial_path', 'status'],
+  additionalProperties: false,
+}
+
+const REVIEW_VERDICT_SCHEMA = {
+  type: 'object',
+  properties: {
+    result: { type: 'string', enum: ['approved', 'needs-revision'] },
+    revisions: { type: 'array', items: { type: 'string' } },
+  },
+  required: ['result'],
+  additionalProperties: false,
+}
+
+// Shape `cts dispatch-spec` emits (one entry per approved-outline area).
+const AREAS_SCHEMA = {
+  type: 'object',
+  properties: {
+    areas: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          dispatch_id: { type: 'string' },
+          area_prefix: { type: 'string' },
+          area_name: { type: 'string' },
+          output_path: { type: 'string' },
+        },
+        required: ['dispatch_id', 'area_prefix', 'area_name', 'output_path'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['areas'],
+  additionalProperties: false,
+}
+
+// Thin self-compose wrapper: a worker fetches its full instructions from the CLI.
+function follow(line) {
+  return [
+    `Run exactly this command: ${line}`,
+    `It prints JSON of the form {"prompt": "..."}. Read the "prompt" field and follow it EXACTLY.`,
+  ]
+}
+
+// ============================ Stage 0: outline ============================
+// plan → review → revise → re-review, until the outline reviewer approves the
+// area decomposition or the cap is hit. Sequential (one outline), so the
+// reviewer's writes to the document-level review.thread never contend.
+phase('Outline')
+
+await agent(
+  [
+    `You are a codebase-to-spec planner. Produce the behavioral-area outline for the packed codebase.`,
+    ...follow(`${cli} cts dispatch-context planner-initial`),
+    `End with a one-line confirmation of the outline path you wrote.`,
+  ].join('\n'),
+  { agentType: 'cts-worker', label: 'plan outline', phase: 'Outline' },
+)
+
+let outlineApproved = false
+for (let round = 1; round <= outlineRoundsCap; round++) {
+  const verdict = await agent(
+    [
+      `You are a codebase-to-spec outline reviewer (independent of the planner).`,
+      ...follow(`${cli} cts dispatch-context outline-reviewer`),
+      `It tells you to record your verdict in the outline's top-level review thread and return it.`,
+      `Return { "result": "approved" | "needs-revision", "revisions": [...] }.`,
+    ].join('\n'),
+    {
+      schema: REVIEW_VERDICT_SCHEMA,
+      agentType: 'cts-worker',
+      label: `review outline r${round}`,
+      phase: 'Outline',
+    },
+  )
+
+  // Fail-closed: only an explicit "approved" verdict advances. A null verdict
+  // (reviewer subagent died after retries) is treated as non-approval — fall
+  // through to revise/re-review so we never fan out an unreviewed outline.
+  if (verdict?.result === 'approved') {
+    outlineApproved = true
+    break
+  }
+  if (round === outlineRoundsCap) break
+
+  await agent(
+    [
+      `You are a codebase-to-spec planner applying the reviewer's outline revisions.`,
+      ...follow(`${cli} cts dispatch-context planner-revise-${round + 1}`),
+      `End with a one-line confirmation.`,
+    ].join('\n'),
+    { agentType: 'cts-worker', label: `revise outline r${round}`, phase: 'Outline' },
+  )
+}
+
+if (!outlineApproved) {
+  // No mid-run HITL: don't fan out a decomposition the reviewer wouldn't pass.
+  log(`outline did not converge within ${outlineRoundsCap} rounds`)
+  return {
+    status: 'outline-unconverged',
+    outline_rounds: outlineRoundsCap,
+    areas: [],
+    converged_count: 0,
+    unconverged: [],
+    failed: [],
+    total: 0,
+  }
+}
+
+// ===================== Stage 1+2: fan out + converge =====================
+// Enumerate the approved outline's areas (an agent runs the CLI; the script
+// can't), then run each area through specify → review/edit independently.
+phase('Specify')
+
+const enumerated = await agent(
+  [
+    `Run exactly this command: ${cli} cts dispatch-spec`,
+    `It prints a JSON array, one entry per area of the approved outline.`,
+    `Return { "areas": <that array, verbatim> }.`,
+  ].join('\n'),
+  { schema: AREAS_SCHEMA, agentType: 'cts-worker', label: 'enumerate areas', phase: 'Specify' },
+)
+
+// Fail-closed: a dead enumerate agent (null return) must surface as a failure,
+// not read as an empty-but-successful decomposition that sails through fan-out
+// and reconcile to a hollow `done`.
+if (!enumerated) {
+  log('area enumeration failed — cannot fan out')
+  return {
+    status: 'enumerate-failed',
+    areas: [],
+    converged_count: 0,
+    unconverged: [],
+    failed: [],
+    total: 0,
+  }
+}
+const areas = enumerated.areas
+
+async function specify(area) {
+  return agent(
+    [
+      `You are a codebase-to-spec specifier worker for the area "${area.area_name}" (prefix ${area.area_prefix}).`,
+      ``,
+      `Step 1 — Resume check. If a non-empty partial already exists at:`,
+      `    ${area.output_path}`,
+      `  then do NOT regenerate it. Return`,
+      `  { "area_prefix": "${area.area_prefix}", "partial_path": "${area.output_path}", "status": "skipped-resume" }.`,
+      ``,
+      `Step 2 — Otherwise, run exactly this command:`,
+      `    ${cli} cts dispatch-context specifier-${area.area_prefix}`,
+      `  Read the "prompt" field of its JSON output and follow it EXACTLY — which source files to`,
+      `  read, how to ground requirements in this area's customers, where to write the partial,`,
+      `  and how to validate + style-check it.`,
+      ``,
+      `Step 3 — Return`,
+      `  { "area_prefix": "${area.area_prefix}", "partial_path": "${area.output_path}",`,
+      `    "status": "drafted", "requirement_count": <number of requirements you wrote> }.`,
+    ].join('\n'),
+    {
+      schema: PARTIAL_RESULT_SCHEMA,
+      agentType: 'cts-worker',
+      label: `specify ${area.area_name}`,
+      phase: 'Specify',
+    },
+  )
+}
+
+async function reviewEditLoop(specifyResult, area) {
+  // Fail-closed (CTSO-INTEG-3.2): a dead specifier (null return) means there may
+  // be no partial to review — record the failure and continue with the other
+  // areas, instead of burning review/edit rounds on a draft that may not exist.
+  if (!specifyResult) {
+    log(`area ${area.area_prefix}: specifier failed — recording and moving on`)
+    return {
+      area_prefix: area.area_prefix,
+      area_name: area.area_name,
+      partial_path: area.output_path,
+      status: 'failed',
+      rounds: 0,
+    }
+  }
+
+  for (let round = 1; round <= roundsCap; round++) {
+    const verdict = await agent(
+      [
+        `You are a codebase-to-spec reviewer for the area "${area.area_name}" (prefix ${area.area_prefix}).`,
+        ...follow(`${cli} cts dispatch-context reviewer-${area.area_prefix}`),
+        `It tells you to review the partial, record your verdict in the outline, and return it.`,
+        `Return { "result": "approved" | "needs-revision", "revisions": [...] }.`,
+      ].join('\n'),
+      {
+        schema: REVIEW_VERDICT_SCHEMA,
+        agentType: 'cts-worker',
+        label: `review ${area.area_name} r${round}`,
+        phase: 'Converge',
+      },
+    )
+
+    if (verdict?.result === 'approved') {
+      return {
+        area_prefix: area.area_prefix,
+        area_name: area.area_name,
+        partial_path: area.output_path,
+        status: 'converged',
+        rounds: round - 1,
+      }
+    }
+
+    // Fail-closed: a null verdict (dead reviewer) is NOT approval — but it also
+    // recorded no fresh revisions in the outline, so dispatching an editor here
+    // would only re-apply the previous round's already-applied list (or have
+    // nothing to act on in round 1). Skip straight to the next review round.
+    if (!verdict) continue
+
+    // Mirror the outline and cross-area loops: the final round's verdict is
+    // final. Without this guard a last editor pass would run whose output is
+    // never re-reviewed before composition.
+    if (round === roundsCap) break
+
+    await agent(
+      [
+        `You are a codebase-to-spec editor for the area "${area.area_name}" (prefix ${area.area_prefix}).`,
+        ...follow(`${cli} cts dispatch-context editor-${area.area_prefix}`),
+        `It embeds the reviewer's revisions and tells you to apply them, then validate + style-check.`,
+        `Return { "area_prefix": "${area.area_prefix}", "partial_path": "${area.output_path}",`,
+        `  "status": "drafted", "requirement_count": <number of requirements now in the partial> }.`,
+      ].join('\n'),
+      {
+        schema: PARTIAL_RESULT_SCHEMA,
+        agentType: 'cts-worker',
+        label: `edit ${area.area_name} r${round}`,
+        phase: 'Converge',
+      },
+    )
+  }
+
+  log(`area ${area.area_prefix} hit roundsCap=${roundsCap} without approval`)
+  return {
+    area_prefix: area.area_prefix,
+    area_name: area.area_name,
+    partial_path: area.output_path,
+    status: 'unconverged',
+    rounds: roundsCap,
+  }
+}
+
+log(`Outline approved — fanning out ${areas.length} area(s)`)
+
+const results = (await pipeline(areas, specify, reviewEditLoop)).filter(Boolean)
+
+// ===================== Stage 3: compose + cross-area reconcile =====================
+// The per-area partials have converged. Assemble them into one composed spec
+// (deterministic), then run the document-level cross-area review/edit loop
+// (CTSO-CONV-5) — duplication, terminology drift, and seam gaps that only a
+// whole-document view catches — before the skill presents the result.
+phase('Reconcile')
+
+await agent(
+  [
+    `Run exactly this command: ${cli} cts compose-orchestrator`,
+    `It deterministically assembles the converged area partials into a single composed spec.`,
+    `End with a one-line confirmation of the composed-spec path it reports.`,
+  ].join('\n'),
+  { agentType: 'cts-worker', label: 'compose spec', phase: 'Reconcile' },
+)
+
+let crossAreaRounds = 0
+let crossAreaConverged = false
+for (let round = 1; round <= crossAreaRoundsCap; round++) {
+  crossAreaRounds = round
+  const verdict = await agent(
+    [
+      `You are a codebase-to-spec cross-area reviewer (document-level, independent).`,
+      ...follow(`${cli} cts dispatch-context cross-area-reviewer`),
+      `It tells you to review the composed spec for cross-area + document-level issues, record your verdict in the outline, and return it.`,
+      `Return { "result": "approved" | "needs-revision", "revisions": [...] }.`,
+    ].join('\n'),
+    {
+      schema: REVIEW_VERDICT_SCHEMA,
+      agentType: 'cts-worker',
+      label: `cross-area review r${round}`,
+      phase: 'Reconcile',
+    },
+  )
+
+  // Fail-closed: only an explicit "approved" verdict ends the loop. A null
+  // verdict (dead reviewer) is non-approval — fall through to edit/re-review.
+  if (verdict?.result === 'approved') {
+    crossAreaConverged = true
+    break
+  }
+  if (round === crossAreaRoundsCap) break
+
+  // The reviewer recorded its revisions in the outline's crossAreaReview thread;
+  // the compose editor self-composes from there and edits the composed spec.
+  await agent(
+    [
+      `You are a codebase-to-spec compose editor applying cross-area revisions to the composed spec.`,
+      ...follow(`${cli} cts dispatch-context compose-editor`),
+      `It embeds the cross-area reviewer's revisions and tells you to apply them, then validate.`,
+      `End with a one-line confirmation.`,
+    ].join('\n'),
+    { agentType: 'cts-worker', label: `compose edit r${round}`, phase: 'Reconcile' },
+  )
+}
+
+if (!crossAreaConverged) {
+  log(`cross-area review did not converge within ${crossAreaRoundsCap} rounds`)
+}
+
+return {
+  status: 'done',
+  areas: results,
+  converged_count: results.filter((r) => r.status === 'converged').length,
+  unconverged: results
+    .filter((r) => r.status === 'unconverged')
+    .map((r) => r.area_prefix),
+  failed: results.filter((r) => r.status === 'failed').map((r) => r.area_prefix),
+  total: areas.length,
+  cross_area_rounds: crossAreaRounds,
+  cross_area_converged: crossAreaConverged,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.24.2",
+  "version": "0.25.0",
   "description": "Requirements tracking CLI, test harness, and MCP server",
   "type": "module",
   "bin": {
@@ -71,7 +71,7 @@
     "@types/node": "^20",
     "@types/uuid": "^11.0.0",
     "typescript": "^5",
-    "vitest": "^4.0.0"
+    "vitest": "^4.1.8"
   },
   "files": [
     "dist",