@cat-factory/orchestration 0.6.0

package/dist/modules/requirements/RequirementReviewService.d.ts

@@ -0,0 +1,48 @@
+import type { Block, RequirementReview, RequirementReviewItem } from '@cat-factory/kernel';
+import type { DocumentRepository, TaskRepository } from '@cat-factory/kernel';
+import type { RequirementReviewRepository } from '@cat-factory/kernel';
+import { type IterativeReviewDeps, IterativeReviewService, type ReviewCommon, type ReviewRepository } from '../review/IterativeReviewService.js';
+import { type RequirementsContext } from './requirements.logic.js';
+export interface RequirementReviewServiceDependencies extends IterativeReviewDeps {
+    requirementReviewRepository: RequirementReviewRepository;
+    /** Linked PRD/RFC documents (optional; only when the documents integration is on). */
+    documentRepository?: DocumentRepository;
+    /** Linked tracker issues (optional; only when the task-source integration is on). */
+    taskRepository?: TaskRepository;
+}
+/**
+ * The requirements-review agent: a single LLM call reviews a block's collected requirements
+ * (description + linked PRD/RFC docs + tracker issues) and raises questions/challenges,
+ * humans answer them, and a second LLM call folds the answers into a standardized
+ * requirements document. The whole iterative loop lives in {@link IterativeReviewService};
+ * this class supplies only the requirements-specific subject, prompts and document field.
+ */
+export declare class RequirementReviewService extends IterativeReviewService<RequirementReview, RequirementsContext> {
+    protected readonly repository: ReviewRepository<RequirementReview>;
+    private readonly documentRepository?;
+    private readonly taskRepository?;
+    constructor(deps: RequirementReviewServiceDependencies);
+    protected readonly entityName = "Requirement review";
+    protected readonly reviewerLabel = "requirements reviewer";
+    protected readonly reviewAgentKind = "requirements-review";
+    protected readonly reworkAgentKind = "requirements-rework";
+    protected readonly reviewSystemPrompt: string;
+    protected readonly reworkSystemPrompt: string;
+    protected readonly reviewIdPrefix = "rrv";
+    protected readonly itemIdPrefix = "rri";
+    protected readonly revisedNoun = "revised requirements";
+    protected readonly truncationMessage: string;
+    protected readonly notificationType: 'requirement_review';
+    protected readonly notificationSubject = "The reviewer";
+    protected notificationTitle(block: Block): string;
+    protected buildReviewPrompt(ctx: RequirementsContext): string;
+    protected buildReworkPrompt(ctx: RequirementsContext, items: RequirementReviewItem[]): string;
+    protected applyIncorporatedDoc(ctx: RequirementsContext, doc: string): void;
+    protected applyFeedback(ctx: RequirementsContext, feedback: string): void;
+    protected readDoc(review: RequirementReview): string | null;
+    protected withDoc(review: RequirementReview, doc: string): RequirementReview;
+    protected newReview(common: ReviewCommon): RequirementReview;
+    /** Assemble the block's collected requirements + any linked docs/issues. */
+    protected gatherContext(workspaceId: string, block: Block): Promise<RequirementsContext>;
+}
+//# sourceMappingURL=RequirementReviewService.d.ts.map

