@on-par/contracts 0.0.0-stage → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 On PAR Dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @on-par/contracts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared typed seam for the Software Factory packages: engineering-ready issue/epic/story, Gherkin acceptance criteria and the DesignArtifact schema (zod).
+
+Part of [Software Factory](https://github.com/on-par/software-factory), a multi-agent factory that ships verified work autonomously. Most users want the CLI, [`@on-par/factory-cli`](https://www.npmjs.com/package/@on-par/factory-cli); the other packages are its building blocks.
+
+## Documentation
+
+- [README and Quick Start](https://github.com/on-par/software-factory#readme)
+- [Architecture and package graph](https://github.com/on-par/software-factory/blob/main/docs/architecture.md)
+- [Changelog](https://github.com/on-par/software-factory/blob/main/CHANGELOG.md)
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/adr.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+export declare const AdrReferenceDraftSchema: z.ZodObject<{
+    text: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const AdrDraftSchema: z.ZodObject<{
+    title: z.ZodString;
+    context: z.ZodDefault<z.ZodString>;
+    decision: z.ZodDefault<z.ZodString>;
+    consequences: z.ZodDefault<z.ZodString>;
+    status: z.ZodDefault<z.ZodEnum<{
+        accepted: "accepted";
+        proposed: "proposed";
+    }>>;
+    references: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>>, z.ZodTransform<{
+        text: string;
+        url?: string | undefined;
+    }[], {
+        text: string;
+        url?: string | undefined;
+    }[] | null | undefined>>;
+}, z.core.$strip>;
+export type AdrReferenceDraft = z.infer<typeof AdrReferenceDraftSchema>;
+export type AdrDraft = z.infer<typeof AdrDraftSchema>;
+//# sourceMappingURL=adr.d.ts.map

package/dist/adr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adr.d.ts","sourceRoot":"","sources":["../src/adr.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,uBAAuB;;;iBAGlC,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;iBAezB,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/adr.js

@@ -0,0 +1,24 @@
+// src/adr.ts — AdrDraft: a proposed architecture decision. The product proposer exports
+// drafts as Proposed ADR files; the factory's PLAN/SHIP pipeline never records ADRs.
+import { z } from 'zod';
+export const AdrReferenceDraftSchema = z.object({
+    text: z.string().min(1),
+    url: z.string().min(1).optional(),
+});
+export const AdrDraftSchema = z.object({
+    title: z.string().min(1),
+    /** The mandatory 'why' — forces and constraints that drove the decision. */
+    context: z.string().default(''),
+    decision: z.string().default(''),
+    consequences: z.string().default(''),
+    /** Drafts arrive Proposed; the writer promotes them to Accepted. */
+    status: z.enum(['proposed', 'accepted']).default('proposed'),
+    // .nullish() (not .default()) so a bare YAML key with no items — which js-yaml parses
+    // to null, not undefined — still defaults to [] rather than failing the parse. Same
+    // reasoning as DesignArtifactSchema's targetTypes.
+    references: z
+        .array(AdrReferenceDraftSchema)
+        .nullish()
+        .transform((v) => v ?? []),
+});
+//# sourceMappingURL=adr.js.map

package/dist/adr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adr.js","sourceRoot":"","sources":["../src/adr.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,qFAAqF;AACrF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,4EAA4E;IAC5E,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IAC/B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IAChC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IACpC,oEAAoE;IACpE,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IAC5D,sFAAsF;IACtF,oFAAoF;IACpF,mDAAmD;IACnD,UAAU,EAAE,CAAC;SACV,KAAK,CAAC,uBAAuB,CAAC;SAC9B,OAAO,EAAE;SACT,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;CAC7B,CAAC,CAAC"}

package/dist/design.d.ts

@@ -0,0 +1,224 @@
+import { z } from 'zod';
+export declare const VerificationStepSchema: z.ZodObject<{
+    command: z.ZodString;
+    passWhen: z.ZodString;
+}, z.core.$strip>;
+export declare const RejectedApproachSchema: z.ZodObject<{
+    option: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export declare const DesignApproachSchema: z.ZodObject<{
+    chosen: z.ZodString;
+    rejected: z.ZodArray<z.ZodObject<{
+        option: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const TargetTypeSchema: z.ZodObject<{
+    name: z.ZodString;
+    file: z.ZodString;
+    kind: z.ZodDefault<z.ZodEnum<{
+        added: "added";
+        changed: "changed";
+        read: "read";
+    }>>;
+}, z.core.$strip>;
+export declare const SignatureSchema: z.ZodObject<{
+    symbol: z.ZodString;
+    file: z.ZodString;
+    signature: z.ZodString;
+}, z.core.$strip>;
+export declare const CallEdgeSchema: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const BehaviorVerdictSchema: z.ZodEnum<{
+    better: "better";
+    same: "same";
+    unknown: "unknown";
+    worse: "worse";
+}>;
+export declare const BehaviorDeltaRowSchema: z.ZodObject<{
+    input: z.ZodString;
+    branch: z.ZodString;
+    before: z.ZodString;
+    after: z.ZodString;
+    verdict: z.ZodEnum<{
+        better: "better";
+        same: "same";
+        unknown: "unknown";
+        worse: "worse";
+    }>;
+}, z.core.$strip>;
+export declare function coerceListItem(item: unknown): unknown;
+export declare const ExternalListSchema: z.ZodObject<{
+    name: z.ZodString;
+    location: z.ZodString;
+    source: z.ZodString;
+    gaps: z.ZodArray<z.ZodPreprocess<z.ZodString, unknown>>;
+}, z.core.$strip>;
+export declare const EvidenceKindSchema: z.ZodEnum<{
+    command: "command";
+    "fail-to-pass-test": "fail-to-pass-test";
+    none: "none";
+    screenshot: "screenshot";
+}>;
+export declare const FailToPassTestEvidenceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"fail-to-pass-test">;
+    claim: z.ZodString;
+    test: z.ZodString;
+}, z.core.$strip>;
+export declare const CommandEvidenceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"command">;
+    claim: z.ZodString;
+    command: z.ZodString;
+    passWhen: z.ZodString;
+}, z.core.$strip>;
+export declare const ScreenshotEvidenceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"screenshot">;
+    claim: z.ZodString;
+    route: z.ZodString;
+}, z.core.$strip>;
+export declare const NoEvidenceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"none">;
+    claim: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export declare const EvidencePlanEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"fail-to-pass-test">;
+    claim: z.ZodString;
+    test: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"command">;
+    claim: z.ZodString;
+    command: z.ZodString;
+    passWhen: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"screenshot">;
+    claim: z.ZodString;
+    route: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"none">;
+    claim: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>], "kind">;
+export declare const DesignArtifactSchema: z.ZodObject<{
+    restatedProblem: z.ZodString;
+    approach: z.ZodObject<{
+        chosen: z.ZodString;
+        rejected: z.ZodArray<z.ZodObject<{
+            option: z.ZodString;
+            reason: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    interfacesTouched: z.ZodArray<z.ZodPreprocess<z.ZodString, unknown>>;
+    targetTypes: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        file: z.ZodString;
+        kind: z.ZodDefault<z.ZodEnum<{
+            added: "added";
+            changed: "changed";
+            read: "read";
+        }>>;
+    }, z.core.$strip>>>>, z.ZodTransform<{
+        name: string;
+        file: string;
+        kind: "added" | "changed" | "read";
+    }[], {
+        name: string;
+        file: string;
+        kind: "added" | "changed" | "read";
+    }[] | null | undefined>>;
+    signatures: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        symbol: z.ZodString;
+        file: z.ZodString;
+        signature: z.ZodString;
+    }, z.core.$strip>>>>, z.ZodTransform<{
+        symbol: string;
+        file: string;
+        signature: string;
+    }[], {
+        symbol: string;
+        file: string;
+        signature: string;
+    }[] | null | undefined>>;
+    callGraph: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>>, z.ZodTransform<{
+        from: string;
+        to: string;
+        note?: string | undefined;
+    }[], {
+        from: string;
+        to: string;
+        note?: string | undefined;
+    }[] | null | undefined>>;
+    behaviorContract: z.ZodArray<z.ZodPreprocess<z.ZodString, unknown>>;
+    verificationPlan: z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        passWhen: z.ZodString;
+    }, z.core.$strip>>;
+    riskBlastRadius: z.ZodString;
+    openQuestions: z.ZodArray<z.ZodPreprocess<z.ZodString, unknown>>;
+    edgeInputs: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodPreprocess<z.ZodString, unknown>>>, unknown>;
+    behaviorDelta: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        input: z.ZodString;
+        branch: z.ZodString;
+        before: z.ZodString;
+        after: z.ZodString;
+        verdict: z.ZodEnum<{
+            better: "better";
+            same: "same";
+            unknown: "unknown";
+            worse: "worse";
+        }>;
+    }, z.core.$strip>>>, unknown>;
+    externalLists: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        location: z.ZodString;
+        source: z.ZodString;
+        gaps: z.ZodArray<z.ZodPreprocess<z.ZodString, unknown>>;
+    }, z.core.$strip>>>, unknown>;
+    evidencePlan: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"fail-to-pass-test">;
+        claim: z.ZodString;
+        test: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"command">;
+        claim: z.ZodString;
+        command: z.ZodString;
+        passWhen: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"screenshot">;
+        claim: z.ZodString;
+        route: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"none">;
+        claim: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>], "kind">>>, unknown>;
+}, z.core.$strip>;
+export type VerificationStep = z.infer<typeof VerificationStepSchema>;
+export type RejectedApproach = z.infer<typeof RejectedApproachSchema>;
+export type DesignApproach = z.infer<typeof DesignApproachSchema>;
+export type TargetType = z.infer<typeof TargetTypeSchema>;
+export type Signature = z.infer<typeof SignatureSchema>;
+export type CallEdge = z.infer<typeof CallEdgeSchema>;
+export type BehaviorVerdict = z.infer<typeof BehaviorVerdictSchema>;
+export type BehaviorDeltaRow = z.infer<typeof BehaviorDeltaRowSchema>;
+export type ExternalList = z.infer<typeof ExternalListSchema>;
+export type EvidenceKind = z.infer<typeof EvidenceKindSchema>;
+export type FailToPassTestEvidence = z.infer<typeof FailToPassTestEvidenceSchema>;
+export type CommandEvidence = z.infer<typeof CommandEvidenceSchema>;
+export type ScreenshotEvidence = z.infer<typeof ScreenshotEvidenceSchema>;
+export type NoEvidence = z.infer<typeof NoEvidenceSchema>;
+export type EvidencePlanEntry = z.infer<typeof EvidencePlanEntrySchema>;
+export type DesignArtifact = z.infer<typeof DesignArtifactSchema>;
+/** Paths (e.g. 'edgeInputs[11]', 'externalLists[0].gaps[2]') of the raw design's
+ *  string-list items that coerceListItem will rewrite. Non-object input or non-array
+ *  fields yield nothing. */
+export declare function findCoercedDesignItems(design: unknown): string[];
+//# sourceMappingURL=design.d.ts.map

