@cat-factory/contracts 0.6.0

package/dist/requests.js

@@ -0,0 +1,231 @@
+import * as v from 'valibot';
+import { agentConfigValuesSchema } from './agent-config.js';
+import { consensusStepConfigSchema, stepGatingSchema } from './consensus.js';
+import { cloudProviderSchema, instanceSizeSchema } from './provisioning.js';
+import { agentKindSchema, blockTypeSchema, createTaskTypeSchema, positionSchema, sizeSchema, taskTypeFieldsSchema, } from './primitives.js';
+// Request body schemas. The Hono facade validates inbound JSON against these via
+// @hono/valibot-validator; the frontend API client can import the inferred input
+// types to stay in lockstep with what the backend accepts.
+export const createWorkspaceSchema = v.object({
+    name: v.optional(v.pipe(v.string(), v.trim(), v.maxLength(120))),
+    /** Optional free-text description shown on the board switcher / onboarding list. */
+    description: v.optional(v.pipe(v.string(), v.trim(), v.maxLength(500))),
+    /**
+     * Seed the board with the sample architecture *blocks* (default true; the SPA
+     * passes false so real boards start empty). The pipeline catalog is always
+     * provisioned regardless — it is product config, not sample data.
+     */
+    seed: v.optional(v.boolean()),
+    /**
+     * The account the new board belongs to. Optional: when omitted (or in the
+     * auth-disabled path) the board is created in the caller's personal account, or
+     * unscoped when there is no signed-in user.
+     */
+    accountId: v.optional(v.pipe(v.string(), v.minLength(1))),
+});
+/** Rename a board and/or update its description. */
+export const renameWorkspaceSchema = v.object({
+    name: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(120))),
+    /** `null` clears the description; an absent key leaves it unchanged. */
+    description: v.optional(v.nullable(v.pipe(v.string(), v.trim(), v.maxLength(500)))),
+});
+export const addFrameSchema = v.object({
+    type: blockTypeSchema,
+    position: positionSchema,
+});
+/**
+ * Add a service frame backed by an EXISTING GitHub repo the App can access.
+ * Unlike bootstrap there is no container / agent run: the backend links + syncs
+ * the repo into the workspace (if it wasn't already tracked), creates the frame
+ * `ready`, and links the repo projection to it. `position` is optional — the
+ * backend lays the frame out when omitted (the side-panel button passes none).
+ */
+export const addServiceFromRepoSchema = v.object({
+    repoGithubId: v.number(),
+    position: v.optional(positionSchema),
+    /**
+     * For a monorepo repo, the subdirectory (relative to the repo root) this service
+     * lives in, e.g. `packages/api`. Omitted/empty for a whole-repo service. The
+     * frame is titled after the directory's base name when given.
+     */
+    directory: v.optional(v.string()),
+    /**
+     * Whether the backing repo is a monorepo (hosts several services). Sent as part of
+     * the add request instead of a separate up-front PATCH; when provided the backend
+     * persists the repo's monorepo flag, then requires a {@link directory}. A monorepo
+     * repo can back several service frames, each pinned to its own subdirectory.
+     */
+    isMonorepo: v.optional(v.boolean()),
+});
+export const addTaskSchema = v.object({
+    // The user always names the task — no auto-generated placeholder titles.
+    title: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(200)),
+    description: v.optional(v.pipe(v.string(), v.trim(), v.maxLength(2000))),
+    // The kind of work this task represents; omitted → 'feature'. `recurring` is NOT
+    // allowed here (recurring tasks are created via a recurring-pipeline schedule).
+    taskType: v.optional(createTaskTypeSchema),
+    // Small per-type fields collected on the form (e.g. a bug's severity / repro).
+    taskTypeFields: v.optional(taskTypeFieldsSchema),
+    // The merge threshold preset governing this task's auto-merge; omitted/empty →
+    // the workspace default preset.
+    mergePresetId: v.optional(v.pipe(v.string(), v.maxLength(120))),
+    // The pipeline the task's Run controls default to; omitted/empty → none recorded.
+    pipelineId: v.optional(v.pipe(v.string(), v.maxLength(120))),
+    // Task-level agent-contributed config values (e.g. the Tester's environment).
+    agentConfig: v.optional(agentConfigValuesSchema),
+});
+export const addModuleSchema = v.object({
+    name: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(120)),
+    position: v.optional(positionSchema),
+});
+export const updateBlockSchema = v.partial(v.object({
+    title: v.pipe(v.string(), v.trim(), v.maxLength(200)),
+    description: v.pipe(v.string(), v.maxLength(2000)),
+    position: positionSchema,
+    // The dragged frame size (service frames are resizable by their borders).
+    size: sizeSchema,
+    moduleName: v.pipe(v.string(), v.trim(), v.maxLength(120)),
+    fragmentIds: v.array(v.pipe(v.string(), v.maxLength(120))),
+    // Service-level (frame): the service's selected best-practice fragment ids (folded
+    // into code-aware agents on its tasks); an empty array clears the selection.
+    serviceFragmentIds: v.array(v.pipe(v.string(), v.maxLength(120))),
+    // The selected model's catalog id; an empty string resets to the default.
+    modelId: v.pipe(v.string(), v.maxLength(120)),
+    // The merge threshold preset id; an empty string resets to the workspace default.
+    mergePresetId: v.pipe(v.string(), v.maxLength(120)),
+    // The task's default pipeline id; an empty string clears the selection.
+    pipelineId: v.pipe(v.string(), v.maxLength(120)),
+    // Task-level agent-contributed config values (id→value map; replaces the map).
+    agentConfig: agentConfigValuesSchema,
+    // Service-level (frame): docker-compose path for the Tester's local infra; an
+    // empty string clears it.
+    testComposePath: v.pipe(v.string(), v.maxLength(400)),
+    // Service-level (frame): the service has no infra dependencies to stand up.
+    noInfraDependencies: v.boolean(),
+    // Service-level (frame): the cloud provider this service's jobs run on.
+    cloudProvider: cloudProviderSchema,
+    // Service-level (frame): the abstract instance size for this service's jobs.
+    instanceSize: instanceSizeSchema,
+}));
+export const moveBlockSchema = v.object({ position: positionSchema });
+export const reparentSchema = v.object({
+    parentId: v.pipe(v.string(), v.minLength(1)),
+    position: positionSchema,
+});
+export const toggleDependencySchema = v.object({
+    sourceId: v.pipe(v.string(), v.minLength(1)),
+});
+export const createPipelineSchema = v.object({
+    name: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(120)),
+    agentKinds: v.pipe(v.array(agentKindSchema), v.minLength(1)),
+    /**
+     * Per-step human approval gates, parallel to {@link agentKinds}. Optional;
+     * omitted means no gates (the pipeline runs straight through).
+     */
+    gates: v.optional(v.array(v.boolean())),
+    /**
+     * Per-step companion quality thresholds (0..1), parallel to {@link agentKinds}.
+     * Only meaningful on companion steps; `null`/omitted means "use the companion's
+     * default threshold". Optional.
+     */
+    thresholds: v.optional(v.array(v.nullable(v.pipe(v.number(), v.minValue(0), v.maxValue(1))))),
+    /**
+     * Per-step enable flags, parallel to {@link agentKinds}. `false` keeps the step in
+     * the pipeline but skips it at run start. Optional; omitted means every step runs.
+     */
+    enabled: v.optional(v.array(v.boolean())),
+    /**
+     * Per-step consensus configs, parallel to {@link agentKinds}: a step whose kind carries
+     * a consensus capability trait may run through the multi-model consensus mechanism.
+     * `null`/omitted ⇒ the standard single-actor agent. Optional.
+     */
+    consensus: v.optional(v.array(v.nullable(consensusStepConfigSchema))),
+    /**
+     * Per-step estimate gating, parallel to {@link agentKinds}: an enabled entry makes the
+     * step run only when the task estimate meets the threshold. `null`/omitted ⇒ always run.
+     * A pipeline with any enabled gating requires a `task-estimator` step earlier in the
+     * chain or it is rejected. Optional.
+     */
+    gating: v.optional(v.array(v.nullable(stepGatingSchema))),
+    /** Free-form organizational labels for the library. Optional. */
+    labels: v.optional(v.array(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(40)))),
+});
+/**
+ * Edit an existing (non-built-in) pipeline. Every field is optional — only the
+ * supplied fields change; `agentKinds` (when present) replaces the whole chain and
+ * re-aligns the parallel arrays. Built-in pipelines reject this (clone them first).
+ */
+export const updatePipelineSchema = v.object({
+    name: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(120))),
+    agentKinds: v.optional(v.pipe(v.array(agentKindSchema), v.minLength(1))),
+    gates: v.optional(v.array(v.boolean())),
+    thresholds: v.optional(v.array(v.nullable(v.pipe(v.number(), v.minValue(0), v.maxValue(1))))),
+    enabled: v.optional(v.array(v.boolean())),
+    consensus: v.optional(v.array(v.nullable(consensusStepConfigSchema))),
+    gating: v.optional(v.array(v.nullable(stepGatingSchema))),
+    labels: v.optional(v.array(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(40)))),
+});
+/** Clone any pipeline (built-in or custom) into a new, editable copy. */
+export const clonePipelineSchema = v.object({
+    /** Name for the copy. Optional; defaults to "<source name> (copy)". */
+    name: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(120))),
+});
+/**
+ * Organize a pipeline in the library: set labels and/or archive state. The ONLY
+ * mutation allowed on a built-in pipeline (it touches view/organization metadata,
+ * not structure), so built-ins can be tagged/archived while staying read-only for
+ * their steps. Every field optional — only the supplied fields change.
+ */
+export const organizePipelineSchema = v.object({
+    labels: v.optional(v.array(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(40)))),
+    archived: v.optional(v.boolean()),
+});
+export const startExecutionSchema = v.object({
+    pipelineId: v.pipe(v.string(), v.minLength(1)),
+});
+// NOTE: the personal password that unlocks a run's individual-usage credential
+// (Claude / GLM / Codex) is NOT a body field on any of the run endpoints below
+// (start / retry / resolve-decision / approve / request-changes). It is an ambient
+// credential carried on the `X-Personal-Password` header (see
+// `PERSONAL_PASSWORD_HEADER` in personal-subscriptions.ts), so it stays out of the
+// wire-contract payloads and the client can attach it uniformly on the gated calls.
+export const resolveDecisionSchema = v.object({
+    choice: v.pipe(v.string(), v.minLength(1)),
+});
+/**
+ * Approve a step's gated proposal. An optional edited `proposal` overrides the
+ * agent's text, so the human's revision is what flows to downstream steps.
+ */
+export const approveStepSchema = v.object({
+    proposal: v.optional(v.pipe(v.string(), v.maxLength(50000))),
+});
+/** One GitHub-review-style comment on a block of the proposal (request body). */
+const reviewCommentInputSchema = v.object({
+    quotedSource: v.pipe(v.string(), v.maxLength(20000)),
+    srcStart: v.number(),
+    srcEnd: v.number(),
+    body: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(5000)),
+});
+/**
+ * Request changes on a gated proposal: the step re-runs with the reviewer's
+ * freeform `feedback` and/or per-block `comments`. At least one of the two must
+ * be present — an empty review changes nothing.
+ */
+export const requestStepChangesSchema = v.pipe(v.object({
+    feedback: v.optional(v.pipe(v.string(), v.trim(), v.maxLength(10000))),
+    comments: v.optional(v.array(reviewCommentInputSchema)),
+}), v.check((input) => Boolean(input.feedback?.length) || Boolean(input.comments?.length), 'Provide freeform feedback or at least one comment'));
+/** Reject a gated proposal: the run stops entirely (a terminal failure). */
+export const rejectStepSchema = v.object({
+    reason: v.optional(v.pipe(v.string(), v.trim(), v.maxLength(2000))),
+});
+/**
+ * Restart a run from a chosen step: re-run from `fromStepIndex` onward, keeping the
+ * earlier steps (and their outputs) as handoff context and resetting that step plus
+ * every later one's iteration counters. The service validates the index against the
+ * run's real step count; this only enforces a non-negative integer up front.
+ */
+export const restartFromStepSchema = v.object({
+    fromStepIndex: v.pipe(v.number(), v.integer(), v.minValue(0)),
+});
+//# sourceMappingURL=requests.js.map

