@gordon.gan/specflow 1.8.0-alpha → 1.8.1-beta

package/dist/core/document/schemas.d.ts

@@ -43,7 +43,6 @@ export declare const ErrorSpecSchema: z.ZodObject<{
     condition: string;
     note?: string | undefined;
 }>;
-export type ErrorSpec = z.infer<typeof ErrorSpecSchema>;
 export declare const InterfaceEntitySchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -218,7 +217,7 @@ export declare const DecisionEntitySchema: z.ZodObject<{
 }>;
 export type DecisionEntity = z.infer<typeof DecisionEntitySchema>;
 export declare const EntitiesSchema: z.ZodObject<{
-    interfaces: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    interfaces: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         name: z.ZodString;
         method: z.ZodEnum<["GET", "POST", "PUT", "PATCH", "DELETE"]>;
@@ -325,8 +324,58 @@ export declare const EntitiesSchema: z.ZodObject<{
             required?: boolean | undefined;
             desc?: string | undefined;
         }[] | undefined;
-    }>, "many">>;
-    tables: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    }>, "many">>, {
+        path: string;
+        id: string;
+        name: string;
+        errors: {
+            status: string;
+            condition: string;
+            note?: string | undefined;
+        }[];
+        method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+        failure_examples: string[];
+        request_fields?: {
+            type: string;
+            name: string;
+            required: boolean;
+            default?: string | undefined;
+            desc?: string | undefined;
+        }[] | undefined;
+        response_fields?: {
+            type: string;
+            name: string;
+            required: boolean;
+            default?: string | undefined;
+            desc?: string | undefined;
+        }[] | undefined;
+    }[], {
+        path: string;
+        id: string;
+        name: string;
+        errors: {
+            status: string;
+            condition: string;
+            note?: string | undefined;
+        }[];
+        method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+        failure_examples: string[];
+        request_fields?: {
+            type: string;
+            name: string;
+            default?: string | undefined;
+            required?: boolean | undefined;
+            desc?: string | undefined;
+        }[] | undefined;
+        response_fields?: {
+            type: string;
+            name: string;
+            default?: string | undefined;
+            required?: boolean | undefined;
+            desc?: string | undefined;
+        }[] | undefined;
+    }[] | undefined>;
+    tables: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         name: z.ZodString;
         ddl: z.ZodString;
@@ -377,8 +426,34 @@ export declare const EntitiesSchema: z.ZodObject<{
         }[] | undefined;
         migration?: string | undefined;
         rollback?: string | undefined;
