@cat-factory/contracts 0.6.0

package/dist/snapshot.js

@@ -0,0 +1,104 @@
+import * as v from 'valibot';
+import { blockSchema, executionInstanceSchema, pipelineSchema, spendStatusSchema, workspaceSchema, } from './entities.js';
+import { bootstrapJobSchema } from './bootstrap.js';
+import { notificationSchema } from './notifications.js';
+import { mergeThresholdPresetSchema } from './merge.js';
+import { agentConfigCatalogSchema } from './agent-config.js';
+import { modelDefaultsSchema } from './model-defaults.js';
+import { serviceFragmentDefaultsSchema } from './service-fragment-defaults.js';
+import { pipelineScheduleSchema } from './recurring.js';
+import { serviceSchema, workspaceMountSchema } from './services.js';
+import { trackerSettingsSchema } from './tracker.js';
+import { workspaceSettingsSchema } from './workspace-settings.js';
+// The full board snapshot returned by GET /workspaces/:id (and POST /workspaces).
+// It lives in its own module because it references both ./entities and
+// ./bootstrap, and ./bootstrap imports from ./entities — defining it in either
+// would be a circular import.
+export const workspaceSnapshotSchema = v.object({
+    workspace: workspaceSchema,
+    blocks: v.array(blockSchema),
+    pipelines: v.array(pipelineSchema),
+    executions: v.array(executionInstanceSchema),
+    /**
+     * Bootstrap runs for this workspace (the unified `agent_runs` table's bootstrap
+     * rows). Carried in the snapshot so the board can render a bootstrap's live
+     * progress / failure + retry the moment it loads, without a separate fetch that
+     * could fail independently. Attached by the worker, so optional on the wire.
+     */
+    bootstrapJobs: v.optional(v.array(bootstrapJobSchema)),
+    /**
+     * The current spend-safeguard status. Attached by the worker (it depends on
+     * deployment-wide pricing/budget config), so it is optional on the wire.
+     */
+    spend: v.optional(spendStatusSchema),
+    /**
+     * Open human-actionable notifications for this workspace (PRs awaiting a merge
+     * decision, completed pipelines awaiting confirmation, CI that gave up). Carried
+     * in the snapshot so the board renders the inbox + badges on load. Attached by
+     * the worker, so optional on the wire.
+     */
+    notifications: v.optional(v.array(notificationSchema)),
+    /**
+     * The workspace's merge threshold presets (the library a task picks its
+     * auto-merge policy from). Attached by the worker, so optional on the wire.
+     */
+    mergePresets: v.optional(v.array(mergeThresholdPresetSchema)),
+    /**
+     * The catalog of agent config-contribution descriptors (the task-level parameters
+     * the registered agent kinds surface, e.g. the Tester's environment). The board
+     * renders the subset whose owning kind appears in a task's selected pipeline.
+     * Static metadata derived from the agent registry; attached by the facade, so
+     * optional on the wire.
+     */
+    agentConfigCatalog: v.optional(agentConfigCatalogSchema),
+    /**
+     * The workspace's per-agent-kind default models (the model each agent kind
+     * defaults to, overriding the env routing for this workspace). Attached by the
+     * worker, so optional on the wire.
+     */
+    modelDefaults: v.optional(modelDefaultsSchema),
+    /**
+     * The deployment's env-routing defaults as `provider:model` refs: the model an
+     * agent kind runs on when neither the task nor the workspace pins one. `default`
+     * is the global fallback; `byKind` carries the kinds an operator routed
+     * specifically (e.g. a strong coding model for the coder). The frontend resolves
+     * a kind's deployment default as `byKind[kind] ?? default` and labels it so the
+     * model-defaults panel can name the model behind "Deployment default". Derived
+     * from shared config, attached by the facade, so optional on the wire.
+     */
+    deploymentModelDefaults: v.optional(v.object({
+        default: v.string(),
+        byKind: v.record(v.string(), v.string()),
+    })),
+    /**
+     * The workspace's default service-fragment selection (the best-practice fragment ids
+     * new services inherit). Attached by the facade, so optional on the wire.
+     */
+    serviceFragmentDefaults: v.optional(serviceFragmentDefaultsSchema),
+    /**
+     * The workspace's recurring pipelines (schedules that re-run a pipeline against
+     * a service on a cadence). Carried in the snapshot so the board renders the
+     * recurring-task badges + inspector on load. Run history is fetched lazily.
+     */
+    recurringPipelines: v.optional(v.array(pipelineScheduleSchema)),
+    /**
+     * The workspace's issue-tracker selection (where the tech-debt pipeline files
+     * its ticket). Attached by the worker, so optional on the wire.
+     */
+    trackerSettings: v.optional(trackerSettingsSchema),
+    /**
+     * In-org shared services. `mounts` are the services this workspace mounts (with the
+     * per-workspace frame layout); `serviceCatalog` is the org's services the board can
+     * mount from (each annotated with `mountCount` so the UI can badge a shared frame).
+     * Attached by the worker when the services module is wired, so optional on the wire.
+     */
+    mounts: v.optional(v.array(workspaceMountSchema)),
+    serviceCatalog: v.optional(v.array(serviceSchema)),
+    /**
+     * The workspace's runtime settings (the human-wait escalation threshold + the
+     * per-service running-task limit policy). Lazily seeded from the defaults; attached
+     * by the facade, so optional on the wire.
+     */
+    settings: v.optional(workspaceSettingsSchema),
+});
+//# sourceMappingURL=snapshot.js.map

