@popoverai/dotrequirements 0.24.2 → 0.24.3

package/dist/codebase-to-spec/schemas.d.ts

@@ -337,5 +337,380 @@ export declare const SPEC_REVIEW_JSON_SCHEMA: {
     readonly required: readonly ["coverage_gaps", "framing_errors", "cross_area_issues", "internal_mechanics_drift", "revisions", "verdict"];
     readonly additionalProperties: false;
 };
+export declare const ConversationalCustomerSchema: z.ZodObject<{
+    description: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+}, {
+    description: string;
+}>;
+export type ConversationalCustomer = z.infer<typeof ConversationalCustomerSchema>;
+/**
+ * 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 declare const ConversationalReviewEntrySchema: z.ZodDiscriminatedUnion<"result", [z.ZodObject<{
+    result: z.ZodLiteral<"approved">;
+}, "strip", z.ZodTypeAny, {
+    result: "approved";
+}, {
+    result: "approved";
+}>, z.ZodObject<{
+    result: z.ZodLiteral<"needs-revision">;
+    revisions: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    revisions: string[];
+    result: "needs-revision";
+}, {
+    revisions: string[];
+    result: "needs-revision";
+}>]>;
+export type ConversationalReviewEntry = z.infer<typeof ConversationalReviewEntrySchema>;
+/**
+ * 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 declare const ConversationalReviewSchema: z.ZodObject<{
+    result: z.ZodEnum<["approved", "needs-revision"]>;
+    thread: z.ZodArray<z.ZodDiscriminatedUnion<"result", [z.ZodObject<{
+        result: z.ZodLiteral<"approved">;
+    }, "strip", z.ZodTypeAny, {
+        result: "approved";
+    }, {
+        result: "approved";
+    }>, z.ZodObject<{
+        result: z.ZodLiteral<"needs-revision">;
+        revisions: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        revisions: string[];
+        result: "needs-revision";
+    }, {
+        revisions: string[];
+        result: "needs-revision";
+    }>]>, "many">;
+}, "strip", z.ZodTypeAny, {
+    result: "approved" | "needs-revision";
+    thread: ({
+        result: "approved";
+    } | {
+        revisions: string[];
+        result: "needs-revision";
+    })[];
+}, {
+    result: "approved" | "needs-revision";
+    thread: ({
+        result: "approved";
+    } | {
+        revisions: string[];
+        result: "needs-revision";
+    })[];
+}>;
+export type ConversationalReview = z.infer<typeof ConversationalReviewSchema>;
+export declare const ConversationalAreaSchema: z.ZodObject<{
+    name: z.ZodString;
+    prefix: z.ZodString;
+    description: z.ZodString;
+    source_files: z.ZodArray<z.ZodString, "many">;
+    customers: z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+    }, {
+        description: string;
+    }>, "many">;
+    /**
+     * 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: z.ZodOptional<z.ZodObject<{
+        result: z.ZodEnum<["approved", "needs-revision"]>;
+        thread: z.ZodArray<z.ZodDiscriminatedUnion<"result", [z.ZodObject<{
+            result: z.ZodLiteral<"approved">;
+        }, "strip", z.ZodTypeAny, {
+            result: "approved";
+        }, {
+            result: "approved";
+        }>, z.ZodObject<{
+            result: z.ZodLiteral<"needs-revision">;
+            revisions: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            revisions: string[];
+            result: "needs-revision";
+        }, {
+            revisions: string[];
+            result: "needs-revision";
+        }>]>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        result: "approved" | "needs-revision";
+        thread: ({
+            result: "approved";
+        } | {
+            revisions: string[];
+            result: "needs-revision";
+        })[];
+    }, {
+        result: "approved" | "needs-revision";
+        thread: ({
+            result: "approved";
+        } | {
+            revisions: string[];
+            result: "needs-revision";
+        })[];
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    prefix: string;
+    name: string;
+    description: string;
+    customers: {
+        description: string;
+    }[];
+    source_files: string[];
+    review?: {
+        result: "approved" | "needs-revision";
+        thread: ({
+            result: "approved";
+        } | {
+            revisions: string[];
+            result: "needs-revision";
+        })[];
+    } | undefined;
+}, {
+    prefix: string;
+    name: string;
+    description: string;
+    customers: {
+        description: string;
+    }[];
+    source_files: string[];
+    review?: {
+        result: "approved" | "needs-revision";
+        thread: ({
+            result: "approved";
+        } | {
+            revisions: string[];
+            result: "needs-revision";
+        })[];
+    } | undefined;
+}>;
+export type ConversationalArea = z.infer<typeof ConversationalAreaSchema>;
+export declare const ConversationalOutlineSchema: z.ZodObject<{
+    title: z.ZodString;
+    defaultPrefix: z.ZodString;
+    summary: z.ZodString;
+    review: z.ZodOptional<z.ZodObject<{
+        result: z.ZodEnum<["approved", "needs-revision"]>;
+        thread: z.ZodArray<z.ZodDiscriminatedUnion<"result", [z.ZodObject<{
+            result: z.ZodLiteral<"approved">;
+        }, "strip", z.ZodTypeAny, {
+            result: "approved";
+        }, {
+            result: "approved";
+        }>, z.ZodObject<{
+            result: z.ZodLiteral<"needs-revision">;
+            revisions: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            revisions: string[];
+            result: "needs-revision";
+        }, {
+            revisions: string[];
+            result: "needs-revision";
+        }>]>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        result: "approved" | "needs-revision";
+        thread: ({
+            result: "approved";
+        } | {
+            revisions: string[];
+            result: "needs-revision";
+        })[];
+    }, {
+        result: "approved" | "needs-revision";
+        thread: ({
+            result: "approved";
+        } | {
+            revisions: string[];
+            result: "needs-revision";
+        })[];
+    }>>;
+    areas: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        prefix: z.ZodString;
+        description: z.ZodString;
+        source_files: z.ZodArray<z.ZodString, "many">;
+        customers: z.ZodArray<z.ZodObject<{
+            description: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            description: string;
+        }, {
+            description: string;
+        }>, "many">;
+        /**
+         * 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: z.ZodOptional<z.ZodObject<{
+            result: z.ZodEnum<["approved", "needs-revision"]>;
+            thread: z.ZodArray<z.ZodDiscriminatedUnion<"result", [z.ZodObject<{
+                result: z.ZodLiteral<"approved">;
+            }, "strip", z.ZodTypeAny, {
+                result: "approved";
+            }, {
+                result: "approved";
+            }>, z.ZodObject<{
+                result: z.ZodLiteral<"needs-revision">;
+                revisions: z.ZodArray<z.ZodString, "many">;
+            }, "strip", z.ZodTypeAny, {
+                revisions: string[];
+                result: "needs-revision";
+            }, {
+                revisions: string[];
+                result: "needs-revision";
+            }>]>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            result: "approved" | "needs-revision";
+            thread: ({
+                result: "approved";
+            } | {
+                revisions: string[];
+                result: "needs-revision";
+            })[];
+        }, {
+            result: "approved" | "needs-revision";
+            thread: ({
+                result: "approved";
+            } | {
+                revisions: string[];
+                result: "needs-revision";
+            })[];
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        prefix: string;
+        name: string;
+        description: string;
+        customers: {
+            description: string;
+        }[];
+        source_files: string[];
+        review?: {
+            result: "approved" | "needs-revision";
+            thread: ({
+                result: "approved";
+            } | {
+                revisions: string[];
+                result: "needs-revision";
+            })[];
+        } | undefined;
+    }, {
+        prefix: string;
+        name: string;
+        description: string;
+        customers: {
+            description: string;
+        }[];
+        source_files: string[];
+        review?: {
+            result: "approved" | "needs-revision";
+            thread: ({
+                result: "approved";
+            } | {
+                revisions: string[];
+                result: "needs-revision";
+            })[];
+        } | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    defaultPrefix: string;
+    summary: string;
+    areas: {
+        prefix: string;
+        name: string;
+        description: string;
+        customers: {
+            description: string;
+        }[];
+        source_files: string[];
+        review?: {
+            result: "approved" | "needs-revision";
+            thread: ({
+                result: "approved";
+            } | {
+                revisions: string[];
+                result: "needs-revision";
+            })[];
+        } | undefined;
+    }[];
+    review?: {
+        result: "approved" | "needs-revision";
+        thread: ({
+            result: "approved";
+        } | {
+            revisions: string[];
+            result: "needs-revision";
+        })[];
+    } | undefined;
+}, {
+    title: string;
+    defaultPrefix: string;
+    summary: string;
+    areas: {
+        prefix: string;
+        name: string;
+        description: string;
+        customers: {
+            description: string;
+        }[];
+        source_files: string[];
+        review?: {
+            result: "approved" | "needs-revision";
+            thread: ({
+                result: "approved";
+            } | {
+                revisions: string[];
+                result: "needs-revision";
+            })[];
+        } | undefined;
+    }[];
+    review?: {
+        result: "approved" | "needs-revision";
+        thread: ({
+            result: "approved";
+        } | {
+            revisions: string[];
+            result: "needs-revision";
+        })[];
+    } | undefined;
+}>;
+export type ConversationalOutline = z.infer<typeof ConversationalOutlineSchema>;
+/**
+ * Parse YAML text against the conversational outline schema. Throws with
+ * a descriptive message on parse or validation failure.
+ */
+export declare function parseConversationalOutline(text: string): ConversationalOutline;
+/**
+ * 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 declare function conversationalOutlineToLegacy(outline: ConversationalOutline): Outline;
+/**
+ * Serialize a conversational outline back to YAML text. Uses literal-block
+ * multi-line strings (`|`) where possible for readability.
+ */
+export declare function stringifyConversationalOutline(outline: ConversationalOutline): string;
 export declare function parseSpecReview(text: string): SpecReview;
 //# sourceMappingURL=schemas.d.ts.map

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

@@ -189,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