package/dist/design.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"design.d.ts","sourceRoot":"","sources":["../src/design.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,sBAAsB;;;iBAGjC,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;iBAGjC,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;;iBAG/B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;iBAI3B,CAAC;AAEH,eAAO,MAAM,eAAe;;;;iBAI1B,CAAC;AAEH,eAAO,MAAM,cAAc;;;;iBAIzB,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;EAAiD,CAAC;AAEpF,eAAO,MAAM,sBAAsB;;;;;;;;;;;iBAMjC,CAAC;AAKH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAYrD;AAID,eAAO,MAAM,kBAAkB;;;;;iBAK7B,CAAC;AAIH,eAAO,MAAM,kBAAkB;;;;;EAAiE,CAAC;AAEjG,eAAO,MAAM,4BAA4B;;;;iBAIvC,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;iBAKhC,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;iBAInC,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;iBAI3B,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;2BAKlC,CAAC;AAMH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2B/B,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACxD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAClF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC1E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAIlE;;4BAE4B;AAC5B,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,CAmBhE"}

package/dist/design.js

@@ -0,0 +1,154 @@
+// src/design.ts — DesignArtifact: the structured design block PLAN emits and BUILD
+// consumes (originally #422; moved here in #466 so both apps share one definition;
+// deepened in #480).
+import { z } from 'zod';
+export const VerificationStepSchema = z.object({
+    command: z.string().min(1),
+    passWhen: z.string().min(1),
+});
+export const RejectedApproachSchema = z.object({
+    option: z.string().min(1),
+    reason: z.string().min(1),
+});
+export const DesignApproachSchema = z.object({
+    chosen: z.string().min(1),
+    rejected: z.array(RejectedApproachSchema),
+});
+export const TargetTypeSchema = z.object({
+    name: z.string().min(1),
+    file: z.string().min(1),
+    kind: z.enum(['added', 'changed', 'read']).default('changed'),
+});
+export const SignatureSchema = z.object({
+    symbol: z.string().min(1),
+    file: z.string().min(1),
+    signature: z.string().min(1),
+});
+export const CallEdgeSchema = z.object({
+    from: z.string().min(1),
+    to: z.string().min(1),
+    note: z.string().min(1).optional(),
+});
+export const BehaviorVerdictSchema = z.enum(['same', 'better', 'worse', 'unknown']);
+export const BehaviorDeltaRowSchema = z.object({
+    input: z.string().min(1),
+    branch: z.string().min(1),
+    before: z.string().min(1),
+    after: z.string().min(1),
+    verdict: BehaviorVerdictSchema,
+});
+// js-yaml reads an unquoted list item containing ': ' as a one-key map (#2216, #551).
+// Turn it back into the line the model wrote; any other non-string becomes its JSON text,
+// so one bad item never discards the whole artifact.
+export function coerceListItem(item) {
+    if (typeof item === 'string')
+        return item;
+    if (item !== null && typeof item === 'object' && !Array.isArray(item)) {
+        const entries = Object.entries(item);
+        if (entries.length === 1) {
+            const [key, value] = entries[0];
+            if (value === null || value === undefined)
+                return `${key}:`;
+            const text = typeof value === 'object' ? JSON.stringify(value) : String(value);
+            return `${key}: ${text}`;
+        }
+    }
+    return JSON.stringify(item) ?? String(item);
+}
+const stringListItem = z.preprocess(coerceListItem, z.string().min(1));
+export const ExternalListSchema = z.object({
+    name: z.string().min(1),
+    location: z.string().min(1),
+    source: z.string().min(1),
+    gaps: z.array(stringListItem),
+});
+// Evidence per claim (#2257). Each kind requires its own field: fail-to-pass-test needs
+// `test`, command needs `command` + `passWhen`, screenshot needs `route`, none needs `reason`.
+export const EvidenceKindSchema = z.enum(['fail-to-pass-test', 'command', 'screenshot', 'none']);
+export const FailToPassTestEvidenceSchema = z.object({
+    kind: z.literal('fail-to-pass-test'),
+    claim: z.string().min(1),
+    test: z.string().min(1),
+});
+export const CommandEvidenceSchema = z.object({
+    kind: z.literal('command'),
+    claim: z.string().min(1),
+    command: z.string().min(1),
+    passWhen: z.string().min(1),
+});
+export const ScreenshotEvidenceSchema = z.object({
+    kind: z.literal('screenshot'),
+    claim: z.string().min(1),
+    route: z.string().min(1),
+});
+export const NoEvidenceSchema = z.object({
+    kind: z.literal('none'),
+    claim: z.string().min(1),
+    reason: z.string().min(1),
+});
+export const EvidencePlanEntrySchema = z.discriminatedUnion('kind', [
+    FailToPassTestEvidenceSchema,
+    CommandEvidenceSchema,
+    ScreenshotEvidenceSchema,
+    NoEvidenceSchema,
+]);
+// A bare YAML key parses to null, which must not fail the whole parse; and unlike
+// targetTypes the key stays optional in the inferred type (no [] default injected).
+const optionalList = (item) => z.preprocess((v) => v ?? undefined, z.array(item).optional());
+export const DesignArtifactSchema = z.object({
+    restatedProblem: z.string().min(1),
+    approach: DesignApproachSchema,
+    interfacesTouched: z.array(stringListItem),
+    // .nullish() (not .default()) so a bare YAML key with no items — which js-yaml
+    // parses to null, not undefined — still defaults to [] instead of failing the
+    // whole DesignArtifactSchema parse.
+    targetTypes: z
+        .array(TargetTypeSchema)
+        .nullish()
+        .transform((v) => v ?? []),
+    signatures: z
+        .array(SignatureSchema)
+        .nullish()
+        .transform((v) => v ?? []),
+    callGraph: z
+        .array(CallEdgeSchema)
+        .nullish()
+        .transform((v) => v ?? []),
+    behaviorContract: z.array(stringListItem),
+    verificationPlan: z.array(VerificationStepSchema),
+    riskBlastRadius: z.string().min(1),
+    openQuestions: z.array(z.preprocess(coerceListItem, z.string())),
+    edgeInputs: optionalList(stringListItem),
+    behaviorDelta: optionalList(BehaviorDeltaRowSchema),
+    externalLists: optionalList(ExternalListSchema),
+    evidencePlan: optionalList(EvidencePlanEntrySchema),
+});
+const STRING_LIST_FIELDS = ['interfacesTouched', 'behaviorContract', 'openQuestions', 'edgeInputs'];
+/** Paths (e.g. 'edgeInputs[11]', 'externalLists[0].gaps[2]') of the raw design's
+ *  string-list items that coerceListItem will rewrite. Non-object input or non-array
+ *  fields yield nothing. */
+export function findCoercedDesignItems(design) {
+    if (typeof design !== 'object' || design === null)
+        return [];
+    const d = design;
+    const paths = [];
+    const walk = (list, prefix) => {
+        if (!Array.isArray(list))
+            return;
+        list.forEach((item, i) => {
+            if (typeof item !== 'string')
+                paths.push(`${prefix}[${i}]`);
+        });
+    };
+    for (const field of STRING_LIST_FIELDS)
+        walk(d[field], field);
+    if (Array.isArray(d.externalLists)) {
+        d.externalLists.forEach((row, i) => {
+            if (typeof row === 'object' && row !== null) {
+                walk(row.gaps, `externalLists[${i}].gaps`);
+            }
+        });
+    }
+    return paths;
+}
+//# sourceMappingURL=design.js.map