package/dist/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,EACL,WAAW,EACX,uBAAuB,EACvB,cAAc,EACd,iBAAiB,EACjB,eAAe,GAChB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAA;AACvD,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAA;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzD,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAA;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AACvD,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAA;AAEjE,kFAAkF;AAClF,uEAAuE;AACvE,+EAA+E;AAC/E,8BAA8B;AAE9B,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,SAAS,EAAE,eAAe;IAC1B,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC;IAC5B,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC;IAClC,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,uBAAuB,CAAC;IAC5C;;;;;OAKG;IACH,aAAa,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACtD;;;OAGG;IACH,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IACpC;;;;;OAKG;IACH,aAAa,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACtD;;;OAGG;IACH,YAAY,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;IAC7D;;;;;;OAMG;IACH,kBAAkB,EAAE,CAAC,CAAC,QAAQ,CAAC,wBAAwB,CAAC;IACxD;;;;OAIG;IACH,aAAa,EAAE,CAAC,CAAC,QAAQ,CAAC,mBAAmB,CAAC;IAC9C;;;;;;;;OAQG;IACH,uBAAuB,EAAE,CAAC,CAAC,QAAQ,CACjC,CAAC,CAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;QACnB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;KACzC,CAAC,CACH;IACD;;;OAGG;IACH,uBAAuB,EAAE,CAAC,CAAC,QAAQ,CAAC,6BAA6B,CAAC;IAClE;;;;OAIG;IACH,kBAAkB,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC/D;;;OAGG;IACH,eAAe,EAAE,CAAC,CAAC,QAAQ,CAAC,qBAAqB,CAAC;IAClD;;;;;OAKG;IACH,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;IACjD,cAAc,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAClD;;;;OAIG;IACH,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,uBAAuB,CAAC;CAC9C,CAAC,CAAA"}

package/dist/spec.d.ts