-    }>, "many">>;
-    decisions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    }>, "many">>, {
+        id: string;
+        name: string;
+        ddl: string;
+        fields?: {
+            type: string;
+            name: string;
+            required: boolean;
+            default?: string | undefined;
+            desc?: string | undefined;
+        }[] | undefined;
+        migration?: string | undefined;
+        rollback?: string | undefined;
+    }[], {
+        id: string;
+        name: string;
+        ddl: string;
+        fields?: {
+            type: string;
+            name: string;
+            default?: string | undefined;
+            required?: boolean | undefined;
+            desc?: string | undefined;
+        }[] | undefined;
+        migration?: string | undefined;
+        rollback?: string | undefined;
+    }[] | undefined>;
+    decisions: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         text: z.ZodString;
     }, "strip", z.ZodTypeAny, {
@@ -387,7 +462,13 @@ export declare const EntitiesSchema: z.ZodObject<{
     }, {
         id: string;
         text: string;
-    }>, "many">>;
+    }>, "many">>, {
+        id: string;
+        text: string;
+    }[], {
+        id: string;
+        text: string;
+    }[] | undefined>;
 }, "strip", z.ZodTypeAny, {
     interfaces: {
         path: string;
@@ -481,14 +562,13 @@ export declare const EntitiesSchema: z.ZodObject<{
 }>;
 export type Entities = z.infer<typeof EntitiesSchema>;
 export declare const OutlinePointKindSchema: z.ZodEnum<["entity", "narrative", "mixed"]>;
-export type OutlinePointKind = z.infer<typeof OutlinePointKindSchema>;
 export declare const OutlinePointSchema: z.ZodObject<{
     id: z.ZodString;
     text: z.ZodString;
     required: z.ZodDefault<z.ZodBoolean>;
     kind: z.ZodDefault<z.ZodEnum<["entity", "narrative", "mixed"]>>;
-    references: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    source_segments: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    references: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodString, "many">>, string[], string[] | undefined>;
+    source_segments: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodString, "many">>, string[], string[] | undefined>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     references: string[];
@@ -513,8 +593,8 @@ export declare const OutlineChapterSchema: z.ZodObject<{
         text: z.ZodString;
         required: z.ZodDefault<z.ZodBoolean>;
         kind: z.ZodDefault<z.ZodEnum<["entity", "narrative", "mixed"]>>;
-        references: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-        source_segments: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        references: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodString, "many">>, string[], string[] | undefined>;
+        source_segments: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodString, "many">>, string[], string[] | undefined>;
     }, "strip", z.ZodTypeAny, {
         id: string;
         references: string[];
@@ -570,7 +650,6 @@ export declare const OutlineEntitySchema: z.ZodObject<{
     frozen: string;
     standalone?: boolean | undefined;
 }>;
-export type OutlineEntity = z.infer<typeof OutlineEntitySchema>;
 export declare const FillOnceSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     input_budget_tokens: z.ZodDefault<z.ZodNumber>;
@@ -581,7 +660,6 @@ export declare const FillOnceSchema: z.ZodObject<{
     enabled?: boolean | undefined;
     input_budget_tokens?: number | undefined;
 }>;
-export type FillOnce = z.infer<typeof FillOnceSchema>;
 export declare const OutlineSchema: z.ZodObject<{
     profile: z.ZodString;
     chapters: z.ZodArray<z.ZodObject<{
@@ -592,8 +670,8 @@ export declare const OutlineSchema: z.ZodObject<{
             text: z.ZodString;
             required: z.ZodDefault<z.ZodBoolean>;
             kind: z.ZodDefault<z.ZodEnum<["entity", "narrative", "mixed"]>>;
-            references: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-            source_segments: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+            references: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodString, "many">>, string[], string[] | undefined>;
+            source_segments: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodString, "many">>, string[], string[] | undefined>;
         }, "strip", z.ZodTypeAny, {
             id: string;
             references: string[];
@@ -635,7 +713,7 @@ export declare const OutlineSchema: z.ZodObject<{
         }[];
         optional?: boolean | undefined;
     }>, "many">;
-    entities: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    entities: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         frozen: z.ZodString;
         standalone: z.ZodDefault<z.ZodBoolean>;
@@ -647,8 +725,16 @@ export declare const OutlineSchema: z.ZodObject<{
         id: string;
         frozen: string;
         standalone?: boolean | undefined;
-    }>, "many">>;
-    decisions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }>, "many">>, {
+        standalone: boolean;
+        id: string;
+        frozen: string;
+    }[], {
+        id: string;
+        frozen: string;
+        standalone?: boolean | undefined;
+    }[] | undefined>;
+    decisions: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodString, "many">>, string[], string[] | undefined>;
     fill_once: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         input_budget_tokens: z.ZodDefault<z.ZodNumber>;
@@ -712,7 +798,6 @@ export declare const OutlineSchema: z.ZodObject<{
 }>;
 export type Outline = z.infer<typeof OutlineSchema>;
 export declare const ConstraintItemKindSchema: z.ZodEnum<["entity", "decision", "point"]>;
-export type ConstraintItemKind = z.infer<typeof ConstraintItemKindSchema>;
 export declare const ConstraintItemSchema: z.ZodObject<{
     kind: z.ZodEnum<["entity", "decision", "point"]>;
     id: z.ZodString;
@@ -731,14 +816,14 @@ export declare const ChapterComponentSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
     when: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, unknown>;
-    depends_on: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    outline_points: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    depends_on: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodString, "many">>, string[], string[] | undefined>;
+    outline_points: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         text: z.ZodString;
         required: z.ZodDefault<z.ZodBoolean>;
         kind: z.ZodDefault<z.ZodEnum<["entity", "narrative", "mixed"]>>;
-        references: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-        source_segments: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        references: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodString, "many">>, string[], string[] | undefined>;
+        source_segments: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodString, "many">>, string[], string[] | undefined>;
     }, "strip", z.ZodTypeAny, {
         id: string;
         references: string[];
@@ -753,10 +838,24 @@ export declare const ChapterComponentSchema: z.ZodObject<{
         kind?: "entity" | "narrative" | "mixed" | undefined;
         required?: boolean | undefined;
         source_segments?: string[] | undefined;
-    }>, "many">>;
+    }>, "many">>, {
+        id: string;
+        references: string[];
+        kind: "entity" | "narrative" | "mixed";
+        required: boolean;
+        text: string;
+        source_segments: string[];
+    }[], {
+        id: string;
+        text: string;
+        references?: string[] | undefined;
+        kind?: "entity" | "narrative" | "mixed" | undefined;
+        required?: boolean | undefined;
+        source_segments?: string[] | undefined;
+    }[] | undefined>;
     entities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     narratives: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
-    gates: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    gates: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodString, "many">>, string[], string[] | undefined>;
     map_prompt: z.ZodOptional<z.ZodString>;
     output_budget_tokens: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
@@ -801,9 +900,10 @@ export declare const ScenarioProfileSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
     required: z.ZodArray<z.ZodString, "many">;
-    optional_candidates: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    forbidden: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    shared: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    optional_candidates: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodString, "many">>, string[], string[] | undefined>;
+    forbidden: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodString, "many">>, string[], string[] | undefined>;
+    shared: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodString, "many">>, string[], string[] | undefined>;
+    appendices: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodEnum<["anti-ai", "handoff"]>, "many">>, ("handoff" | "anti-ai")[], ("handoff" | "anti-ai")[] | undefined>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     name: string;
@@ -811,6 +911,7 @@ export declare const ScenarioProfileSchema: z.ZodObject<{
     optional_candidates: string[];
     forbidden: string[];
     shared: string[];
+    appendices: ("handoff" | "anti-ai")[];
 }, {
     id: string;
     name: string;
@@ -818,10 +919,10 @@ export declare const ScenarioProfileSchema: z.ZodObject<{
     optional_candidates?: string[] | undefined;
     forbidden?: string[] | undefined;
     shared?: string[] | undefined;
+    appendices?: ("handoff" | "anti-ai")[] | undefined;
 }>;
 export type ScenarioProfile = z.infer<typeof ScenarioProfileSchema>;
 export declare const ReviewTargetSchema: z.ZodEnum<["entity", "narrative", "mixed"]>;
-export type ReviewTarget = z.infer<typeof ReviewTargetSchema>;
 export declare const ReviewFindingSchema: z.ZodObject<{
     id: z.ZodString;
     severity: z.ZodEnum<["critical", "important", "minor"]>;
@@ -858,7 +959,7 @@ export declare const ReviewResultSchema: z.ZodObject<{
     reviewer: z.ZodDefault<z.ZodEnum<["ai", "human"]>>;
     verdict: z.ZodEnum<["pass", "fail", "pass_with_waivers"]>;
     summary: z.ZodOptional<z.ZodString>;
-    findings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    findings: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         severity: z.ZodEnum<["critical", "important", "minor"]>;
         category: z.ZodString;
@@ -885,8 +986,26 @@ export declare const ReviewResultSchema: z.ZodObject<{
         target?: "entity" | "narrative" | "mixed" | undefined;
         chapter?: string | undefined;
         waiver_reason?: string | undefined;
-    }>, "many">>;
-    part_hashes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    }>, "many">>, {
+        status: "fixed" | "open" | "waived";
+        message: string;
+        id: string;
+        severity: "critical" | "important" | "minor";
+        target: "entity" | "narrative" | "mixed";
+        category: string;
+        chapter?: string | undefined;
+        waiver_reason?: string | undefined;
+    }[], {
+        message: string;
+        id: string;
+        severity: "critical" | "important" | "minor";
+        category: string;
+        status?: "fixed" | "open" | "waived" | undefined;
+        target?: "entity" | "narrative" | "mixed" | undefined;
+        chapter?: string | undefined;
+        waiver_reason?: string | undefined;
+    }[] | undefined>;
+    part_hashes: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         sha256: z.ZodString;
     }, "strip", z.ZodTypeAny, {
@@ -895,7 +1014,33 @@ export declare const ReviewResultSchema: z.ZodObject<{
     }, {
         id: string;
         sha256: string;
-    }>, "many">>;
+    }>, "many">>, {
+        id: string;
+        sha256: string;
+    }[], {
+        id: string;
+        sha256: string;
+    }[] | undefined>;
+    /** decision 9 · tamper semantics: chapters the ENGINE legitimately changed after the review
+     *  snapshot (entity refill / narrative fix notes). The tamper check exempts these from the
+     *  post-review "stale" verdict — every other chapter must still match the reviewer-time
+     *  `part_hashes` snapshot. */
+    post_review_repairs: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodObject<{
+        chapter: z.ZodString;
+        at: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        at: string;
+        chapter: string;
+    }, {
+        at: string;
+        chapter: string;
+    }>, "many">>, {
+        at: string;
+        chapter: string;
+    }[], {
+        at: string;
+        chapter: string;
+    }[] | undefined>;
 }, "strip", z.ZodTypeAny, {
     schema: "specflow.document.review/v1";
     change: string;
@@ -916,6 +1061,10 @@ export declare const ReviewResultSchema: z.ZodObject<{
         id: string;
         sha256: string;
     }[];
+    post_review_repairs: {
+        at: string;
+        chapter: string;
+    }[];
     summary?: string | undefined;
 }, {
     schema: "specflow.document.review/v1";
@@ -938,11 +1087,16 @@ export declare const ReviewResultSchema: z.ZodObject<{
         id: string;
         sha256: string;
     }[] | undefined;
+    post_review_repairs?: {
+        at: string;
+        chapter: string;
+    }[] | undefined;
 }>;
 export type ReviewResult = z.infer<typeof ReviewResultSchema>;
 export declare function parseReviewResult(raw: unknown): ReviewResult;
 export declare function parseInterfaceEntity(raw: unknown): InterfaceEntity;
 export declare function parseTableEntity(raw: unknown): TableEntity;
+export declare function parseDecisionEntity(raw: unknown): DecisionEntity;
 export declare function parseEntities(raw: unknown): Entities;
 export declare function parseOutline(raw: unknown): Outline;
 export declare function parseChapterComponent(raw: unknown): ChapterComponent;

package/dist/core/document/schemas.js

@@ -10,6 +10,9 @@
  *  - Outline is the two-pass core IR (replaces ACP index.yaml/parts_order)
  */
 import { z } from 'zod';
+// ============= 通用归一化（P2） =============
+/** 把显式 null 归一为 undefined，使 `.default([])` 对 null 与缺键行为一致（zod v3 默认不处理 null）。 */
+const nullish = (schema) => z.preprocess((v) => (v === null ? undefined : v), schema);
 // ============= Field-level contract primitives =============
 export const FieldSchema = z.object({
     name: z.string().min(1),
@@ -25,7 +28,7 @@ export const ErrorSpecSchema = z.object({
 });
 // ============= Contract entities =============
 export const InterfaceEntitySchema = z.object({
-    id: z.string().min(1), // stable id, e.g. "I1"
+    id: z.string().trim().min(1), // stable id, e.g. "I1"
     name: z.string().min(1), // e.g. "SubmitStepResult"
     method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']),
     path: z.string().min(1),
@@ -35,7 +38,7 @@ export const InterfaceEntitySchema = z.object({
     failure_examples: z.array(z.string()).min(1), // G2 hard gate
 });
 export const TableEntitySchema = z.object({
-    id: z.string().min(1), // stable id, e.g. "T1"
+    id: z.string().trim().min(1), // stable id, e.g. "T1"
     name: z.string().min(1),
     ddl: z.string().min(1),
     fields: z.array(FieldSchema).optional(),
@@ -43,32 +46,33 @@ export const TableEntitySchema = z.object({
     rollback: z.string().optional(), // G4: rollback compat
 });
 export const DecisionEntitySchema = z.object({
-    id: z.string().min(1), // e.g. "D1"
+    id: z.string().trim().min(1), // e.g. "D1"
     text: z.string().min(1),
 });
 export const EntitiesSchema = z.object({
-    interfaces: z.array(InterfaceEntitySchema).default([]),
-    tables: z.array(TableEntitySchema).default([]),
-    decisions: z.array(DecisionEntitySchema).default([]),
+    interfaces: nullish(z.array(InterfaceEntitySchema).default([])),
+    tables: nullish(z.array(TableEntitySchema).default([])),
+    decisions: nullish(z.array(DecisionEntitySchema).default([])),
 });
 // ============= Outline (two-pass core IR, decision 6/8/9) =============
 export const OutlinePointKindSchema = z.enum(['entity', 'narrative', 'mixed']);
 export const OutlinePointSchema = z.object({
-    id: z.string().min(1),
+    id: z.string().trim().min(1),
     text: z.string().min(1),
     required: z.boolean().default(true),
     kind: OutlinePointKindSchema.default('mixed'), // decision 9: coverage channel
-    references: z.array(z.string()).default([]), // decision 8: entity ids (full contract injection)
-    source_segments: z.array(z.string()).default([]), // decision 9: original input segment ids
+    references: nullish(z.array(z.string()).default([])), // decision 8: entity ids (full contract injection)
+    source_segments: nullish(z.array(z.string()).default([])), // decision 9: original input segment ids
 });
 export const OutlineChapterSchema = z.object({
-    id: z.string().min(1),
+    // 白名单字符集与 paths.ts CHAPTER_ID_RE 一致：拒绝路径分隔符/`..`/空串（防路径穿越）
+    id: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/, 'chapter id must be a safe identifier'),
     title: z.string().min(1),
     points: z.array(OutlinePointSchema).min(1),
     optional: z.boolean().default(false),
 });
 export const OutlineEntitySchema = z.object({
-    id: z.string().min(1),
+    id: z.string().trim().min(1),
     frozen: z.string().min(1), // frozen name, must not drift
     standalone: z.boolean().default(false), // decision 9: referenced by decisions only, no contract injection
 });
@@ -79,43 +83,44 @@ export const FillOnceSchema = z.object({
 export const OutlineSchema = z.object({
     profile: z.string().min(1),
     chapters: z.array(OutlineChapterSchema).min(1), // order = render order
-    entities: z.array(OutlineEntitySchema).default([]),
-    decisions: z.array(z.string()).default([]),
+    entities: nullish(z.array(OutlineEntitySchema).default([])),
+    decisions: nullish(z.array(z.string()).default([])),
     fill_once: FillOnceSchema.optional(),
 });
 // ============= Constraint list (decision 8 · P1-D) =============
 export const ConstraintItemKindSchema = z.enum(['entity', 'decision', 'point']);
 export const ConstraintItemSchema = z.object({
     kind: ConstraintItemKindSchema,
-    id: z.string().min(1),
+    id: z.string().trim().min(1),
     label: z.string().min(1), // one-line label for digest prompt
 });
 // ============= Chapter component (reusable) =============
 export const ChapterComponentSchema = z.object({
-    id: z.string().min(1),
+    id: z.string().trim().min(1),
     title: z.string().min(1),
-    when: z.preprocess((v) => (v === null || v === '' ? undefined : v), z.string().optional()), // condition DSL: input.<feature> && / || / !
-    depends_on: z.array(z.string()).default([]),
-    outline_points: z.array(OutlinePointSchema).default([]), // candidate points (Pass 1 reference)
+    when: z.preprocess((v) => (typeof v === 'string' ? (v.trim() === '' ? undefined : v.trim()) : v === null ? undefined : v), z.string().optional()), // condition DSL: input.<feature> && / || / !
+    depends_on: nullish(z.array(z.string()).default([])),
+    outline_points: nullish(z.array(OutlinePointSchema).default([])), // candidate points (Pass 1 reference)
     entities: z.record(z.any()).optional(), // chapter entity schema description
     narratives: z.record(z.any()).optional(),
-    gates: z.array(z.string()).default([]),
+    gates: nullish(z.array(z.string()).default([])),
     map_prompt: z.string().optional(),
     output_budget_tokens: z.number().int().positive().optional(), // per-chapter output cap
 });
 // ============= Scenario profile (three-way classification, decision 8 · P1-J) =============
 export const ScenarioProfileSchema = z.object({
-    id: z.string().min(1),
+    id: z.string().trim().min(1),
     name: z.string().min(1),
     required: z.array(z.string()).min(1), // must be included by outline
-    optional_candidates: z.array(z.string()).default([]), // LLM may choose (subject to when)
-    forbidden: z.array(z.string()).default([]), // never appear in this scenario
-    shared: z.array(z.string()).default([]), // global chapters allowed in dependency closure
+    optional_candidates: nullish(z.array(z.string()).default([])), // LLM may choose (subject to when)
+    forbidden: nullish(z.array(z.string()).default([])), // never appear in this scenario
+    shared: nullish(z.array(z.string()).default([])), // global chapters allowed in dependency closure
+    appendices: nullish(z.array(z.enum(['anti-ai', 'handoff'])).default([])), // §7.2: rendered 附录 B/C
 });
 // ============= Review (decision 9 · target + max_rounds) =============
 export const ReviewTargetSchema = z.enum(['entity', 'narrative', 'mixed']);
 export const ReviewFindingSchema = z.object({
-    id: z.string().min(1),
+    id: z.string().trim().min(1),
     severity: z.enum(['critical', 'important', 'minor']),
     category: z.string().min(1),
     message: z.string().min(1),
@@ -131,8 +136,13 @@ export const ReviewResultSchema = z.object({
     reviewer: z.enum(['ai', 'human']).default('ai'),
     verdict: z.enum(['pass', 'fail', 'pass_with_waivers']),
     summary: z.string().optional(),
-    findings: z.array(ReviewFindingSchema).default([]),
-    part_hashes: z.array(z.object({ id: z.string(), sha256: z.string().min(64).max(64) })).default([]),
+    findings: nullish(z.array(ReviewFindingSchema).default([])),
+    part_hashes: nullish(z.array(z.object({ id: z.string().trim().min(1), sha256: z.string().regex(/^[a-f0-9]{64}$/i, 'sha256 must be 64 hex chars') })).default([])),
+    /** decision 9 · tamper semantics: chapters the ENGINE legitimately changed after the review
+     *  snapshot (entity refill / narrative fix notes). The tamper check exempts these from the
+     *  post-review "stale" verdict — every other chapter must still match the reviewer-time
+     *  `part_hashes` snapshot. */
+    post_review_repairs: nullish(z.array(z.object({ chapter: z.string().min(1), at: z.string().min(1) })).default([])),
 });
 export function parseReviewResult(raw) {
     return ReviewResultSchema.parse(raw);
@@ -144,6 +154,9 @@ export function parseInterfaceEntity(raw) {
 export function parseTableEntity(raw) {
     return TableEntitySchema.parse(raw);
 }
+export function parseDecisionEntity(raw) {
+    return DecisionEntitySchema.parse(raw);
+}
 export function parseEntities(raw) {
     return EntitiesSchema.parse(raw);
 }

package/dist/integrations/shared/capability-evidence.js

@@ -7,10 +7,10 @@ const MARKER_RULES = [
     { id: 'sub.propose.first_iteration', skill: 'propose', includes: ['first-iteration deep-analysis pass'] },
     { id: 'sub.refine.multi_round', skill: 'refine', includes: ['auto-multi-round loop', '## LOOP (Stages 2-4)'] },
     { id: 'sub.refine.challenge_scope', skill: 'refine', includes: ['Challenge Behaviors #3 and #4', 'question scope'] },
-    { id: 'sub.document.two_pass_outline', skill: 'document', includes: ['outline', 'Pass 1'] },
-    { id: 'sub.document.fill_in_by_points', skill: 'document', includes: ['填空', '要点'] },
-    { id: 'sub.document.contract_injection', skill: 'document', includes: ['契约注入', 'references'] },
-    { id: 'sub.document.coverage_check', skill: 'document', includes: ['覆盖', 'coverage'] },
+    { id: 'sub.techdoc.two_pass_outline', skill: 'techdoc', includes: ['outline', 'Pass 1'] },
+    { id: 'sub.techdoc.fill_in_by_points', skill: 'techdoc', includes: ['填空', '要点'] },
+    { id: 'sub.techdoc.contract_injection', skill: 'techdoc', includes: ['契约注入', 'references'] },
+    { id: 'sub.techdoc.coverage_check', skill: 'techdoc', includes: ['覆盖', 'coverage'] },
     { id: 'sub.apply.phase_a', skill: 'apply', includes: ['## Phase A: Task Rewrite'] },
     { id: 'sub.apply.phase_b', skill: 'apply', includes: ['## Phase B: Subagent TDD Execution'] },
     { id: 'sub.apply.gap_detection', skill: 'apply', includes: ['Gap Detection'] },

package/dist/integrations/shared/command-catalog.js

@@ -2,7 +2,8 @@ export const COMMAND_CATALOG = [
     { id: 'explore', description: 'Think-before-propose exploration when requirements are fuzzy' },
     { id: 'propose', description: 'Create proposal and spec artifacts for a change' },
     { id: 'refine', description: 'Refine and iterate on spec artifacts' },
-    { id: 'document', description: 'Generate scenario-based solution documents via the Generic LongDoc Engine' },
+    { id: 'techdoc', description: 'Generate scenario-based solution documents via the Generic LongDoc Engine' },
+    { id: 'techdoc-synth', description: 'Synthesize multi-repo four artifacts into ONE cross-repo document (document + synthesize; scene auto-detect when --profile omitted)' },
     { id: 'apply', description: 'Implement tasks from a change spec' },
     { id: 'review', description: 'Review code changes against spec' },
     { id: 'test', description: 'Run tests and verify coverage' },

package/dist/integrations/shared/parity-manifest.js

@@ -13,10 +13,10 @@ export const CAPABILITY_MANIFEST = [
     { id: 'sub.propose.first_iteration', commandId: 'propose', level: 'sub-capability', required: true },
     { id: 'sub.refine.multi_round', commandId: 'refine', level: 'sub-capability', required: true },
     { id: 'sub.refine.challenge_scope', commandId: 'refine', level: 'sub-capability', required: true },
-    { id: 'sub.document.two_pass_outline', commandId: 'document', level: 'sub-capability', required: true },
-    { id: 'sub.document.fill_in_by_points', commandId: 'document', level: 'sub-capability', required: true },
-    { id: 'sub.document.contract_injection', commandId: 'document', level: 'sub-capability', required: true },
-    { id: 'sub.document.coverage_check', commandId: 'document', level: 'sub-capability', required: true },
+    { id: 'sub.techdoc.two_pass_outline', commandId: 'techdoc', level: 'sub-capability', required: true },
+    { id: 'sub.techdoc.fill_in_by_points', commandId: 'techdoc', level: 'sub-capability', required: true },
+    { id: 'sub.techdoc.contract_injection', commandId: 'techdoc', level: 'sub-capability', required: true },
+    { id: 'sub.techdoc.coverage_check', commandId: 'techdoc', level: 'sub-capability', required: true },
     { id: 'sub.apply.phase_a', commandId: 'apply', level: 'sub-capability', required: true },
     { id: 'sub.apply.phase_b', commandId: 'apply', level: 'sub-capability', required: true },
     { id: 'sub.apply.gap_detection', commandId: 'apply', level: 'sub-capability', required: true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.8.0-alpha",
+  "version": "1.8.1-beta",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [
@@ -55,6 +55,7 @@
     "release:major": "npm version major && git push && git push --tags"
   },
   "dependencies": {
+    "@gordon.gan/specflow": "^1.8.0-alpha",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "js-yaml": "^4.1.0",

package/prompts/document/map/acceptance.md

@@ -5,4 +5,5 @@
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
 - 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级

package/prompts/document/map/anti-ai.md

@@ -0,0 +1,29 @@
+# 附录填充：anti-ai（去AI味自检 · 附录 B）
+
+你是方案文档撰写员。为整份方案写「去AI味自检」条目，写入 `appendices/anti-ai.md`。
+
+## 硬规则（frontend-dev-guide §十一 → README §1.6）
+
+1. **至少 3 条**：每条自检对应五维中的一维，格式 `- 维度名：自检陈述`（如 `- 不做决策：明确写了本期不做什么（…），不是只列功能清单`）。
+2. **对着五维写**：
+   | 维度 | 自检问题 | AI 味反例 |
+   |------|---------|----------|
+   | 不做决策 | 明确说了「不做什么」？ | 只列功能清单 |
+   | 数字具体 | 指标/约束具体到数字？ | 「提升体验」 |
+   | 竞品立场 | 与竞品差异有一句话立场？ | 「借鉴头部最佳实践」 |
+   | 此刻合理性 | 为什么现在做？不做会怎样？ | 不解释时机 |
+   | 优先级倾斜 | P0/P1 有倾斜逻辑？ | 全功能同等权重 |
+3. **必须引用本文档的实际内容**：每条自检要能指到正文里的具体段落/数字（如「正文 §Benchmark 给了原始测量值 82ms/320ms，不是只说『更快』」）。禁止写与本文档无关的通用自检。
+4. **诚实**：自检条目是「我确实做到了」的声明，不是愿望清单。没做到的维度不要硬凑，写「本迭代不适用」并说明理由。
+5. **禁止 stub**（TODO/待补充/此处省略）；每条不少于 15 字。
+
+## 输出示例
+
+```markdown
+- 不做决策：明确写了预研不做架构/接口/UI 实现设计（§6.3 分界），不是只列候选功能。
+- 数字具体：benchmark 给出同条件同设备原始测量值（冷启动 82ms vs 320ms），不是「性能大幅提升」。
+- 竞品立场：一句话立场写明「本项目不选 Bun」及原因，不是「借鉴头部最佳实践」。
+- 此刻合理性：说明了本次预研触发点（生态缺口风险），不做会怎样已写（§research）。
+```
+
+> 优先级：项目约定 > SpecFlow guidance > LLM。