package/dist/modules/requirements/RequirementReviewService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequirementReviewService.d.ts","sourceRoot":"","sources":["../../../src/modules/requirements/RequirementReviewService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAC1F,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC7E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAA;AAEtE,OAAO,EACL,KAAK,mBAAmB,EACxB,sBAAsB,EACtB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACtB,MAAM,qCAAqC,CAAA;AAC5C,OAAO,EACL,KAAK,mBAAmB,EAGzB,MAAM,yBAAyB,CAAA;AAEhC,MAAM,WAAW,oCAAqC,SAAQ,mBAAmB;IAC/E,2BAA2B,EAAE,2BAA2B,CAAA;IACxD,sFAAsF;IACtF,kBAAkB,CAAC,EAAE,kBAAkB,CAAA;IACvC,qFAAqF;IACrF,cAAc,CAAC,EAAE,cAAc,CAAA;CAChC;AAED;;;;;;GAMG;AACH,qBAAa,wBAAyB,SAAQ,sBAAsB,CAClE,iBAAiB,EACjB,mBAAmB,CACpB;IACC,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,CAAA;IAClE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAoB;IACxD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAgB;IAEhD,YAAY,IAAI,EAAE,oCAAoC,EAKrD;IAED,SAAS,CAAC,QAAQ,CAAC,UAAU,wBAAuB;IACpD,SAAS,CAAC,QAAQ,CAAC,aAAa,2BAA0B;IAC1D,SAAS,CAAC,QAAQ,CAAC,eAAe,yBAAwB;IAC1D,SAAS,CAAC,QAAQ,CAAC,eAAe,yBAAwB;IAC1D,SAAS,CAAC,QAAQ,CAAC,kBAAkB,SAAuB;IAC5D,SAAS,CAAC,QAAQ,CAAC,kBAAkB,SAAuB;IAC5D,SAAS,CAAC,QAAQ,CAAC,cAAc,SAAQ;IACzC,SAAS,CAAC,QAAQ,CAAC,YAAY,SAAQ;IACvC,SAAS,CAAC,QAAQ,CAAC,WAAW,0BAAyB;IACvD,SAAS,CAAC,QAAQ,CAAC,iBAAiB,SAEwC;IAC5E,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAG,oBAAoB,CAAS;IACnE,SAAS,CAAC,QAAQ,CAAC,mBAAmB,kBAAiB;IAEvD,SAAS,CAAC,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAEhD;IAED,SAAS,CAAC,iBAAiB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAE5D;IAED,SAAS,CAAC,iBAAiB,CAAC,GAAG,EAAE,mBAAmB,EAAE,KAAK,EAAE,qBAAqB,EAAE,GAAG,MAAM,CAE5F;IAED,SAAS,CAAC,oBAAoB,CAAC,GAAG,EAAE,mBAAmB,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAE1E;IAED,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAExE;IAED,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI,CAE1D;IAED,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAE3E;IAED,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,iBAAiB,CAE3D;IAED,4EAA4E;IAC5E,UAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAsB7F;CACF"}

package/dist/modules/requirements/RequirementReviewService.js

@@ -0,0 +1,83 @@
+import { REVIEW_SYSTEM_PROMPT, REWORK_SYSTEM_PROMPT } from '@cat-factory/agents';
+import { IterativeReviewService, } from '../review/IterativeReviewService.js';
+import { buildReviewPrompt, buildReworkPrompt, } from './requirements.logic.js';
+/**
+ * The requirements-review agent: a single LLM call reviews a block's collected requirements
+ * (description + linked PRD/RFC docs + tracker issues) and raises questions/challenges,
+ * humans answer them, and a second LLM call folds the answers into a standardized
+ * requirements document. The whole iterative loop lives in {@link IterativeReviewService};
+ * this class supplies only the requirements-specific subject, prompts and document field.
+ */
+export class RequirementReviewService extends IterativeReviewService {
+    repository;
+    documentRepository;
+    taskRepository;
+    constructor(deps) {
+        super(deps);
+        this.repository = deps.requirementReviewRepository;
+        this.documentRepository = deps.documentRepository;
+        this.taskRepository = deps.taskRepository;
+    }
+    entityName = 'Requirement review';
+    reviewerLabel = 'requirements reviewer';
+    reviewAgentKind = 'requirements-review';
+    reworkAgentKind = 'requirements-rework';
+    reviewSystemPrompt = REVIEW_SYSTEM_PROMPT;
+    reworkSystemPrompt = REWORK_SYSTEM_PROMPT;
+    reviewIdPrefix = 'rrv';
+    itemIdPrefix = 'rri';
+    revisedNoun = 'revised requirements';
+    truncationMessage = 'The reworked requirements were cut off before completion (model output limit ' +
+        'reached). Try splitting this work into smaller tasks, then rework again.';
+    notificationType = 'requirement_review';
+    notificationSubject = 'The reviewer';
+    notificationTitle(block) {
+        return `Requirements review: ${block.title}`;
+    }
+    buildReviewPrompt(ctx) {
+        return buildReviewPrompt(ctx);
+    }
+    buildReworkPrompt(ctx, items) {
+        return buildReworkPrompt(ctx, items);
+    }
+    applyIncorporatedDoc(ctx, doc) {
+        ctx.incorporatedDoc = doc;
+    }
+    applyFeedback(ctx, feedback) {
+        ctx.reworkFeedback = feedback;
+    }
+    readDoc(review) {
+        return review.incorporatedRequirements;
+    }
+    withDoc(review, doc) {
+        return { ...review, incorporatedRequirements: doc };
+    }
+    newReview(common) {
+        return { ...common, incorporatedRequirements: null };
+    }
+    /** Assemble the block's collected requirements + any linked docs/issues. */
+    async gatherContext(workspaceId, block) {
+        const docs = this.documentRepository
+            ? (await this.documentRepository.listByBlock(workspaceId, block.id)).map((d) => ({
+                title: d.title,
+                url: d.url,
+                excerpt: d.excerpt,
+            }))
+            : [];
+        const tasks = this.taskRepository
+            ? (await this.taskRepository.listByBlock(workspaceId, block.id)).map((t) => ({
+                key: t.externalId,
+                title: t.title,
+                status: t.status,
+                type: t.type,
+                description: t.description,
+            }))
+            : [];
+        return {
+            block: { title: block.title, type: block.type, description: block.description },
+            docs,
+            tasks,
+        };
+    }
+}
+//# sourceMappingURL=RequirementReviewService.js.map