package/dist/requests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requests.js","sourceRoot":"","sources":["../src/requests.ts"],"names":[],"mappings":"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"}

package/dist/requirements.d.ts

@@ -0,0 +1,127 @@
+import * as v from 'valibot';
+/** What kind of concern a review item raises. */
+export declare const reviewItemCategorySchema: v.PicklistSchema<["gap", "clarification", "assumption", "risk", "question"], undefined>;
+export type ReviewItemCategory = v.InferOutput<typeof reviewItemCategorySchema>;
+/** How important resolving the item is before implementation should proceed. */
+export declare const reviewItemSeveritySchema: v.PicklistSchema<["low", "medium", "high"], undefined>;
+export type ReviewItemSeverity = v.InferOutput<typeof reviewItemSeveritySchema>;
+/**
+ * Lifecycle of a single item: `open` until a human engages, `answered` once a
+ * reply is recorded, `resolved` when accepted as done, `dismissed` when waved
+ * off as not applicable. Both `resolved` and `dismissed` count as "settled" for
+ * the purpose of gating incorporation.
+ */
+export declare const reviewItemStatusSchema: v.PicklistSchema<["open", "answered", "resolved", "dismissed"], undefined>;
+export type ReviewItemStatus = v.InferOutput<typeof reviewItemStatusSchema>;
+/** A single question / challenge the reviewer raised about the requirements. */
+export declare const requirementReviewItemSchema: v.ObjectSchema<{
+    readonly id: v.StringSchema<undefined>;
+    readonly category: v.PicklistSchema<["gap", "clarification", "assumption", "risk", "question"], undefined>;
+    readonly severity: v.PicklistSchema<["low", "medium", "high"], undefined>;
+    /** Short headline of the concern. */
+    readonly title: v.StringSchema<undefined>;
+    /** The full question / gap / challenge, in plain prose. */
+    readonly detail: v.StringSchema<undefined>;
+    readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed"], undefined>;
+    /** The human's answer, or null while unanswered. */
+    readonly reply: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly createdAt: v.NumberSchema<undefined>;
+    readonly updatedAt: v.NumberSchema<undefined>;
+}, undefined>;
+export type RequirementReviewItem = v.InferOutput<typeof requirementReviewItemSchema>;
+/**
+ * Lifecycle of the review as a whole:
+ * - `ready`: the reviewer raised findings that are awaiting human answers/dismissals.
+ * - `incorporating`: transient. The human answered the findings and asked to incorporate;
+ *   the durable driver is folding the answers into a document (the FIRST async stage). No
+ *   human action is needed — the user is back on the board.
+ * - `reviewing`: transient. The document is folded and the reviewer is RE-reviewing it (the
+ *   SECOND async stage). Distinguished from `incorporating` so the board/window can show
+ *   which stage is running; the user is summoned again only if it yields `ready`/`exceeded`.
+ * - `merged`: the companion produced an incorporated document (an internal transient on the
+ *   async path — the driver re-reviews it immediately; only the off-path inline incorporate
+ *   leaves a review here momentarily).
+ * - `exceeded`: the iteration cap was reached with findings still open — awaiting the
+ *   human's choice (one more round / proceed anyway / reset the task).
+ * - `incorporated`: terminal. The requirements phase is settled; downstream agents
+ *   consume {@link incorporatedRequirements} when present (else the original description).
+ */
+export declare const requirementReviewStatusSchema: v.PicklistSchema<["ready", "incorporating", "reviewing", "merged", "exceeded", "incorporated"], undefined>;
+export type RequirementReviewStatus = v.InferOutput<typeof requirementReviewStatusSchema>;
+/** A completed requirements review for one board block. */
+export declare const requirementReviewSchema: v.ObjectSchema<{
+    readonly id: v.StringSchema<undefined>;
+    readonly blockId: v.StringSchema<undefined>;
+    readonly status: v.PicklistSchema<["ready", "incorporating", "reviewing", "merged", "exceeded", "incorporated"], undefined>;
+    readonly items: v.ArraySchema<v.ObjectSchema<{
+        readonly id: v.StringSchema<undefined>;
+        readonly category: v.PicklistSchema<["gap", "clarification", "assumption", "risk", "question"], undefined>;
+        readonly severity: v.PicklistSchema<["low", "medium", "high"], undefined>;
+        /** Short headline of the concern. */
+        readonly title: v.StringSchema<undefined>;
+        /** The full question / gap / challenge, in plain prose. */
+        readonly detail: v.StringSchema<undefined>;
+        readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed"], undefined>;
+        /** The human's answer, or null while unanswered. */
+        readonly reply: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly createdAt: v.NumberSchema<undefined>;
+        readonly updatedAt: v.NumberSchema<undefined>;
+    }, undefined>, undefined>;
+    /** `provider:model` that produced the review, for transparency; null in tests. */
+    readonly model: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * The revised requirements text the incorporation companion last folded the answers
+     * into. Set once a doc has been produced (status `merged`/`incorporated`); null while
+     * still awaiting answers on the first pass. Consumed by every downstream agent step +
+     * the spec-writer once the phase is settled.
+     */
+    readonly incorporatedRequirements: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * How many reviewer passes have run so far (the initial review is iteration 1; each
+     * re-review adds one). Compared against {@link maxIterations} to decide when the loop
+     * has exhausted its budget.
+     */
+    readonly iteration: v.OptionalSchema<v.NumberSchema<undefined>, 1>;
+    /**
+     * The reviewer-pass budget for this review, snapshotted from the task's merge preset
+     * (`maxRequirementIterations`) when the review started. An "extra round" choice bumps
+     * it by one.
+     */
+    readonly maxIterations: v.OptionalSchema<v.NumberSchema<undefined>, 1>;
+    readonly createdAt: v.NumberSchema<undefined>;
+    readonly updatedAt: v.NumberSchema<undefined>;
+}, undefined>;
+export type RequirementReview = v.InferOutput<typeof requirementReviewSchema>;
+/** Record a human's answer to a single review item. */
+export declare const replyReviewItemSchema: v.ObjectSchema<{
+    readonly reply: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 4000, undefined>]>;
+}, undefined>;
+export type ReplyReviewItemInput = v.InferOutput<typeof replyReviewItemSchema>;
+/** Set a review item's status (resolve / dismiss / reopen). */
+export declare const updateReviewItemStatusSchema: v.ObjectSchema<{
+    readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed"], undefined>;
+}, undefined>;
+export type UpdateReviewItemStatusInput = v.InferOutput<typeof updateReviewItemStatusSchema>;
+/**
+ * Incorporate the settled answers into a standardized requirements document. An optional
+ * `feedback` comment is the human's "do it differently" lever when redoing a merge they
+ * were unhappy with — it is folded into the rework prompt alongside the prior document.
+ */
+export declare const incorporateRequirementsSchema: v.ObjectSchema<{
+    readonly feedback: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 4000, undefined>]>, undefined>;
+}, undefined>;
+export type IncorporateRequirementsInput = v.InferOutput<typeof incorporateRequirementsSchema>;
+/**
+ * How a human resolves a requirements review that hit its iteration cap with findings
+ * still open: `extra-round` grants one more reviewer pass, `proceed` advances the
+ * pipeline using the last incorporated document, `stop-reset` cancels the run and
+ * returns the task to phase zero (editable) while keeping the last incorporated doc.
+ * Shares the {@link iterationCapChoiceSchema} with the companion gate — same three
+ * choices, one source of truth (see `./iteration-cap.ts`).
+ */
+export declare const resolveRequirementsExceededSchema: v.ObjectSchema<{
+    readonly choice: v.PicklistSchema<["extra-round", "proceed", "stop-reset"], undefined>;
+}, undefined>;
+export type ResolveRequirementsExceededInput = v.InferOutput<typeof resolveRequirementsExceededSchema>;
+export type ResolveRequirementsExceededChoice = ResolveRequirementsExceededInput['choice'];
+//# sourceMappingURL=requirements.d.ts.map