@@ -0,0 +1,174 @@
+import * as v from 'valibot';
+/** MoSCoW priority — how essential a requirement is. */
+export declare const requirementPrioritySchema: v.PicklistSchema<["must", "should", "could"], undefined>;
+export type RequirementPriority = v.InferOutput<typeof requirementPrioritySchema>;
+/** Whether a requirement is a behaviour, a quality attribute, or a hard constraint. */
+export declare const requirementKindSchema: v.PicklistSchema<["functional", "nonfunctional", "constraint"], undefined>;
+export type RequirementKind = v.InferOutput<typeof requirementKindSchema>;
+/**
+ * A single acceptance criterion in structured Given/When/Then form — the seed for
+ * one Gherkin `Scenario`. Kept structured (not prose) so the harness can render it
+ * mechanically and deterministically into a `.feature` file.
+ */
+export declare const acceptanceCriterionSchema: v.ObjectSchema<{
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+    readonly given: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+    readonly when: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+    readonly outcome: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+}, undefined>;
+export type AcceptanceCriterion = v.InferOutput<typeof acceptanceCriterionSchema>;
+/** A single prescriptive requirement, traceable back to the board task(s) it came from. */
+export declare const requirementItemSchema: v.ObjectSchema<{
+    /** Stable slug, e.g. `req-login-rate-limit`. */
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+    /** Short headline. */
+    readonly title: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 120, undefined>]>;
+    /** The requirement itself, as `The system SHALL …` prose. */
+    readonly statement: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 4000, undefined>]>;
+    readonly kind: v.PicklistSchema<["functional", "nonfunctional", "constraint"], undefined>;
+    readonly priority: v.PicklistSchema<["must", "should", "could"], undefined>;
+    /** Ids of the board task/block(s) this requirement was aggregated from (provenance). */
+    readonly sourceBlockIds: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>, readonly []>;
+    /** Structured acceptance criteria → the seed for this requirement's Gherkin scenarios. */
+    readonly acceptance: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+        readonly given: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+        readonly when: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+        readonly outcome: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+    }, undefined>, undefined>, readonly []>;
+}, undefined>;
+export type RequirementItem = v.InferOutput<typeof requirementItemSchema>;
+/**
+ * A cross-cutting domain rule / invariant / constraint — prescriptive, but not tied
+ * to a single capability. Unified into THIS document (not a separate `domain/`
+ * artifact) because rules share the spec's lifecycle; rendered to `rules.md`.
+ */
+export declare const domainRuleSchema: v.ObjectSchema<{
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+    /** The invariant, e.g. `An order may never have a negative total.` */
+    readonly rule: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 4000, undefined>]>;
+    /** Why the rule exists (optional). */
+    readonly rationale: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, "">;
+    readonly sourceBlockIds: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>, readonly []>;
+}, undefined>;
+export type DomainRule = v.InferOutput<typeof domainRuleSchema>;
+/** A grouping of related requirements (a capability / feature area ≈ one `.feature` file). */
+export declare const requirementGroupSchema: v.ObjectSchema<{
+    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 120, undefined>]>;
+    readonly summary: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, "">;
+    readonly requirements: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        /** Stable slug, e.g. `req-login-rate-limit`. */
+        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+        /** Short headline. */
+        readonly title: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 120, undefined>]>;
+        /** The requirement itself, as `The system SHALL …` prose. */
+        readonly statement: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 4000, undefined>]>;
+        readonly kind: v.PicklistSchema<["functional", "nonfunctional", "constraint"], undefined>;
+        readonly priority: v.PicklistSchema<["must", "should", "could"], undefined>;
+        /** Ids of the board task/block(s) this requirement was aggregated from (provenance). */
+        readonly sourceBlockIds: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>, readonly []>;
+        /** Structured acceptance criteria → the seed for this requirement's Gherkin scenarios. */
+        readonly acceptance: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+            readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+            readonly given: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+            readonly when: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+            readonly outcome: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+        }, undefined>, undefined>, readonly []>;
+    }, undefined>, undefined>, readonly []>;
+}, undefined>;
+export type RequirementGroup = v.InferOutput<typeof requirementGroupSchema>;
+/** The unified, prescriptive specification document for one service (the `spec.json` tree). */
+export declare const specDocSchema: v.ObjectSchema<{
+    /** Service / frame name (defaults to the repo name). */
+    readonly service: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 120, undefined>]>;
+    /** One-paragraph product intent for the service overall. */
+    readonly summary: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, "">;
+    /** Requirements grouped by capability; each group renders one `.feature` file. */
+    readonly groups: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 120, undefined>]>;
+        readonly summary: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, "">;
+        readonly requirements: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+            /** Stable slug, e.g. `req-login-rate-limit`. */
+            readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+            /** Short headline. */
+            readonly title: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 120, undefined>]>;
+            /** The requirement itself, as `The system SHALL …` prose. */
+            readonly statement: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 4000, undefined>]>;
+            readonly kind: v.PicklistSchema<["functional", "nonfunctional", "constraint"], undefined>;
+            readonly priority: v.PicklistSchema<["must", "should", "could"], undefined>;
+            /** Ids of the board task/block(s) this requirement was aggregated from (provenance). */
+            readonly sourceBlockIds: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>, readonly []>;
+            /** Structured acceptance criteria → the seed for this requirement's Gherkin scenarios. */
+            readonly acceptance: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+                readonly given: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+                readonly when: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+                readonly outcome: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+            }, undefined>, undefined>, readonly []>;
+        }, undefined>, undefined>, readonly []>;
+    }, undefined>, undefined>, readonly []>;
+    /** Cross-cutting domain rules / invariants / constraints. */
+    readonly rules: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+        /** The invariant, e.g. `An order may never have a negative total.` */
+        readonly rule: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 4000, undefined>]>;
+        /** Why the rule exists (optional). */
+        readonly rationale: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, "">;
+        readonly sourceBlockIds: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>, readonly []>;
+    }, undefined>, undefined>, readonly []>;
+}, undefined>;
+export type SpecDoc = v.InferOutput<typeof specDocSchema>;
+/**
+ * The lightweight `version.json` manifest committed alongside the spec. It carries a
+ * monotonic version counter, the generation timestamp, a content hash of the
+ * canonical tree, and the requirement/rule counts — so staleness checks are a tiny
+ * read rather than a full parse of `spec.json`. Mirrors the blueprint's
+ * `version.json` manifest field-for-field in spirit.
+ */
+export declare const specVersionSchema: v.ObjectSchema<{
+    readonly version: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly generatedAt: v.StringSchema<undefined>;
+    /** sha256 (hex) of the canonical `spec.json` bytes. */
+    readonly hash: v.StringSchema<undefined>;
+    readonly requirements: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly rules: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+}, undefined>;
+export type SpecVersion = v.InferOutput<typeof specVersionSchema>;
+/** Folder, relative to the repo root, that holds the persisted spec. */
+export declare const SPEC_DIR = "spec";
+/** Canonical machine-readable spec file (the SpecDoc tree). */
+export declare const SPEC_JSON_PATH = "spec/spec.json";
+/** High-level overview markdown — the file agents read first. */
+export declare const SPEC_OVERVIEW_PATH = "spec/overview.md";
+/** Domain rules / invariants / constraints markdown. */
+export declare const SPEC_RULES_PATH = "spec/rules.md";
+/** Tiny manifest read for quick staleness checks without parsing the full tree. */
+export declare const SPEC_VERSION_PATH = "spec/version.json";
+/** Sub-folder holding the generated Gherkin `.feature` files (one per group). */
+export declare const SPEC_FEATURES_DIR = "spec/features";
+/** Legacy folder name the spec lived under before the rename; relocated on first run. */
+export declare const LEGACY_SPEC_DIR = "requirements";
+/**
+ * Strictly parse an arbitrary value (e.g. the JSON read from `spec.json`, or a tree
+ * returned by the spec-writer container) into a {@link SpecDoc}, enforcing the exact
+ * schema shape. Throws on any shape violation, so a bad payload can never be
+ * ingested. Use it at every trust boundary that ingests a spec.
+ */
+export declare function parseSpecDoc(value: unknown): SpecDoc;
+/** Non-throwing variant: returns the parsed doc or `undefined` when invalid. */
+export declare function safeParseSpecDoc(value: unknown): SpecDoc | undefined;
+/**
+ * Render a {@link SpecDoc} as readable markdown for HUMAN + COMPANION review.
+ *
+ * The spec-writer is a container agent: it emits the spec as JSON, renders the
+ * in-repo files and commits them, then its raw `summary` (a fragment of the Pi
+ * transcript) is all that survives on the step. Grading that transcript instead of
+ * the document is what made the spec-companion declare every pass "unreviewable" and
+ * loop the producer to its cap. This renders the actual tree — every group, its
+ * requirements (statement / kind / priority) and their Given/When/Then acceptance
+ * criteria, plus the cross-cutting rules — so the reviewer (and the SPA reader, and
+ * downstream steps) see the spec itself, not the agent's chatter. Deterministic and
+ * dependency-free so it is safe to call at the ingest trust boundary.
+ */
+export declare function renderSpecForReview(spec: SpecDoc): string;
+//# sourceMappingURL=spec.d.ts.map