package/dist/design.js.map

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

package/dist/gherkin.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export declare const AcceptanceCriterionSchema: z.ZodObject<{
+    name: z.ZodString;
+    given: z.ZodArray<z.ZodString>;
+    when: z.ZodArray<z.ZodString>;
+    then: z.ZodArray<z.ZodString>;
+    tracesTo: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type AcceptanceCriterion = z.infer<typeof AcceptanceCriterionSchema>;
+//# sourceMappingURL=gherkin.d.ts.map

package/dist/gherkin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gherkin.d.ts","sourceRoot":"","sources":["../src/gherkin.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,yBAAyB;;;;;;iBAOpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}

package/dist/gherkin.js

@@ -0,0 +1,13 @@
+// src/gherkin.ts — Gherkin acceptance criterion: the executable-shaped "done" statement
+// carried on every engineering-ready story (#466).
+import { z } from 'zod';
+import { TracesToSchema } from './trace.js';
+export const AcceptanceCriterionSchema = z.object({
+    name: z.string().min(1),
+    given: z.array(z.string().min(1)),
+    when: z.array(z.string().min(1)).min(1),
+    then: z.array(z.string().min(1)).min(1),
+    /** Intent statement IDs this criterion verifies (#472). Additive — does not bump the schema version. */
+    tracesTo: TracesToSchema.default([]),
+});
+//# sourceMappingURL=gherkin.js.map

package/dist/gherkin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gherkin.js","sourceRoot":"","sources":["../src/gherkin.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,mDAAmD;AACnD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACvC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACvC,wGAAwG;IACxG,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC;CACrC,CAAC,CAAC"}