package/dist/modules/requirements/RequirementReviewService.js.map

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

package/dist/modules/requirements/requirements.logic.d.ts

@@ -0,0 +1,93 @@
+import type { Block, RequirementConcernLevel, RequirementReviewItem } from '@cat-factory/kernel';
+/** A requirements/PRD/RFC document linked to the block as context. */
+export interface ReviewContextDoc {
+    title: string;
+    url: string;
+    excerpt: string;
+}
+/** A tracker issue linked to the block as context. */
+export interface ReviewContextTask {
+    key: string;
+    title: string;
+    status: string;
+    type: string;
+    description: string;
+}
+/** Everything the reviewer reasons over: the block plus its linked context. */
+export interface RequirementsContext {
+    block: Pick<Block, 'title' | 'type' | 'description'>;
+    docs: ReviewContextDoc[];
+    tasks: ReviewContextTask[];
+    /**
+     * The standardized requirements document produced by a prior incorporation. When
+     * present (a re-review or a redo), it is the authoritative requirements text the
+     * reviewer/rework reasons over — the original description + linked context become
+     * background reference. Absent on the first pass.
+     */
+    incorporatedDoc?: string;
+    /**
+     * The human's freeform "do it differently" comment when redoing a merge they were
+     * unhappy with — folded into the next rework so it corrects course. Absent otherwise.
+     */
+    reworkFeedback?: string;
+}
+/**
+ * Render the block's "collected requirements" as a single Markdown document — the
+ * standardized incorporated document when one exists (a later review/rework cycle),
+ * else the block description, plus any linked PRD/RFC pages and tracker issues. Used
+ * both as the reviewer's input and as the base the incorporate step rewrites.
+ */
+export declare function renderRequirements(ctx: RequirementsContext): string;
+export declare function buildReviewPrompt(ctx: RequirementsContext): string;
+/** Pull the first JSON object out of a model response (tolerates code fences). */
+export declare function extractJson(text: string): unknown;
+/**
+ * Coerce the model's parsed JSON into review items. Tolerant: unknown
+ * categories/severities fall back to sensible defaults, items missing both a
+ * title and detail are dropped, and the result is sorted high-severity first and
+ * capped so a runaway response can't flood the board.
+ */
+export declare function coerceReviewItems(raw: unknown, newId: () => string, now: number): RequirementReviewItem[];
+/**
+ * Build the user prompt for the requirements-rework step: the gathered context plus
+ * the human's answers (resolved items, folded in) and dismissals (kept out). Works
+ * with an empty item list too — the "no challenges" path simply restates the
+ * requirements in the standard structure. The {@link REWORK_SYSTEM_PROMPT} (in
+ * `@cat-factory/agents`) defines the required output structure.
+ */
+export declare function buildReworkPrompt(ctx: RequirementsContext, items: RequirementReviewItem[]): string;
+/**
+ * Whether an incorporation pass has anything to fold in: at least one finding the human
+ * answered/resolved with a non-empty reply, or a freeform "do it differently" feedback.
+ * When false, the rework + re-review LLM calls would add no new facts — the only thing
+ * {@link buildReworkPrompt} could still emit is dismissed items as negative "do NOT add"
+ * guidance, never new content — so the engine skips them and settles the review directly
+ * (the parallel of a polling gate's "precheck passed, don't spin up the agent" skip).
+ * Matches the `answered` filter {@link buildReworkPrompt} uses to decide what gets folded
+ * in. Note this changes the all-dismissed case: it no longer produces an LLM-restated
+ * (reformatted-but-fact-identical) document; downstream consumes the last incorporated
+ * doc if an earlier iteration produced one, else the original description.
+ */
+export declare function hasNotesToIncorporate(items: RequirementReviewItem[], feedback?: string): boolean;
+/**
+ * What the engine should do with a reviewer pass's findings:
+ * - `auto-pass`: no outstanding findings, or every outstanding finding's severity is at
+ *   or below the task's tolerated level — record them but advance without a human.
+ * - `awaiting`: outstanding findings above the tolerated level and the iteration budget
+ *   has room — pause for the human to answer/dismiss.
+ * - `exceeded`: outstanding findings above the tolerated level but the iteration budget
+ *   is spent — pause for the human to pick how to proceed.
+ */
+export type ReviewDisposition = 'auto-pass' | 'awaiting' | 'exceeded';
+/**
+ * Decide a reviewer pass's disposition from its findings, the task's tolerated concern
+ * level and the iteration budget. Only OUTSTANDING items (not yet resolved/dismissed)
+ * gate the run, so a pass whose findings the human later dismisses converges. Pure so
+ * the engine + tests share one rule.
+ */
+export declare function disposeReview(items: RequirementReviewItem[], opts: {
+    iteration: number;
+    maxIterations: number;
+    concernThreshold: RequirementConcernLevel;
+}): ReviewDisposition;
+//# sourceMappingURL=requirements.logic.d.ts.map