package/dist/requirements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirements.d.ts","sourceRoot":"","sources":["../src/requirements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAoB5B,iDAAiD;AACjD,eAAO,MAAM,wBAAwB,yFAMnC,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,wDAAwC,CAAA;AAC7E,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,4EAA4D,CAAA;AAC/F,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E,gFAAgF;AAChF,eAAO,MAAM,2BAA2B;;;;IAItC,qCAAqC;;IAErC,2DAA2D;;;IAG3D,oDAAoD;;;;aAIpD,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAErF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,6BAA6B,4GAOxC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAA;AAEzF,2DAA2D;AAC3D,eAAO,MAAM,uBAAuB;;;;;;;;QAxClC,qCAAqC;;QAErC,2DAA2D;;;QAG3D,oDAAoD;;;;;IAwCpD,kFAAkF;;IAElF;;;;;OAKG;;IAEH;;;;OAIG;;IAEH;;;;OAIG;;;;aAIH,CAAA;AACF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAI7E,uDAAuD;AACvD,eAAO,MAAM,qBAAqB;;aAEhC,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAE9E,+DAA+D;AAC/D,eAAO,MAAM,4BAA4B;;aAEvC,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAE5F;;;;GAIG;AACH,eAAO,MAAM,6BAA6B;;aAExC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAA;AAE9F;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC;;aAE5C,CAAA;AACF,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,WAAW,CAC1D,OAAO,iCAAiC,CACzC,CAAA;AACD,MAAM,MAAM,iCAAiC,GAAG,gCAAgC,CAAC,QAAQ,CAAC,CAAA"}