package/dist/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AA2B5B,wDAAwD;AACxD,eAAO,MAAM,yBAAyB,0DAA0C,CAAA;AAChF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAEjF,uFAAuF;AACvF,eAAO,MAAM,qBAAqB,4EAA4D,CAAA;AAC9F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;;;;;aAOpC,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAEjF,2FAA2F;AAC3F,eAAO,MAAM,qBAAqB;IAChC,gDAAgD;;IAEhD,sBAAsB;;IAEtB,6DAA6D;;;;IAI7D,wFAAwF;;IAExF,0FAA0F;;;;;;;aAE1F,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;IAE3B,sEAAsE;;IAEtE,sCAAsC;;;aAGtC,CAAA;AACF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAE/D,8FAA8F;AAC9F,eAAO,MAAM,sBAAsB;;;;QA/BjC,gDAAgD;;QAEhD,sBAAsB;;QAEtB,6DAA6D;;;;QAI7D,wFAAwF;;QAExF,0FAA0F;;;;;;;;aAyB1F,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E,+FAA+F;AAC/F,eAAO,MAAM,aAAa;IACxB,wDAAwD;;IAExD,4DAA4D;;IAE5D,kFAAkF;;;;;YA5ClF,gDAAgD;;YAEhD,sBAAsB;;YAEtB,6DAA6D;;;;YAI7D,wFAAwF;;YAExF,0FAA0F;;;;;;;;;IAoC1F,6DAA6D;;;QAxB7D,sEAAsE;;QAEtE,sCAAsC;;;;aAwBtC,CAAA;AACF,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,aAAa,CAAC,CAAA;AAEzD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB;;;IAG5B,uDAAuD;;;;aAIvD,CAAA;AACF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAOjE,wEAAwE;AACxE,eAAO,MAAM,QAAQ,SAAS,CAAA;AAC9B,+DAA+D;AAC/D,eAAO,MAAM,cAAc,mBAA0B,CAAA;AACrD,iEAAiE;AACjE,eAAO,MAAM,kBAAkB,qBAA4B,CAAA;AAC3D,wDAAwD;AACxD,eAAO,MAAM,eAAe,kBAAyB,CAAA;AACrD,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,sBAA6B,CAAA;AAC3D,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,kBAAyB,CAAA;AAEvD,yFAAyF;AACzF,eAAO,MAAM,eAAe,iBAAiB,CAAA;AAE7C;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpD;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAGpE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAuBzD"}

package/dist/spec.js