package/dist/modules/requirements/requirements.logic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirements.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/requirements/requirements.logic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EACL,uBAAuB,EACvB,qBAAqB,EAGtB,MAAM,qBAAqB,CAAA;AAa5B,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,sDAAsD;AACtD,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,aAAa,CAAC,CAAA;IACpD,IAAI,EAAE,gBAAgB,EAAE,CAAA;IACxB,KAAK,EAAE,iBAAiB,EAAE,CAAA;IAC1B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAyBnE;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAwBlE;AAED,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CASjD;AAgBD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,MAAM,MAAM,EACnB,GAAG,EAAE,MAAM,GACV,qBAAqB,EAAE,CA2BzB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,mBAAmB,EACxB,KAAK,EAAE,qBAAqB,EAAE,GAC7B,MAAM,CA6CR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,qBAAqB,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAKhG;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,UAAU,GAAG,UAAU,CAAA;AAErE;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,qBAAqB,EAAE,EAC9B,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,uBAAuB,CAAA;CAAE,GAC5F,iBAAiB,CAOnB"}

package/dist/modules/requirements/requirements.logic.js

@@ -0,0 +1,203 @@
+import { REQUIREMENT_CONCERN_RANK } from '@cat-factory/contracts';
+// Pure logic for the requirements-review agent: assembling the "collected
+// requirements" text from a block + its linked context, building the review and
+// incorporate prompts, and coercing the model's JSON response into review items.
+// Kept side-effect-free so the integration tests can exercise the prompt/parse
+// paths directly and the service stays a thin orchestrator.
+const CATEGORIES = ['gap', 'clarification', 'assumption', 'risk', 'question'];
+const SEVERITIES = ['low', 'medium', 'high'];
+const SEVERITY_RANK = { high: 0, medium: 1, low: 2 };
+/**
+ * Render the block's "collected requirements" as a single Markdown document — the
+ * standardized incorporated document when one exists (a later review/rework cycle),
+ * else the block description, plus any linked PRD/RFC pages and tracker issues. Used
+ * both as the reviewer's input and as the base the incorporate step rewrites.
+ */
+export function renderRequirements(ctx) {
+    const lines = ctx.incorporatedDoc?.trim()
+        ? [
+            `# ${ctx.block.title} (${ctx.block.type})`,
+            '',
+            '## Current standardized requirements (under review)',
+            ctx.incorporatedDoc.trim(),
+        ]
+        : [
+            `# ${ctx.block.title} (${ctx.block.type})`,
+            '',
+            '## Description',
+            ctx.block.description?.trim() || '(no description provided)',
+        ];
+    if (ctx.docs.length) {
+        lines.push('', '## Linked requirement / PRD / RFC documents');
+        for (const d of ctx.docs)
+            lines.push('', `### ${d.title} (${d.url})`, d.excerpt);
+    }
+    if (ctx.tasks.length) {
+        lines.push('', '## Linked tracker issues');
+        for (const t of ctx.tasks) {
+            lines.push('', `### ${t.key} — ${t.title} [${t.type} / ${t.status}]`, t.description);
+        }
+    }
+    return lines.join('\n');
+}
+export function buildReviewPrompt(ctx) {
+    return [
+        'Here are the collected requirements to review:',
+        '',
+        renderRequirements(ctx),
+        '',
+        'Produce a JSON object of this exact shape:',
+        '{',
+        '  "items": [',
+        '    {',
+        '      "category": "gap|clarification|assumption|risk|question",',
+        '      "severity": "low|medium|high",',
+        '      "title": "short headline of the concern",',
+        '      "detail": "the full question / gap / challenge, phrased for a product owner"',
+        '    }',
+        '  ]',
+        '}',
+        '',
+        'Assign a severity to EVERY item — no item may omit it. Use `high` for a gap or ' +
+            'ambiguity that would block correct implementation, `medium` for one that risks ' +
+            'rework or a wrong assumption, and `low` for a minor clarification or nice-to-have. ' +
+            'Raise between 0 and 20 items, ordered by severity (high first). If the requirements ' +
+            'are genuinely complete and unambiguous, return an empty items array. Output JSON only.',
+    ].join('\n');
+}
+/** Pull the first JSON object out of a model response (tolerates code fences). */
+export function extractJson(text) {
+    const start = text.indexOf('{');
+    const end = text.lastIndexOf('}');
+    if (start === -1 || end <= start)
+        return null;
+    try {
+        return JSON.parse(text.slice(start, end + 1));
+    }
+    catch {
+        return null;
+    }
+}
+function asString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function coerceCategory(value) {
+    return CATEGORIES.includes(value)
+        ? value
+        : 'question';
+}
+function coerceSeverity(value) {
+    return SEVERITIES.includes(value) ? value : 'medium';
+}
+/**
+ * Coerce the model's parsed JSON into review items. Tolerant: unknown
+ * categories/severities fall back to sensible defaults, items missing both a
+ * title and detail are dropped, and the result is sorted high-severity first and
+ * capped so a runaway response can't flood the board.
+ */
+export function coerceReviewItems(raw, newId, now) {
+    const list = Array.isArray(raw?.items)
+        ? raw.items
+        : Array.isArray(raw)
+            ? raw
+            : [];
+    const items = [];
+    for (const entry of list) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const obj = entry;
+        const title = asString(obj.title);
+        const detail = asString(obj.detail) || asString(obj.question);
+        if (!title && !detail)
+            continue;
+        items.push({
+            id: newId(),
+            category: coerceCategory(obj.category),
+            severity: coerceSeverity(obj.severity),
+            title: title || detail.slice(0, 80),
+            detail: detail || title,
+            status: 'open',
+            reply: null,
+            createdAt: now,
+            updatedAt: now,
+        });
+    }
+    items.sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity]);
+    return items.slice(0, 20);
+}
+/**
+ * Build the user prompt for the requirements-rework step: the gathered context plus
+ * the human's answers (resolved items, folded in) and dismissals (kept out). Works
+ * with an empty item list too — the "no challenges" path simply restates the
+ * requirements in the standard structure. The {@link REWORK_SYSTEM_PROMPT} (in
+ * `@cat-factory/agents`) defines the required output structure.
+ */
+export function buildReworkPrompt(ctx, items) {
+    const lines = ['Current collected requirements:', '', renderRequirements(ctx), ''];
+    // An answered item (the human recorded a reply) is folded in; a resolved one too.
+    const answered = items.filter((i) => (i.status === 'answered' || i.status === 'resolved') && i.reply?.trim());
+    const dismissed = items.filter((i) => i.status === 'dismissed');
+    if (answered.length) {
+        lines.push('Clarifications the product owner provided (fold these in):', '');
+        for (const i of answered) {
+            lines.push(`- Q (${i.category}): ${i.title} — ${i.detail}`);
+            lines.push(`  A: ${i.reply?.trim() || '(no answer recorded)'}`);
+        }
+        lines.push('');
+    }
+    if (dismissed.length) {
+        lines.push('Items the product owner dismissed as out of scope (do NOT add these):', '');
+        for (const i of dismissed)
+            lines.push(`- ${i.title}`);
+        lines.push('');
+    }
+    if (!answered.length && !dismissed.length) {
+        lines.push('The reviewer raised no open questions — restate the requirements cleanly in the ' +
+            'standard structure without inventing new facts.', '');
+    }
+    // When the human was unhappy with a previous merge and asked to redo it, fold their
+    // freeform direction in so this attempt corrects course rather than repeating it.
+    if (ctx.reworkFeedback?.trim()) {
+        lines.push('', 'The reviewer was UNHAPPY with your previous reworked document and asked you to ' +
+            'redo it with this specific direction — follow it closely:', '', ctx.reworkFeedback.trim(), '');
+    }
+    lines.push('Rewrite the requirements as a single self-contained Markdown document in the standard ' +
+        'structure described in your instructions, folding in every answer above. Output the ' +
+        'revised requirements only.');
+    return lines.join('\n');
+}
+/**
+ * Whether an incorporation pass has anything to fold in: at least one finding the human
+ * answered/resolved with a non-empty reply, or a freeform "do it differently" feedback.
+ * When false, the rework + re-review LLM calls would add no new facts — the only thing
+ * {@link buildReworkPrompt} could still emit is dismissed items as negative "do NOT add"
+ * guidance, never new content — so the engine skips them and settles the review directly
+ * (the parallel of a polling gate's "precheck passed, don't spin up the agent" skip).
+ * Matches the `answered` filter {@link buildReworkPrompt} uses to decide what gets folded
+ * in. Note this changes the all-dismissed case: it no longer produces an LLM-restated
+ * (reformatted-but-fact-identical) document; downstream consumes the last incorporated
+ * doc if an earlier iteration produced one, else the original description.
+ */
+export function hasNotesToIncorporate(items, feedback) {
+    if (feedback?.trim())
+        return true;
+    return items.some((i) => (i.status === 'answered' || i.status === 'resolved') && !!i.reply?.trim());
+}
+/**
+ * Decide a reviewer pass's disposition from its findings, the task's tolerated concern
+ * level and the iteration budget. Only OUTSTANDING items (not yet resolved/dismissed)
+ * gate the run, so a pass whose findings the human later dismisses converges. Pure so
+ * the engine + tests share one rule.
+ */
+export function disposeReview(items, opts) {
+    const outstanding = items.filter((i) => i.status !== 'dismissed' && i.status !== 'resolved');
+    if (outstanding.length === 0)
+        return 'auto-pass';
+    const maxRank = Math.max(...outstanding.map((i) => REQUIREMENT_CONCERN_RANK[i.severity]));
+    if (maxRank <= REQUIREMENT_CONCERN_RANK[opts.concernThreshold])
+        return 'auto-pass';
+    if (opts.iteration >= opts.maxIterations)
+        return 'exceeded';
+    return 'awaiting';
+}
+//# sourceMappingURL=requirements.logic.js.map

