@popoverai/dotrequirements 0.24.1 → 0.24.3

package/dist/codebase-to-spec/schemas.js

@@ -10,6 +10,10 @@
  */
 import { z } from "zod";
 // ---------- Outline ----------
+export const CustomerSchema = z.object({
+    name: z.string().min(1),
+    description: z.string().min(1),
+});
 export const AreaSchema = z.object({
     name: z.string().min(1),
     description: z.string().min(1),
@@ -17,6 +21,13 @@ export const AreaSchema = z.object({
         .string()
         .regex(/^[A-Z][A-Z0-9_]*$/, "prefix must be uppercase alphanumeric/underscore"),
     files: z.array(z.string()).min(0),
+    /**
+     * Customers this area serves — at least one. Each customer is a *user* of
+     * the software (not a contributor to its codebase). The specifier will use
+     * one of these as the persona it grounds the area's requirements in.
+     * See CTS-PLAN-1 (customer threading).
+     */
+    customers: z.array(CustomerSchema).min(1),
 });
 export const OutlineSchema = z.object({
     title: z.string().min(1),
@@ -45,8 +56,21 @@ export const OUTLINE_JSON_SCHEMA = {
                     description: { type: "string" },
                     prefix: { type: "string" },
                     files: { type: "array", items: { type: "string" } },
+                    customers: {
+                        type: "array",
+                        minItems: 1,
+                        items: {
+                            type: "object",
+                            properties: {
+                                name: { type: "string" },
+                                description: { type: "string" },
+                            },
+                            required: ["name", "description"],
+                            additionalProperties: false,
+                        },
+                    },
                 },
-                required: ["name", "description", "prefix", "files"],
+                required: ["name", "description", "prefix", "files", "customers"],
                 additionalProperties: false,
             },
         },
@@ -165,6 +189,139 @@ export const SPEC_REVIEW_JSON_SCHEMA = {
     ],
     additionalProperties: false,
 };
+// ---------- Conversational orchestrator outline (Phase 2b refactor) ----------
+//
+// The conversational orchestrator uses a single evolving `outline.yaml` as
+// the pipeline's substrate. The outline carries both the behavioral spec
+// content (areas, customers, source_files) AND its own lifecycle state
+// (review.result + review.thread). This is distinct from the legacy
+// `OutlineSchema` above, which the `cts run` pipeline still uses.
+//
+// Field naming uses "result" rather than "verdict" deliberately: review is
+// a collaborative interaction with the worker, not a juridical ruling.
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+export const ConversationalCustomerSchema = z.object({
+    description: z.string().min(1),
+});
+/**
+ * One entry in the review thread (project-level or per-area). Discriminated
+ * on `result`:
+ *
+ * - `approved`: no revisions required.
+ * - `needs-revision`: must include a non-empty `revisions` list — each
+ *   entry is a clear, actionable instruction for the next planner pass.
+ */
+export const ConversationalReviewEntrySchema = z.discriminatedUnion("result", [
+    z.object({
+        result: z.literal("approved"),
+    }),
+    z.object({
+        result: z.literal("needs-revision"),
+        revisions: z.array(z.string()).min(1),
+    }),
+]);
+/**
+ * Review state. Used both at the project level (outline.review) and per
+ * area (area.review). `result` mirrors the latest thread entry's result
+ * so callers can query state without walking the thread.
+ */
+export const ConversationalReviewSchema = z.object({
+    result: z.enum(["approved", "needs-revision"]),
+    thread: z.array(ConversationalReviewEntrySchema).min(1),
+});
+export const ConversationalAreaSchema = z.object({
+    name: z.string().min(1),
+    prefix: z
+        .string()
+        .regex(/^[A-Z][A-Z0-9_]*$/, "prefix must be uppercase alphanumeric/underscore"),
+    description: z.string().min(1),
+    source_files: z.array(z.string()).min(0),
+    customers: z.array(ConversationalCustomerSchema).min(1),
+    /**
+     * Per-area review state — same shape as the project-level review.
+     * Optional: planner output doesn't include it; CA adds it after reviewing
+     * a partial. Tracks the per-area iteration loop (specify → review →
+     * editor → re-review → approved) the same way `outline.review` tracks
+     * the outline iteration loop.
+     */
+    review: ConversationalReviewSchema.optional(),
+});
+export const ConversationalOutlineSchema = z.object({
+    title: z.string().min(1),
+    defaultPrefix: z
+        .string()
+        .regex(/^[A-Z][A-Z0-9_]*$/, "defaultPrefix must be uppercase alphanumeric/underscore"),
+    summary: z.string().min(1),
+    review: ConversationalReviewSchema.optional(),
+    areas: z.array(ConversationalAreaSchema).min(1),
+});
+/**
+ * Parse YAML text against the conversational outline schema. Throws with
+ * a descriptive message on parse or validation failure.
+ */
+export function parseConversationalOutline(text) {
+    let raw;
+    try {
+        raw = parseYaml(text);
+    }
+    catch (err) {
+        throw new Error(`Outline YAML is invalid: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return ConversationalOutlineSchema.parse(raw);
+}
+/**
+ * Synthesize a short customer `name` from a conversational customer's
+ * `description`. The orchestrator's `ConversationalCustomerSchema` only
+ * carries description, but the legacy `CustomerSchema` requires both
+ * `name` and `description`. Adapter use only — downstream compose/present
+ * stages don't read `name`, so this is a schema-shape bridge, not a
+ * semantic field.
+ *
+ * Heuristic: descriptions like "Priya, a CTS pipeline operator" yield
+ * "Priya" via first comma-segment. Otherwise truncate to 40 chars.
+ */
+function synthesizeCustomerName(description) {
+    const firstSegment = description.split(",")[0]?.trim() ?? "";
+    if (firstSegment.length > 0 && firstSegment.length <= 40) {
+        return firstSegment;
+    }
+    return description.slice(0, 40).trim() || description;
+}
+/**
+ * Adapt a conversational orchestrator outline to the legacy Outline shape
+ * for use with stages that still take the legacy schema (compose, present).
+ *
+ * Discards orchestrator-only fields (review); maps `source_files` → `files`;
+ * bridges the customer-shape difference by synthesizing a `name` from each
+ * conversational customer's description.
+ */
+export function conversationalOutlineToLegacy(outline) {
+    return {
+        title: outline.title,
+        defaultPrefix: outline.defaultPrefix,
+        summary: outline.summary,
+        areas: outline.areas.map((a) => ({
+            name: a.name,
+            description: a.description,
+            prefix: a.prefix,
+            files: a.source_files,
+            customers: a.customers.map((c) => ({
+                name: synthesizeCustomerName(c.description),
+                description: c.description,
+            })),
+        })),
+    };
+}
+/**
+ * Serialize a conversational outline back to YAML text. Uses literal-block
+ * multi-line strings (`|`) where possible for readability.
+ */
+export function stringifyConversationalOutline(outline) {
+    return stringifyYaml(outline, {
+        lineWidth: 0,
+        blockQuote: "literal",
+    });
+}
 export function parseSpecReview(text) {
     const trimmed = text.trim();
     let raw;

package/dist/codebase-to-spec/skill-install.d.ts

@@ -1,34 +1,39 @@
 /**
  * Skill installation logic for the codebase-to-spec skill.
  *
- * The skill is a thin conversational wrapper around `dotrequirements cts run`.
- * It ships as a SKILL.md template bundled in the CLI package, and this module
- * copies it into the host's skill directory (default: `.claude/skills/` for
- * Claude Code).
+ * Ships as a bundle: SKILL.md + cts-worker agent definition + persona-
+ * injection hook script + hook registration in `.claude/settings.local.json`.
+ * The skill body (the conversational orchestrator) DEPENDS on the companion
+ * files — installing just the skill without them would leave Task dispatches
+ * unable to resolve their persona. For `project` scope, all four pieces are
+ * installed in one shot. For `global` and `custom` scopes, only the skill
+ * body is installed; the companions are project-scoped by CC convention.
  *
  * Host portability (CTS-SKILL-5): the install logic supports any host that
  * follows the Agent Skills format. The default target is Claude Code's
  * convention; `--target-dir` lets users place the skill anywhere.
  *
  * Requirements covered:
- * - CTS-SKILL-1: skill artifact exists and points users at `dotrequirements cts run`
- * - CTS-SKILL-5: install logic is host-agnostic and works on any host with
- *   Agent Skills format support
+ * - CTS-SKILL-1, CTS-SKILL-5
+ * - CTSO-CLI-1 (bundles the agent + hook that PreToolUse-injects persona bodies)
  */
 export type SkillInstallScope = "project" | "global" | "custom";
 export interface SkillInstallOptions {
     /**
      * Where to install:
      * - `project` (default): `<projectRoot>/.claude/skills/codebase-to-spec/`
-     * - `global`: `~/.claude/skills/codebase-to-spec/`
-     * - `custom`: requires `targetDir`
+     *   (plus companions under `<projectRoot>/.claude/agents/` and
+     *   `<projectRoot>/.claude/hooks/`, and hook registration in
+     *   `<projectRoot>/.claude/settings.local.json`)
+     * - `global`: `~/.claude/skills/codebase-to-spec/` (skill body only)
+     * - `custom`: requires `targetDir` (skill body only)
      */
     scope?: SkillInstallScope;
     /** Required when `scope === 'custom'`. The skill directory will be created here. */
     targetDir?: string;
     /** Project root (used when scope === 'project'). Defaults to cwd. */
     projectRoot?: string;
-    /** Overwrite existing SKILL.md if present. Default false. */
+    /** Overwrite existing SKILL.md / agent / hook if present. Default false. */
     overwrite?: boolean;
 }
 export interface SkillInstallResult {
@@ -38,6 +43,13 @@ export interface SkillInstallResult {
     installed: boolean;
     /** True if an existing file was replaced. */
     overwrote: boolean;
+    /** Companion files installed alongside the skill (project scope only). */
+    companions?: {
+        agentPath: string;
+        hookScriptPath: string;
+        settingsPath: string;
+        hookRegistered: boolean;
+    };
 }
 /**
  * Resolve the directory in which the skill should live, given the user's
@@ -50,8 +62,20 @@ export declare function resolveSkillDir(options: SkillInstallOptions): string;
  */
 export declare function loadSkillTemplate(): string;
 /**
- * Install (or refuse to overwrite) the codebase-to-spec SKILL.md at the
- * resolved location.
+ * Load the bundled cts-worker agent definition template.
+ */
+export declare function loadAgentTemplate(): string;
+/**
+ * Load the bundled persona-injection hook script template.
+ */
+export declare function loadHookTemplate(): string;
+/**
+ * Install (or refuse to overwrite) the codebase-to-spec skill bundle.
+ *
+ * For `project` scope: installs skill body, cts-worker agent, persona hook
+ * script, and registers the hook in settings.local.json.
+ *
+ * For `global` and `custom` scopes: installs only the skill body.
  */
 export declare function installSkill(options?: SkillInstallOptions): SkillInstallResult;
 //# sourceMappingURL=skill-install.d.ts.map

package/dist/codebase-to-spec/skill-install.js

@@ -1,21 +1,23 @@
 /**
  * Skill installation logic for the codebase-to-spec skill.
  *
- * The skill is a thin conversational wrapper around `dotrequirements cts run`.
- * It ships as a SKILL.md template bundled in the CLI package, and this module
- * copies it into the host's skill directory (default: `.claude/skills/` for
- * Claude Code).
+ * Ships as a bundle: SKILL.md + cts-worker agent definition + persona-
+ * injection hook script + hook registration in `.claude/settings.local.json`.
+ * The skill body (the conversational orchestrator) DEPENDS on the companion
+ * files — installing just the skill without them would leave Task dispatches
+ * unable to resolve their persona. For `project` scope, all four pieces are
+ * installed in one shot. For `global` and `custom` scopes, only the skill
+ * body is installed; the companions are project-scoped by CC convention.
  *
  * Host portability (CTS-SKILL-5): the install logic supports any host that
  * follows the Agent Skills format. The default target is Claude Code's
  * convention; `--target-dir` lets users place the skill anywhere.
  *
  * Requirements covered:
- * - CTS-SKILL-1: skill artifact exists and points users at `dotrequirements cts run`
- * - CTS-SKILL-5: install logic is host-agnostic and works on any host with
- *   Agent Skills format support
+ * - CTS-SKILL-1, CTS-SKILL-5
+ * - CTSO-CLI-1 (bundles the agent + hook that PreToolUse-injects persona bodies)
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { loadTemplate } from "../utils/templates.js";
@@ -49,31 +51,130 @@ export function loadSkillTemplate() {
     return loadTemplate("skills/codebase-to-spec/SKILL.md");
 }
 /**
- * Install (or refuse to overwrite) the codebase-to-spec SKILL.md at the
- * resolved location.
+ * Load the bundled cts-worker agent definition template.
+ */
+export function loadAgentTemplate() {
+    return loadTemplate("agents/cts-worker.md");
+}
+/**
+ * Load the bundled persona-injection hook script template.
+ */
+export function loadHookTemplate() {
+    return loadTemplate("hooks/cts-worker-persona.sh");
+}
+/**
+ * Install (or refuse to overwrite) one template file at a target path.
+ * Returns true if a write happened.
+ */
+function installTemplateFile(templateContent, targetPath, overwrite, description) {
+    const exists = existsSync(targetPath);
+    if (exists && !overwrite) {
+        const onDisk = readFileSync(targetPath, "utf-8");
+        if (onDisk === templateContent) {
+            return { installed: false, overwrote: false };
+        }
+        throw new Error(`${description} already exists at ${targetPath} and differs from the bundled template. Pass --overwrite to replace it, or delete the file first.`);
+    }
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, templateContent, "utf-8");
+    return { installed: true, overwrote: exists };
+}
+/**
+ * Register the cts-worker-persona PreToolUse hook in the project's
+ * `.claude/settings.local.json`, preserving any existing keys.
+ *
+ * Returns true if the hook registration was added or updated.
+ */
+function registerHookInSettings(projectRoot, hookScriptPath) {
+    const settingsPath = join(projectRoot, ".claude", "settings.local.json");
+    const hookEntry = {
+        matcher: "Task",
+        hooks: [{ type: "command", command: hookScriptPath }],
+    };
+    // Read existing settings if present.
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        try {
+            const content = readFileSync(settingsPath, "utf-8");
+            if (content.trim()) {
+                settings = JSON.parse(content);
+            }
+        }
+        catch {
+            // Invalid JSON — refuse to clobber. Tell caller to fix manually.
+            throw new Error(`Existing ${settingsPath} contains invalid JSON. Fix it or delete it before installing the orchestrator hook.`);
+        }
+    }
+    // Initialize the hooks tree if missing.
+    // biome-ignore lint/suspicious/noExplicitAny: settings.local.json is user-owned; we narrow ad-hoc.
+    const hooks = (settings.hooks ?? {});
+    const preToolUse = (hooks.PreToolUse ?? []);
+    // Check if an entry already references our hook script (idempotent).
+    const alreadyRegistered = preToolUse.some((entry) => {
+        if (entry.matcher !== "Task")
+            return false;
+        const innerHooks = entry.hooks;
+        if (!Array.isArray(innerHooks))
+            return false;
+        return innerHooks.some((h) => h.command === hookScriptPath);
+    });
+    if (alreadyRegistered) {
+        return { settingsPath, registered: false };
+    }
+    preToolUse.push(hookEntry);
+    hooks.PreToolUse = preToolUse;
+    settings.hooks = hooks;
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf-8");
+    return { settingsPath, registered: true };
+}
+/**
+ * Install (or refuse to overwrite) the codebase-to-spec skill bundle.
+ *
+ * For `project` scope: installs skill body, cts-worker agent, persona hook
+ * script, and registers the hook in settings.local.json.
+ *
+ * For `global` and `custom` scopes: installs only the skill body.
  */
 export function installSkill(options = {}) {
     const skillDir = resolveSkillDir(options);
     const skillPath = join(skillDir, "SKILL.md");
-    const template = loadSkillTemplate();
-    const exists = existsSync(skillPath);
-    if (exists && !options.overwrite) {
-        // Idempotent no-op: if the on-disk content already matches the template,
-        // there's nothing to do and we shouldn't surface that as a conflict.
-        const onDisk = readFileSync(skillPath, "utf-8");
-        if (onDisk === template) {
-            return { installedPath: skillPath, installed: false, overwrote: false };
-        }
-        // Stale or hand-edited copy: refuse without --overwrite so we don't
-        // silently clobber user changes.
-        throw new Error(`SKILL.md already exists at ${skillPath} and differs from the bundled template. Pass --overwrite to replace it, or delete the file first.`);
+    const skillTemplate = loadSkillTemplate();
+    const skillResult = installTemplateFile(skillTemplate, skillPath, options.overwrite === true, "SKILL.md");
+    // Skill body only for global/custom scopes — CC reads agents and hooks
+    // per-project, so the companions don't make sense outside a project.
+    const scope = options.scope ?? "project";
+    if (scope !== "project") {
+        return {
+            installedPath: skillPath,
+            installed: skillResult.installed,
+            overwrote: skillResult.overwrote,
+        };
     }
-    mkdirSync(dirname(skillPath), { recursive: true });
-    writeFileSync(skillPath, template, "utf-8");
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const agentPath = join(projectRoot, ".claude", "agents", "cts-worker.md");
+    const hookScriptPath = join(projectRoot, ".claude", "hooks", "cts-worker-persona.sh");
+    // Install the cts-worker agent definition.
+    installTemplateFile(loadAgentTemplate(), agentPath, options.overwrite === true, "cts-worker agent definition");
+    // Install the persona-injection hook script (executable bit set separately).
+    installTemplateFile(loadHookTemplate(), hookScriptPath, options.overwrite === true, "cts-worker-persona hook script");
+    // chmod the hook script to be executable so Claude Code's PreToolUse
+    // hook can invoke it. (Imported statically — the CLI package is ESM, so
+    // `require("node:fs")` here would throw ReferenceError and silently
+    // leave the script at 0644, breaking the hook on every install.)
+    chmodSync(hookScriptPath, 0o755);
+    // Register the hook in settings.local.json.
+    const { settingsPath, registered } = registerHookInSettings(projectRoot, hookScriptPath);
     return {
         installedPath: skillPath,
-        installed: true,
-        overwrote: exists,
+        installed: skillResult.installed,
+        overwrote: skillResult.overwrote,
+        companions: {
+            agentPath,
+            hookScriptPath,
+            settingsPath,
+            hookRegistered: registered,
+        },
     };
 }
 //# sourceMappingURL=skill-install.js.map

package/dist/codebase-to-spec/specifier.js

@@ -24,6 +24,12 @@ function buildUserMessage(ctx) {
         `Area description: ${ctx.area.description}`,
         `Document defaultPrefix: ${ctx.outline.defaultPrefix}`,
         `Area prefix: ${ctx.area.prefix}`,
+        ``,
+        `## Customers this area serves`,
+        `(Pick one of these as the named persona for your requirements. Do not invent a different customer. If none of these is a real user of the software — e.g., all entries describe a contributor to this codebase — follow the AREA-LACKS-CUSTOMER escape in your system prompt instead of writing requirements.)`,
+        `\`\`\`json`,
+        JSON.stringify(ctx.area.customers, null, 2),
+        `\`\`\``,
         `Use full requirement IDs of the form: ${ctx.outline.defaultPrefix}-${ctx.area.prefix}-1, ${ctx.outline.defaultPrefix}-${ctx.area.prefix}-2, etc. (sequential, 1-indexed, no zero-padding).`,
         ``,
         `## Paths`,

package/dist/commands/codebase-to-spec/compose-orchestrator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `dotrequirements codebase-to-spec compose-orchestrator` subcommand.
+ *
+ * Conversational-orchestrator variant of `compose`. Reads outline.yaml
+ * (must be approved) + per-area partials, writes the composed spec to
+ * .dotrequirements-cache/spec-composed.md. Wraps the legacy `runCompose`
+ * by adapting outline.yaml to the legacy Outline shape.
+ *
+ * Requirements covered:
+ * - CTS-COMPOSE-1, CTS-COMPOSE-2 (reuses the legacy compose logic)
+ * - CTSO-INTEG-1: orchestrator uses existing deterministic stages unchanged
+ */
+export declare function composeOrchestratorCommand(): Promise<void>;
+//# sourceMappingURL=compose-orchestrator.d.ts.map

package/dist/commands/codebase-to-spec/compose-orchestrator.js

@@ -0,0 +1,54 @@
+/**
+ * `dotrequirements codebase-to-spec compose-orchestrator` subcommand.
+ *
+ * Conversational-orchestrator variant of `compose`. Reads outline.yaml
+ * (must be approved) + per-area partials, writes the composed spec to
+ * .dotrequirements-cache/spec-composed.md. Wraps the legacy `runCompose`
+ * by adapting outline.yaml to the legacy Outline shape.
+ *
+ * Requirements covered:
+ * - CTS-COMPOSE-1, CTS-COMPOSE-2 (reuses the legacy compose logic)
+ * - CTSO-INTEG-1: orchestrator uses existing deterministic stages unchanged
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { cachePaths } from "../../codebase-to-spec/cache.js";
+import { runCompose } from "../../codebase-to-spec/compose.js";
+import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
+import { conversationalOutlineToLegacy, parseConversationalOutline, } from "../../codebase-to-spec/schemas.js";
+import { findProjectRoot } from "../../utils/project-settings.js";
+export async function composeOrchestratorCommand() {
+    const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+    const paths = cachePaths(projectRoot);
+    if (!existsSync(paths.outline)) {
+        process.stderr.write(`No outline.yaml found at ${paths.outline}. Run the orchestrator's planner first.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    let outline;
+    try {
+        outline = parseConversationalOutline(readFileSync(paths.outline, "utf-8"));
+    }
+    catch (err) {
+        process.stderr.write(`Outline at ${paths.outline} is invalid: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    if (!outline.review || outline.review.result !== "approved") {
+        process.stderr.write(`Outline at ${paths.outline} is not approved (review.result is "${outline.review?.result ?? "absent"}"). Approve the outline before composing.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    const legacyOutline = conversationalOutlineToLegacy(outline);
+    const result = runCompose({
+        outline: legacyOutline,
+        partialPathFor: (sanitized) => paths.partial(sanitized),
+        composedPath: paths.composedSpec,
+    });
+    process.stdout.write(`Composed spec → ${result.composedPath} (${result.partialsIncluded} partials included, ${result.partialsMissing} missing)\n`);
+    if (result.validationError) {
+        process.stderr.write(`Composed spec failed validation:\n${result.validationError}\n`);
+        process.exitCode = ExitCode.StageFailed;
+        return;
+    }
+}
+//# sourceMappingURL=compose-orchestrator.js.map

package/dist/commands/codebase-to-spec/dispatch-context.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `dotrequirements codebase-to-spec dispatch-context <dispatch-id>` subcommand.
+ *
+ * Returns the composed prompt for a worker dispatch as a JSON object on stdout.
+ * Called by the cts-worker PreToolUse hook to compose the subagent's first-turn
+ * prompt via `modifiedInput`.
+ *
+ * Requirements covered:
+ * - CTSO-CLI-1: CLI exposes commands that return dispatch instructions
+ */
+export declare function dispatchContextCommand(dispatchId: string): Promise<void>;
+//# sourceMappingURL=dispatch-context.d.ts.map

package/dist/commands/codebase-to-spec/dispatch-context.js

@@ -0,0 +1,22 @@
+/**
+ * `dotrequirements codebase-to-spec dispatch-context <dispatch-id>` subcommand.
+ *
+ * Returns the composed prompt for a worker dispatch as a JSON object on stdout.
+ * Called by the cts-worker PreToolUse hook to compose the subagent's first-turn
+ * prompt via `modifiedInput`.
+ *
+ * Requirements covered:
+ * - CTSO-CLI-1: CLI exposes commands that return dispatch instructions
+ */
+import { composeDispatchContext } from "../../codebase-to-spec/dispatch.js";
+import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
+export async function dispatchContextCommand(dispatchId) {
+    const ctx = composeDispatchContext(dispatchId);
+    if (!ctx) {
+        process.stderr.write(`Unknown dispatch-id: ${dispatchId}\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    process.stdout.write(`${JSON.stringify(ctx)}\n`);
+}
+//# sourceMappingURL=dispatch-context.js.map

package/dist/commands/codebase-to-spec/dispatch-editor.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `dotrequirements codebase-to-spec dispatch-editor <area-prefix>` subcommand.
+ *
+ * Returns a dispatch payload for an editor pass on a specific area's partial.
+ * Validates that the area's `review.result` is `"needs-revision"` and that
+ * the partial file exists before scaffolding the dispatch.
+ *
+ * The worker overwrites the existing partial via Edit; the area.review.thread
+ * in outline.yaml stays where it is (the orchestrator manages it).
+ *
+ * Requirements covered:
+ * - CTSO-CLI-1: CLI exposes commands that return dispatch instructions
+ * - CTSO-CONV-3: orchestrator dispatches an editor when revisions are needed
+ */
+export declare function dispatchEditorCommand(areaPrefix: string): Promise<void>;
+//# sourceMappingURL=dispatch-editor.d.ts.map

package/dist/commands/codebase-to-spec/dispatch-editor.js

@@ -0,0 +1,71 @@
+/**
+ * `dotrequirements codebase-to-spec dispatch-editor <area-prefix>` subcommand.
+ *
+ * Returns a dispatch payload for an editor pass on a specific area's partial.
+ * Validates that the area's `review.result` is `"needs-revision"` and that
+ * the partial file exists before scaffolding the dispatch.
+ *
+ * The worker overwrites the existing partial via Edit; the area.review.thread
+ * in outline.yaml stays where it is (the orchestrator manages it).
+ *
+ * Requirements covered:
+ * - CTSO-CLI-1: CLI exposes commands that return dispatch instructions
+ * - CTSO-CONV-3: orchestrator dispatches an editor when revisions are needed
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { cachePaths } from "../../codebase-to-spec/cache.js";
+import { EDITOR_DISPATCH_ID_PREFIX } from "../../codebase-to-spec/dispatch.js";
+import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
+import { sanitizeAreaName } from "../../codebase-to-spec/fan-out.js";
+import { parseConversationalOutline, } from "../../codebase-to-spec/schemas.js";
+import { findProjectRoot } from "../../utils/project-settings.js";
+export async function dispatchEditorCommand(areaPrefix) {
+    const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+    const paths = cachePaths(projectRoot);
+    if (!existsSync(paths.outline)) {
+        process.stderr.write(`No outline.yaml found at ${paths.outline}. Dispatch the planner first.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    let outline;
+    try {
+        outline = parseConversationalOutline(readFileSync(paths.outline, "utf-8"));
+    }
+    catch (err) {
+        process.stderr.write(`Outline at ${paths.outline} is invalid: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    const area = outline.areas.find((a) => a.prefix === areaPrefix);
+    if (!area) {
+        process.stderr.write(`No area with prefix "${areaPrefix}" in outline.yaml. Available prefixes: ${outline.areas
+            .map((a) => a.prefix)
+            .join(", ")}\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    if (!area.review) {
+        process.stderr.write(`Area "${areaPrefix}" has no review yet. Write a per-area review with result=needs-revision before dispatching the editor.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    if (area.review.result === "approved") {
+        process.stderr.write(`Area "${areaPrefix}" has review.result "approved" — nothing to revise. The partial is good as-is.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    const partialPath = paths.partial(sanitizeAreaName(area.name));
+    if (!existsSync(partialPath)) {
+        process.stderr.write(`Partial not found at ${partialPath}. Run the specifier for area "${areaPrefix}" before dispatching the editor.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    const payload = {
+        dispatch_id: `${EDITOR_DISPATCH_ID_PREFIX}${areaPrefix}`,
+        output_path: partialPath,
+        area_name: area.name,
+        area_prefix: area.prefix,
+    };
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+//# sourceMappingURL=dispatch-editor.js.map