@@ -0,0 +1,173 @@
+import * as v from 'valibot';
+// ---------------------------------------------------------------------------
+// Unified in-repo SPECIFICATION artifact (prescriptive, service-level).
+//
+// This is the durable PRESCRIPTIVE spec for a whole service, persisted in the
+// service's own GitHub repo under `spec/` and aggregated across every task. It is
+// the mirror image of the blueprint: a blueprint is DESCRIPTIVE ("what the code
+// is"), this spec is PRESCRIPTIVE ("what must be true"). The canonical,
+// machine-readable file is `spec.json` (a SpecDoc); the markdown files
+// (`overview.md`, `rules.md`) and the Gherkin `features/*.feature` files are
+// deterministic renderings of the same tree. Every agent reads it as context, and
+// its acceptance criteria seed the test scenarios.
+//
+// Naming note: this "spec" family is distinct from the transient, per-block
+// "requirements" CONTEXT review (see `requirements.ts`), which clarifies the
+// linked-prose brief before work starts. A spec legitimately *contains*
+// requirements, domain rules and acceptance criteria, so those inner item types
+// keep their names.
+// ---------------------------------------------------------------------------
+const requirementIdField = v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(200));
+const reqNameField = v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(120));
+const reqSummaryField = v.pipe(v.string(), v.maxLength(2000));
+const reqStatementField = v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(4000));
+const blockIdField = v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(200));
+/** MoSCoW priority — how essential a requirement is. */
+export const requirementPrioritySchema = v.picklist(['must', 'should', 'could']);
+/** Whether a requirement is a behaviour, a quality attribute, or a hard constraint. */
+export const requirementKindSchema = v.picklist(['functional', 'nonfunctional', 'constraint']);
+/**
+ * A single acceptance criterion in structured Given/When/Then form — the seed for
+ * one Gherkin `Scenario`. Kept structured (not prose) so the harness can render it
+ * mechanically and deterministically into a `.feature` file.
+ */
+export const acceptanceCriterionSchema = v.object({
+    id: requirementIdField,
+    given: v.pipe(v.string(), v.maxLength(2000)),
+    when: v.pipe(v.string(), v.maxLength(2000)),
+    // The Gherkin "Then" clause. Named `outcome` (not `then`) so the object is never
+    // accidentally thenable — an object with a `then` member misbehaves under `await`.
+    outcome: v.pipe(v.string(), v.maxLength(2000)),
+});
+/** A single prescriptive requirement, traceable back to the board task(s) it came from. */
+export const requirementItemSchema = v.object({
+    /** Stable slug, e.g. `req-login-rate-limit`. */
+    id: requirementIdField,
+    /** Short headline. */
+    title: reqNameField,
+    /** The requirement itself, as `The system SHALL …` prose. */
+    statement: reqStatementField,
+    kind: requirementKindSchema,
+    priority: requirementPrioritySchema,
+    /** Ids of the board task/block(s) this requirement was aggregated from (provenance). */
+    sourceBlockIds: v.optional(v.array(blockIdField), []),
+    /** Structured acceptance criteria → the seed for this requirement's Gherkin scenarios. */
+    acceptance: v.optional(v.array(acceptanceCriterionSchema), []),
+});
+/**
+ * A cross-cutting domain rule / invariant / constraint — prescriptive, but not tied
+ * to a single capability. Unified into THIS document (not a separate `domain/`
+ * artifact) because rules share the spec's lifecycle; rendered to `rules.md`.
+ */
+export const domainRuleSchema = v.object({
+    id: requirementIdField,
+    /** The invariant, e.g. `An order may never have a negative total.` */
+    rule: reqStatementField,
+    /** Why the rule exists (optional). */
+    rationale: v.optional(reqSummaryField, ''),
+    sourceBlockIds: v.optional(v.array(blockIdField), []),
+});
+/** A grouping of related requirements (a capability / feature area ≈ one `.feature` file). */
+export const requirementGroupSchema = v.object({
+    name: reqNameField,
+    summary: v.optional(reqSummaryField, ''),
+    requirements: v.optional(v.array(requirementItemSchema), []),
+});
+/** The unified, prescriptive specification document for one service (the `spec.json` tree). */
+export const specDocSchema = v.object({
+    /** Service / frame name (defaults to the repo name). */
+    service: reqNameField,
+    /** One-paragraph product intent for the service overall. */
+    summary: v.optional(reqSummaryField, ''),
+    /** Requirements grouped by capability; each group renders one `.feature` file. */
+    groups: v.optional(v.array(requirementGroupSchema), []),
+    /** Cross-cutting domain rules / invariants / constraints. */
+    rules: v.optional(v.array(domainRuleSchema), []),
+});
+/**
+ * The lightweight `version.json` manifest committed alongside the spec. It carries a
+ * monotonic version counter, the generation timestamp, a content hash of the
+ * canonical tree, and the requirement/rule counts — so staleness checks are a tiny
+ * read rather than a full parse of `spec.json`. Mirrors the blueprint's
+ * `version.json` manifest field-for-field in spirit.
+ */
+export const specVersionSchema = v.object({
+    version: v.pipe(v.number(), v.integer(), v.minValue(0)),
+    generatedAt: v.string(),
+    /** sha256 (hex) of the canonical `spec.json` bytes. */
+    hash: v.string(),
+    requirements: v.pipe(v.number(), v.integer(), v.minValue(0)),
+    rules: v.pipe(v.number(), v.integer(), v.minValue(0)),
+});
+// ---- In-repo spec artifact paths ------------------------------------------
+// The folder + file layout, the prescriptive sibling of `blueprints/`. The
+// canonical machine-readable file is `spec.json`; the markdown and feature files
+// are deterministic renderings of the same tree.
+/** Folder, relative to the repo root, that holds the persisted spec. */
+export const SPEC_DIR = 'spec';
+/** Canonical machine-readable spec file (the SpecDoc tree). */
+export const SPEC_JSON_PATH = `${SPEC_DIR}/spec.json`;
+/** High-level overview markdown — the file agents read first. */
+export const SPEC_OVERVIEW_PATH = `${SPEC_DIR}/overview.md`;
+/** Domain rules / invariants / constraints markdown. */
+export const SPEC_RULES_PATH = `${SPEC_DIR}/rules.md`;
+/** Tiny manifest read for quick staleness checks without parsing the full tree. */
+export const SPEC_VERSION_PATH = `${SPEC_DIR}/version.json`;
+/** Sub-folder holding the generated Gherkin `.feature` files (one per group). */
+export const SPEC_FEATURES_DIR = `${SPEC_DIR}/features`;
+/** Legacy folder name the spec lived under before the rename; relocated on first run. */
+export const LEGACY_SPEC_DIR = 'requirements';
+/**
+ * Strictly parse an arbitrary value (e.g. the JSON read from `spec.json`, or a tree
+ * returned by the spec-writer container) into a {@link SpecDoc}, enforcing the exact
+ * schema shape. Throws on any shape violation, so a bad payload can never be
+ * ingested. Use it at every trust boundary that ingests a spec.
+ */
+export function parseSpecDoc(value) {
+    return v.parse(specDocSchema, value);
+}
+/** Non-throwing variant: returns the parsed doc or `undefined` when invalid. */
+export function safeParseSpecDoc(value) {
+    const result = v.safeParse(specDocSchema, value);
+    return result.success ? result.output : undefined;
+}
+/**
+ * Render a {@link SpecDoc} as readable markdown for HUMAN + COMPANION review.
+ *
+ * The spec-writer is a container agent: it emits the spec as JSON, renders the
+ * in-repo files and commits them, then its raw `summary` (a fragment of the Pi
+ * transcript) is all that survives on the step. Grading that transcript instead of
+ * the document is what made the spec-companion declare every pass "unreviewable" and
+ * loop the producer to its cap. This renders the actual tree — every group, its
+ * requirements (statement / kind / priority) and their Given/When/Then acceptance
+ * criteria, plus the cross-cutting rules — so the reviewer (and the SPA reader, and
+ * downstream steps) see the spec itself, not the agent's chatter. Deterministic and
+ * dependency-free so it is safe to call at the ingest trust boundary.
+ */
+export function renderSpecForReview(spec) {
+    const lines = [`# Specification: ${spec.service}`];
+    if (spec.summary)
+        lines.push('', spec.summary);
+    for (const group of spec.groups ?? []) {
+        lines.push('', `## ${group.name}`);
+        if (group.summary)
+            lines.push('', group.summary);
+        for (const req of group.requirements ?? []) {
+            lines.push('', `### ${req.title} (${req.id})`, '', `- Kind: ${req.kind}`);
+            lines.push(`- Priority: ${req.priority}`);
+            lines.push(`- Statement: ${req.statement}`);
+            for (const ac of req.acceptance ?? []) {
+                lines.push(`  - Acceptance ${ac.id}: GIVEN ${ac.given} WHEN ${ac.when} THEN ${ac.outcome}`);
+            }
+        }
+    }
+    const rules = spec.rules ?? [];
+    if (rules.length) {
+        lines.push('', '## Domain rules');
+        for (const rule of rules) {
+            lines.push(`- ${rule.rule}${rule.rationale ? ` (${rule.rationale})` : ''}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=spec.js.map

package/dist/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,8EAA8E;AAC9E,wEAAwE;AACxE,EAAE;AACF,8EAA8E;AAC9E,kFAAkF;AAClF,gFAAgF;AAChF,wEAAwE;AACxE,uEAAuE;AACvE,6EAA6E;AAC7E,kFAAkF;AAClF,mDAAmD;AACnD,EAAE;AACF,4EAA4E;AAC5E,6EAA6E;AAC7E,wEAAwE;AACxE,gFAAgF;AAChF,oBAAoB;AACpB,8EAA8E;AAE9E,MAAM,kBAAkB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAA;AACzF,MAAM,YAAY,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAA;AACnF,MAAM,eAAe,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAA;AAC7D,MAAM,iBAAiB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAA;AACzF,MAAM,YAAY,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAA;AAEnF,wDAAwD;AACxD,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAA;AAGhF,uFAAuF;AACvF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,YAAY,EAAE,eAAe,EAAE,YAAY,CAAC,CAAC,CAAA;AAG9F;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,EAAE,EAAE,kBAAkB;IACtB,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC3C,iFAAiF;IACjF,mFAAmF;IACnF,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;CAC/C,CAAC,CAAA;AAGF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,gDAAgD;IAChD,EAAE,EAAE,kBAAkB;IACtB,sBAAsB;IACtB,KAAK,EAAE,YAAY;IACnB,6DAA6D;IAC7D,SAAS,EAAE,iBAAiB;IAC5B,IAAI,EAAE,qBAAqB;IAC3B,QAAQ,EAAE,yBAAyB;IACnC,wFAAwF;IACxF,cAAc,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC;IACrD,0FAA0F;IAC1F,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,yBAAyB,CAAC,EAAE,EAAE,CAAC;CAC/D,CAAC,CAAA;AAGF;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,EAAE,EAAE,kBAAkB;IACtB,sEAAsE;IACtE,IAAI,EAAE,iBAAiB;IACvB,sCAAsC;IACtC,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,eAAe,EAAE,EAAE,CAAC;IAC1C,cAAc,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC;CACtD,CAAC,CAAA;AAGF,8FAA8F;AAC9F,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,IAAI,EAAE,YAAY;IAClB,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,eAAe,EAAE,EAAE,CAAC;IACxC,YAAY,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,qBAAqB,CAAC,EAAE,EAAE,CAAC;CAC7D,CAAC,CAAA;AAGF,+FAA+F;AAC/F,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,wDAAwD;IACxD,OAAO,EAAE,YAAY;IACrB,4DAA4D;IAC5D,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,eAAe,EAAE,EAAE,CAAC;IACxC,kFAAkF;IAClF,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,sBAAsB,CAAC,EAAE,EAAE,CAAC;IACvD,6DAA6D;IAC7D,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,EAAE,CAAC;CACjD,CAAC,CAAA;AAGF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACvD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,uDAAuD;IACvD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,YAAY,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC5D,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;CACtD,CAAC,CAAA;AAGF,8EAA8E;AAC9E,2EAA2E;AAC3E,iFAAiF;AACjF,iDAAiD;AAEjD,wEAAwE;AACxE,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAA;AAC9B,+DAA+D;AAC/D,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,QAAQ,YAAY,CAAA;AACrD,iEAAiE;AACjE,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,QAAQ,cAAc,CAAA;AAC3D,wDAAwD;AACxD,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,QAAQ,WAAW,CAAA;AACrD,mFAAmF;AACnF,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,QAAQ,eAAe,CAAA;AAC3D,iFAAiF;AACjF,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,QAAQ,WAAW,CAAA;AAEvD,yFAAyF;AACzF,MAAM,CAAC,MAAM,eAAe,GAAG,cAAc,CAAA;AAE7C;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,CAAC,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,CAAA;AACtC,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,CAAC,aAAa,EAAE,KAAK,CAAC,CAAA;IAChD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAA;AACnD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAa;IAC/C,MAAM,KAAK,GAAa,CAAC,oBAAoB,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;IAC5D,IAAI,IAAI,CAAC,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,CAAA;IAC9C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;QACtC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;QAClC,IAAI,KAAK,CAAC,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;QAChD,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,YAAY,IAAI,EAAE,EAAE,CAAC;YAC3C,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,OAAO,GAAG,CAAC,KAAK,KAAK,GAAG,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,WAAW,GAAG,CAAC,IAAI,EAAE,CAAC,CAAA;YACzE,KAAK,CAAC,IAAI,CAAC,eAAe,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAA;YACzC,KAAK,CAAC,IAAI,CAAC,gBAAgB,GAAG,CAAC,SAAS,EAAE,CAAC,CAAA;YAC3C,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;gBACtC,KAAK,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,KAAK,SAAS,EAAE,CAAC,IAAI,SAAS,EAAE,CAAC,OAAO,EAAE,CAAC,CAAA;YAC7F,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAA;IAC9B,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACjB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,iBAAiB,CAAC,CAAA;QACjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;QAC7E,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC"}

package/dist/tasks.d.ts

@@ -0,0 +1,150 @@
+import * as v from 'valibot';
+/** The external task trackers cat-factory can link to. */
+export declare const taskSourceKindSchema: v.PicklistSchema<["jira", "github"], undefined>;
+export type TaskSourceKind = v.InferOutput<typeof taskSourceKindSchema>;
+/**
+ * Everything the frontend needs to render a source's connect form and import
+ * box without hard-coding any provider specifics.
+ */
+export declare const taskSourceDescriptorSchema: v.ObjectSchema<{
+    readonly source: v.PicklistSchema<["jira", "github"], undefined>;
+    /** Display name, e.g. `Jira`. */
+    readonly label: v.StringSchema<undefined>;
+    /** Lucide icon name for the source. */
+    readonly icon: v.StringSchema<undefined>;
+    /** Credentials required to connect, in display order. */
+    readonly credentialFields: v.ArraySchema<v.ObjectSchema<{
+        readonly key: v.StringSchema<undefined>;
+        readonly label: v.StringSchema<undefined>;
+        readonly help: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly placeholder: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly secret: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /** Label for the "import an issue" input. */
+    readonly refLabel: v.StringSchema<undefined>;
+    /** Placeholder for the "import an issue" input. */
+    readonly refPlaceholder: v.StringSchema<undefined>;
+    /**
+     * Whether this source supports searching its catalogue by title/content (so
+     * the UI offers a search box, not just a paste-a-URL field). Optional for
+     * backward-compatibility; absent is treated as `false`.
+     */
+    readonly searchable: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+}, undefined>;
+export type TaskSourceDescriptor = v.InferOutput<typeof taskSourceDescriptorSchema>;
+/** A workspace's connection to a task source, as exposed to clients (never the credentials). */
+export declare const taskConnectionSchema: v.ObjectSchema<{
+    readonly source: v.PicklistSchema<["jira", "github"], undefined>;
+    /** A human-friendly label for what we're connected to (site URL). */
+    readonly label: v.StringSchema<undefined>;
+    /** When the connection was established (epoch ms). */
+    readonly connectedAt: v.NumberSchema<undefined>;
+}, undefined>;
+export type TaskConnection = v.InferOutput<typeof taskConnectionSchema>;
+/** A single comment on an issue, with its body normalized to Markdown. */
+export declare const taskCommentSchema: v.ObjectSchema<{
+    /** Comment author's display name; '' when unknown. */
+    readonly author: v.StringSchema<undefined>;
+    /** Source-supplied creation timestamp, kept as the source's ISO string. */
+    readonly createdAt: v.StringSchema<undefined>;
+    /** Comment body, normalized to lightweight Markdown. */
+    readonly body: v.StringSchema<undefined>;
+}, undefined>;
+export type TaskComment = v.InferOutput<typeof taskCommentSchema>;
+/** An issue imported from a source, projected locally as a structured record. */
+export declare const sourceTaskSchema: v.ObjectSchema<{
+    readonly source: v.PicklistSchema<["jira", "github"], undefined>;
+    /** The source's canonical key for the issue (e.g. a Jira issue key `PROJ-123`). */
+    readonly externalId: v.StringSchema<undefined>;
+    /** Issue summary / title. */
+    readonly title: v.StringSchema<undefined>;
+    /** Canonical URL of the issue on the source. */
+    readonly url: v.StringSchema<undefined>;
+    /** Workflow status name, e.g. `In Progress`. */
+    readonly status: v.StringSchema<undefined>;
+    /** Issue type name, e.g. `Bug`. */
+    readonly type: v.StringSchema<undefined>;
+    /** Assignee display name, or null when unassigned. */
+    readonly assignee: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** Priority name, or null when none. */
+    readonly priority: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** Issue labels. */
+    readonly labels: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    /** Issue description, normalized to lightweight Markdown. */
+    readonly description: v.StringSchema<undefined>;
+    /** Recent comments, oldest→newest, bodies normalized to Markdown. */
+    readonly comments: v.ArraySchema<v.ObjectSchema<{
+        /** Comment author's display name; '' when unknown. */
+        readonly author: v.StringSchema<undefined>;
+        /** Source-supplied creation timestamp, kept as the source's ISO string. */
+        readonly createdAt: v.StringSchema<undefined>;
+        /** Comment body, normalized to lightweight Markdown. */
+        readonly body: v.StringSchema<undefined>;
+    }, undefined>, undefined>;
+    /** A short plain-text excerpt of the issue (for list/preview rendering). */
+    readonly excerpt: v.StringSchema<undefined>;
+    /** The board block this issue is attached to as context, if any. */
+    readonly linkedBlockId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** When this projection row was last refreshed (epoch ms). */
+    readonly syncedAt: v.NumberSchema<undefined>;
+}, undefined>;
+export type SourceTask = v.InferOutput<typeof sourceTaskSchema>;
+/**
+ * A single hit from searching a tracker. A lean shape (no description/comments)
+ * used to populate a picker: selecting one imports it (by `externalId`) and
+ * links it to a block. Distinct from {@link SourceTask} — a hit is not yet
+ * projected locally, so it carries no `linkedBlockId`/`syncedAt`.
+ */
+export declare const taskSearchResultSchema: v.ObjectSchema<{
+    readonly source: v.PicklistSchema<["jira", "github"], undefined>;
+    /** The source's canonical key for the issue (re-usable as an import ref). */
+    readonly externalId: v.StringSchema<undefined>;
+    readonly title: v.StringSchema<undefined>;
+    /** Canonical URL of the issue on the source. */
+    readonly url: v.StringSchema<undefined>;
+    /** Workflow status name, e.g. `In Progress` (may be empty). */
+    readonly status: v.StringSchema<undefined>;
+    /** A short plain-text excerpt for the result row (may be empty). */
+    readonly excerpt: v.StringSchema<undefined>;
+}, undefined>;
+export type TaskSearchResult = v.InferOutput<typeof taskSearchResultSchema>;
+/**
+ * Connect a workspace to a task source. The `credentials` bag is validated by
+ * the target provider (the `:source` is in the path), keeping the wire shape
+ * uniform across providers.
+ */
+export declare const connectTaskSourceSchema: v.ObjectSchema<{
+    readonly credentials: v.RecordSchema<v.StringSchema<undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
+}, undefined>;
+export type ConnectTaskSourceInput = v.InferOutput<typeof connectTaskSourceSchema>;
+/** Import (fetch + persist) an issue by its key or a full issue URL. */
+export declare const importTaskSchema: v.ObjectSchema<{
+    readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+}, undefined>;
+export type ImportTaskInput = v.InferOutput<typeof importTaskSchema>;
+/** Search a tracker's issues by free text (title/content). */
+export declare const searchTasksSchema: v.ObjectSchema<{
+    readonly query: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+}, undefined>;
+export type SearchTasksInput = v.InferOutput<typeof searchTasksSchema>;
+/** Attach an imported issue to a task as extra agent context. */
+export declare const linkTaskSchema: v.ObjectSchema<{
+    readonly source: v.PicklistSchema<["jira", "github"], undefined>;
+    readonly externalId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+    readonly blockId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+}, undefined>;
+export type LinkTaskInput = v.InferOutput<typeof linkTaskSchema>;
+/**
+ * Materialise an imported issue as a new board task (a leaf block) inside a
+ * container (service frame or module), and link the issue to it for context. The
+ * issue must already be imported (its key is `externalId`). The new task's
+ * title/description are seeded from the issue.
+ */
+export declare const createTaskFromIssueSchema: v.ObjectSchema<{
+    readonly source: v.PicklistSchema<["jira", "github"], undefined>;
+    readonly externalId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+    /** The frame or module the new task is created in. */
+    readonly containerId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+}, undefined>;
+export type CreateTaskFromIssueInput = v.InferOutput<typeof createTaskFromIssueSchema>;
+//# sourceMappingURL=tasks.d.ts.map