package/dist/modules/requirements/requirements.logic.js.map

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

package/dist/modules/review/IterativeReviewService.d.ts

@@ -0,0 +1,175 @@
+import type { Block, BlockRepository, Clock, IdGenerator, ModelProvider, ModelProviderResolver, ModelRef, NotificationType, RequirementConcernLevel, RequirementReviewItem, RequirementReviewStatus, ReviewItemStatus } from '@cat-factory/kernel';
+import type { NotificationService } from '../notifications/NotificationService.js';
+/** The fields every review (requirements or clarity) shares; the doc field is per-kind. */
+export interface ReviewCommon {
+    id: string;
+    blockId: string;
+    status: RequirementReviewStatus;
+    items: RequirementReviewItem[];
+    model: string | null;
+    iteration: number;
+    maxIterations: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/** The structural persistence port both review repositories satisfy. */
+export interface ReviewRepository<TReview> {
+    getByBlock(workspaceId: string, blockId: string): Promise<TReview | null>;
+    get(workspaceId: string, id: string): Promise<TReview | null>;
+    upsert(workspaceId: string, review: TReview): Promise<void>;
+    deleteByBlock(workspaceId: string, blockId: string): Promise<void>;
+}
+/** The runtime dependencies shared by every iterative-review service. */
+export interface IterativeReviewDeps {
+    blockRepository: BlockRepository;
+    idGenerator: IdGenerator;
+    clock: Clock;
+    /** Resolve a {@link ModelProvider} for a workspace's credential scope. Preferred. */
+    modelProviderResolver?: ModelProviderResolver;
+    /** Static reviewer model provider (e.g. a fake in tests). Used when no resolver is set. */
+    modelProvider?: ModelProvider;
+    /** Default model ref when the block pins none — the agents' routing default. */
+    modelRef?: ModelRef;
+    /** Resolve a block's selected model id to a ref (the deployment-aware resolver). */
+    resolveBlockModel?: (modelId: string | undefined) => ModelRef | undefined;
+    /** Resolve the workspace's per-agent-kind default model id (consulted when the block pins none). */
+    resolveWorkspaceModelDefault?: (workspaceId: string, agentKind: string) => Promise<string | undefined>;
+    /** Raises a notification when a review yields findings. Optional. */
+    notificationService?: NotificationService;
+}
+/**
+ * Stateless, synchronous iterative reviewer (no container, no durable driver). The LLM is
+ * reached through the provider-agnostic {@link ModelProvider} port — the same one the
+ * document planner uses — so this service never imports a provider SDK or an API key. The
+ * model is resolved exactly like an agent step: a model pinned on the block wins, else the
+ * workspace's per-kind default, else the routing default (which falls back to Cloudflare
+ * Workers AI when no direct provider key is set). Reads of an existing review work
+ * regardless.
+ *
+ * @typeParam TReview      The persisted review type (adds a kind-specific document field).
+ * @typeParam TContext     The reviewer's per-kind context (the subject under review).
+ * @typeParam TContextInput Extra per-call inputs threaded into context gathering (e.g. an
+ *                          investigation report for clarity); `{}` when a kind needs none.
+ */
+export declare abstract class IterativeReviewService<TReview extends ReviewCommon, TContext, TContextInput = unknown> {
+    protected readonly deps: IterativeReviewDeps;
+    constructor(deps: IterativeReviewDeps);
+    protected abstract readonly repository: ReviewRepository<TReview>;
+    /** Label for `assertFound` (e.g. 'Requirement review' / 'Clarity review'). */
+    protected abstract readonly entityName: string;
+    /** Human label for error messages (e.g. 'requirements reviewer' / 'clarity reviewer'). */
+    protected abstract readonly reviewerLabel: string;
+    /** The agent kind keying the workspace default model + observability (e.g. 'requirements-review'). */
+    protected abstract readonly reviewAgentKind: string;
+    /** The rework agent kind for observability (e.g. 'requirements-rework'). */
+    protected abstract readonly reworkAgentKind: string;
+    protected abstract readonly reviewSystemPrompt: string;
+    protected abstract readonly reworkSystemPrompt: string;
+    /** Id prefix for fresh reviews / items (e.g. 'rrv' / 'rri'). */
+    protected abstract readonly reviewIdPrefix: string;
+    protected abstract readonly itemIdPrefix: string;
+    /** Noun for the "no revised X produced" error (e.g. 'revised requirements'). */
+    protected abstract readonly revisedNoun: string;
+    /** The full error message when the rework output is length-truncated. */
+    protected abstract readonly truncationMessage: string;
+    protected abstract readonly notificationType: NotificationType;
+    /** Notification title for a findings notification (e.g. `Requirements review: ${title}`). */
+    protected abstract notificationTitle(block: Block): string;
+    /** Notification body lead-in noun (e.g. 'The reviewer' / 'The clarity reviewer'). */
+    protected abstract readonly notificationSubject: string;
+    /** Assemble the subject under review (block + any kind-specific context). */
+    protected abstract gatherContext(workspaceId: string, block: Block, input: TContextInput): Promise<TContext>;
+    protected abstract buildReviewPrompt(ctx: TContext): string;
+    protected abstract buildReworkPrompt(ctx: TContext, items: RequirementReviewItem[]): string;
+    /** Apply a prior incorporated document to the context (a re-review / redo base). */
+    protected abstract applyIncorporatedDoc(ctx: TContext, doc: string): void;
+    /** Apply the human's freeform "do it differently" feedback to the context. */
+    protected abstract applyFeedback(ctx: TContext, feedback: string): void;
+    /** Read the kind-specific document field off a review. */
+    protected abstract readDoc(review: TReview): string | null;
+    /** Return a copy of the review with its document field set. */
+    protected abstract withDoc(review: TReview, doc: string): TReview;
+    /** Build a fresh review from the common fields, initialising the document field to null. */
+    protected abstract newReview(common: ReviewCommon): TReview;
+    /** Whether the LLM-backed review path is available. */
+    get enabled(): boolean;
+    /** The current review for a block, or null if none has been run. */
+    getForBlock(workspaceId: string, blockId: string): Promise<TReview | null>;
+    /**
+     * Run a fresh review of a block (iteration 1). Replaces any prior review for the block
+     * (answers from a stale run don't carry over). The returned review's `status` encodes the
+     * disposition: `incorporated` (auto-pass — advance), `ready` (findings to answer) or
+     * `exceeded` (findings but the iteration budget is already 1).
+     */
+    review(workspaceId: string, blockId: string, opts?: {
+        maxIterations?: number;
+        concernThreshold?: RequirementConcernLevel;
+    } & TContextInput): Promise<TReview>;
+    /**
+     * Re-review the block against its current incorporated document (one more reviewer pass;
+     * `iteration` increments). Keeps the review id + the document; replaces the items with the
+     * fresh findings and re-encodes the disposition into `status`. Called after an
+     * incorporation so the loop can converge (`incorporated`), continue (`ready`) or stop for a
+     * human (`exceeded`).
+     */
+    reReview(workspaceId: string, reviewId: string, opts?: {
+        concernThreshold?: RequirementConcernLevel;
+    }): Promise<TReview>;
+    /** Record a human's answer to one item (and flip it to `answered`). */
+    replyToItem(workspaceId: string, reviewId: string, itemId: string, reply: string): Promise<TReview>;
+    /** Set an item's status (resolve / dismiss / reopen). */
+    setItemStatus(workspaceId: string, reviewId: string, itemId: string, status: ReviewItemStatus): Promise<TReview>;
+    /**
+     * Incorporate the human's answers (and dismissals) into one self-contained, standard-format
+     * document. Requires every finding to be answered or dismissed (no `open` items). The
+     * optional `feedback` is the human's "do it differently" direction when redoing a merge they
+     * were unhappy with, folded into the prompt alongside the prior document. Stores the document
+     * on the review and parks it `merged` for the human to re-review or redo.
+     */
+    incorporate(workspaceId: string, reviewId: string, opts?: {
+        feedback?: string;
+    } & TContextInput): Promise<{
+        review: TReview;
+    }>;
+    /**
+     * Mark the review settled (`incorporated`) — the phase is done and the last incorporated
+     * document (if any) becomes what downstream agents consume.
+     */
+    markIncorporated(workspaceId: string, reviewId: string): Promise<TReview>;
+    /** Grant one more reviewer pass after the cap was hit, reopening the loop (`ready`). */
+    grantExtraRound(workspaceId: string, reviewId: string): Promise<TReview>;
+    /** Flag a review as `incorporating` (the durable driver is about to fold + re-review). */
+    markIncorporating(workspaceId: string, reviewId: string): Promise<TReview>;
+    /** Flag a review as `reviewing` (the second async stage — re-reviewing the folded document). */
+    markReReviewing(workspaceId: string, reviewId: string): Promise<TReview>;
+    /** The model provider for a workspace's scope (per-scope DB pool, else the static one). */
+    protected providerFor(workspaceId: string): Promise<ModelProvider | undefined>;
+    /**
+     * The model to run for a block, with the same precedence as a pipeline step: the block's
+     * pinned selection wins, else the workspace's per-kind default, else the routing default.
+     * A pinned subscription model (Claude Code / Codex) is degraded to the routing default
+     * because the reviewer is an INLINE LLM call with no provider key for the container harness
+     * — the same seam the inline agent executor uses, so the two can't drift.
+     */
+    protected modelFor(workspaceId: string, block: Block): Promise<ModelRef | undefined>;
+    /** Resolve the provider + ref, throwing the kind's "no model configured" error if unavailable. */
+    protected resolveModel(workspaceId: string, block: Block): Promise<{
+        modelProvider: ModelProvider;
+        ref: ModelRef;
+    }>;
+    private reviewerFailed;
+    /** Run the reviewer LLM over the prepared context and coerce the JSON into review items. */
+    protected runReviewer(workspaceId: string, block: Block, context: TContext): Promise<{
+        ref: ModelRef;
+        items: RequirementReviewItem[];
+    }>;
+    /**
+     * Tell people to react to a review's findings. Best-effort and only when there ARE findings
+     * — a clean review pings no one. Never lets a notification failure break the awaited review.
+     */
+    protected notifyFindings(workspaceId: string, block: Block, findingCount: number): Promise<void>;
+    private load;
+    protected patchReview(workspaceId: string, reviewId: string, patch: (review: TReview) => TReview): Promise<TReview>;
+    private mutateItem;
+}
+//# sourceMappingURL=IterativeReviewService.d.ts.map