package/dist/requirements.js

@@ -0,0 +1,137 @@
+import * as v from 'valibot';
+import { iterationCapChoiceSchema } from './iteration-cap.js';
+// ---------------------------------------------------------------------------
+// Requirements-review wire contracts. A reviewer agent inspects a board block's
+// "collected requirements" — its description plus any linked PRD / RFC /
+// requirements documents and tracker issues — and raises a list of review items:
+// gaps, ambiguities, unstated assumptions, risks and open questions, each with a
+// severity. A human answers or dismisses each item; an incorporation companion
+// folds the answers into one standardized requirements document, then the reviewer
+// re-reviews that document. The cycle repeats until the reviewer is clean (or every
+// remaining finding is dismissed / tolerated by the task's severity threshold), or
+// the task's iteration cap is hit and a human picks how to proceed.
+//
+// On the pipeline path the run parks on the requirements step while the human drives
+// these round-trips; the run only advances (converge / proceed) or resets exactly
+// once. The review + its items are persisted and mutated in plain request/response
+// round-trips. Storage-only bookkeeping (the owning workspace) is NOT on the wire.
+// ---------------------------------------------------------------------------
+/** What kind of concern a review item raises. */
+export const reviewItemCategorySchema = v.picklist([
+    'gap',
+    'clarification',
+    'assumption',
+    'risk',
+    'question',
+]);
+/** How important resolving the item is before implementation should proceed. */
+export const reviewItemSeveritySchema = v.picklist(['low', 'medium', 'high']);
+/**
+ * Lifecycle of a single item: `open` until a human engages, `answered` once a
+ * reply is recorded, `resolved` when accepted as done, `dismissed` when waved
+ * off as not applicable. Both `resolved` and `dismissed` count as "settled" for
+ * the purpose of gating incorporation.
+ */
+export const reviewItemStatusSchema = v.picklist(['open', 'answered', 'resolved', 'dismissed']);
+/** A single question / challenge the reviewer raised about the requirements. */
+export const requirementReviewItemSchema = v.object({
+    id: v.string(),
+    category: reviewItemCategorySchema,
+    severity: reviewItemSeveritySchema,
+    /** Short headline of the concern. */
+    title: v.string(),
+    /** The full question / gap / challenge, in plain prose. */
+    detail: v.string(),
+    status: reviewItemStatusSchema,
+    /** The human's answer, or null while unanswered. */
+    reply: v.nullable(v.string()),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+});
+/**
+ * Lifecycle of the review as a whole:
+ * - `ready`: the reviewer raised findings that are awaiting human answers/dismissals.
+ * - `incorporating`: transient. The human answered the findings and asked to incorporate;
+ *   the durable driver is folding the answers into a document (the FIRST async stage). No
+ *   human action is needed — the user is back on the board.
+ * - `reviewing`: transient. The document is folded and the reviewer is RE-reviewing it (the
+ *   SECOND async stage). Distinguished from `incorporating` so the board/window can show
+ *   which stage is running; the user is summoned again only if it yields `ready`/`exceeded`.
+ * - `merged`: the companion produced an incorporated document (an internal transient on the
+ *   async path — the driver re-reviews it immediately; only the off-path inline incorporate
+ *   leaves a review here momentarily).
+ * - `exceeded`: the iteration cap was reached with findings still open — awaiting the
+ *   human's choice (one more round / proceed anyway / reset the task).
+ * - `incorporated`: terminal. The requirements phase is settled; downstream agents
+ *   consume {@link incorporatedRequirements} when present (else the original description).
+ */
+export const requirementReviewStatusSchema = v.picklist([
+    'ready',
+    'incorporating',
+    'reviewing',
+    'merged',
+    'exceeded',
+    'incorporated',
+]);
+/** A completed requirements review for one board block. */
+export const requirementReviewSchema = v.object({
+    id: v.string(),
+    blockId: v.string(),
+    status: requirementReviewStatusSchema,
+    items: v.array(requirementReviewItemSchema),
+    /** `provider:model` that produced the review, for transparency; null in tests. */
+    model: v.nullable(v.string()),
+    /**
+     * The revised requirements text the incorporation companion last folded the answers
+     * into. Set once a doc has been produced (status `merged`/`incorporated`); null while
+     * still awaiting answers on the first pass. Consumed by every downstream agent step +
+     * the spec-writer once the phase is settled.
+     */
+    incorporatedRequirements: v.nullable(v.string()),
+    /**
+     * How many reviewer passes have run so far (the initial review is iteration 1; each
+     * re-review adds one). Compared against {@link maxIterations} to decide when the loop
+     * has exhausted its budget.
+     */
+    iteration: v.optional(v.number(), 1),
+    /**
+     * The reviewer-pass budget for this review, snapshotted from the task's merge preset
+     * (`maxRequirementIterations`) when the review started. An "extra round" choice bumps
+     * it by one.
+     */
+    maxIterations: v.optional(v.number(), 1),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+});
+// ---- Request bodies -------------------------------------------------------
+/** Record a human's answer to a single review item. */
+export const replyReviewItemSchema = v.object({
+    reply: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(4000)),
+});
+/** Set a review item's status (resolve / dismiss / reopen). */
+export const updateReviewItemStatusSchema = v.object({
+    status: reviewItemStatusSchema,
+});
+/**
+ * Incorporate the settled answers into a standardized requirements document. An optional
+ * `feedback` comment is the human's "do it differently" lever when redoing a merge they
+ * were unhappy with — it is folded into the rework prompt alongside the prior document.
+ */
+export const incorporateRequirementsSchema = v.object({
+    feedback: v.optional(v.pipe(v.string(), v.trim(), v.maxLength(4000))),
+});
+/**
+ * How a human resolves a requirements review that hit its iteration cap with findings
+ * still open: `extra-round` grants one more reviewer pass, `proceed` advances the
+ * pipeline using the last incorporated document, `stop-reset` cancels the run and
+ * returns the task to phase zero (editable) while keeping the last incorporated doc.
+ * Shares the {@link iterationCapChoiceSchema} with the companion gate — same three
+ * choices, one source of truth (see `./iteration-cap.ts`).
+ */
+export const resolveRequirementsExceededSchema = v.object({
+    choice: iterationCapChoiceSchema,
+});
+// NOTE: the durable, in-repo PRESCRIPTIVE specification (the `spec.json` tree with its
+// requirements, domain rules and acceptance criteria) lives in `./spec.ts`. This file
+// is only the transient, per-block CONTEXT review of the linked-prose brief.
+//# sourceMappingURL=requirements.js.map

package/dist/requirements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirements.js","sourceRoot":"","sources":["../src/requirements.ts"],"names":[],"mappings":"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"}