@tea-agent/loop-agent 0.39.0-next.23 → 0.39.0-next.25

package/docs/templates/backend-test-dag.json

@@ -145,7 +145,7 @@
 				]
 			},
 			"outputContract": "Write a Chinese, human-readable testcase/md/README.md as the single Markdown-first entry page with Coverage Scope, Coverage Matrix and a machine-parseable module index. Do not write module case cards here; do not execute pytest or modify production code/config.",
-			"subtask_prompt": "This is a required file-generation node. After reading the bounded inputs, immediately use write tools to create testcase/md/README.md. Do not end after analysis or planning, and do not return before a non-empty bounded diff exists. Write ONLY testcase/md/README.md in this node; module case cards are written by downstream sharded nodes.\n\nOutput budget protocol (hard, max output <=16K per turn): Never paste full Matrix, case bodies, or source text into assistant chat. README holds only Scope+Matrix+module index; never inline full case bodies. If a Completeness Gate / OUTPUT_LIMIT_RECOVERY retry is injected, continue only listed target paths.\n\nThe first non-empty response line must be exactly IMPLEMENTATION_OUTCOME: changed after the README has been written, or IMPLEMENTATION_OUTCOME: blocked when precise missing evidence prevents safe generation. already-satisfied is not valid for this node.\n\nRead the upstream environment report. Generate the Markdown-first backend test README under testcase/md/README.md.\n\nWrite human-readable content in Simplified Chinese by default. Keep English only for machine-readable IDs and technical literals such as Case/AC/REQ/BR IDs, HTTP methods, paths, field names, enum values, commands, filenames, code symbols and exact source citations.\n\nCreate testcase/md/README.md as the concise entry page: test objective, target/environment, isolation/cleanup, module summary and a linked case index table with Case ID, Chinese case name, scenario type, endpoint and expected status/result. Avoid repeating every case body in README.\n\nBefore the Coverage Matrix, write a mandatory machine-readable `## Coverage Scope` section in README using exactly `| Field | Value |`, immediately followed by the separator row `|---|---|`, and these six unique rows: `Change Classification`, `Coverage Policy`, `Affected Operations`, `Affected Rule Keys`, `Regression Floor`, `Scope Evidence`. Always set `Change Classification` to `new-operation` and `Coverage Policy` to `full-contract`; do NOT reason about whether operations are new or existing. Cover all in-scope rules from the requirement document at full depth; treat the product requirement as the coverage baseline and use API contract evidence (fields/status/enum/boundary/format) to supplement scenario dimensions. Scope is limited to operations/rules the requirement document (or its referenced API contract) explicitly describes; do not expand to unrelated operations that the requirement does not mention. List affected operations exactly as `METHOD /path`, stable rule keys separated by semicolons, and precise source pointers as Scope Evidence.\n\nCoverage depth is full over the in-scope rules: fully cover every documented status, request/response field rule, requiredness, enum, boundary, format, auth and business state of each affected operation the requirement describes, but do not re-test unrelated operations the requirement does not mention. Inspect shared validator/helper/DTO/query builder evidence and expand Affected Operations when the same affected path can affect them; unresolved impact stays visible as GAP/CONFLICT.\n\nBefore writing cases, build the mandatory machine-readable Coverage Matrix inside `testcase/md/README.md` itself. Its section heading line must be exactly `## Coverage Matrix` with no numeric prefix/suffix; never place the canonical Matrix only in a module file. Use this exact header: `| Rule Key | Priority | Source | Endpoint/Field | Dimension | Rule | Required Test Points | Case IDs | Status |`. Every data row must contain exactly 9 pipe-delimited cells and must never omit `Dimension`; use concise dimensions such as requirement, operation, response-status, requiredness, enum, boundary, format, business-state or error. Use only P0/P1/P2 and COVERED/PARTIAL/GAP/CONFLICT. Use stable `TP-<UPPERCASE-HYPHENATED-ID>` test points separated by semicolons.\n\nEach Rule Key must appear in exactly one Matrix row. Preserve each AC/REQ/BR Rule Key as one row; if one product rule spans multiple dimensions, use a concise composite Dimension in that single row instead of duplicating the key. Derive OpenAPI Rule Keys exactly as the deterministic analyzer does: operation token is `<HTTP-METHOD>-<PATH>` with braces removed and every non-alphanumeric run replaced by a hyphen, uppercase (for example POST `/api/resource-notes` → `POST-API-RESOURCE-NOTES`); response statuses use `API-<OPERATION>-RESPONSE-STATUS`; body/parameter fields use `API-<OPERATION>-<FIELD>-REQUIRED|ENUM|MIN-LENGTH|MAX-LENGTH|MINIMUM|MAXIMUM|PATTERN|FORMAT`. Do not invent aliases such as API-CREATE-FIELDS when a deterministic key applies.\n\nCoverage priority is strict inside the declared scope: P0 product requirements/task hard constraints always remain in scope; P1 exhaustively supplements documented operations, fields, business rules, statuses and errors only for Affected Operations; P2 adds bounded protocol robustness only when it is relevant to the change and does not invent product behavior. Coverage percentages describe the declared affected scope, never whole-API completeness unless every operation is explicitly listed. Conflicts or undefined expectations must stay visible as GAP/CONFLICT with precise source pointers, never guessed.\n\nFor uniqueness/lifecycle rules cover absent, active-existing, deleted-existing, create-delete-recreate, restore-then-recreate and documented scope/case-normalization states. For every enum cover every valid value plus bounded invalid equivalence classes (unknown, case variant, whitespace, empty, null/missing and wrong types as applicable). For every length/number rule cover min-1, min, nominal, max and max+1. For format rules cover each allowed class separately plus a valid mixed value, and representative forbidden classes including uppercase, internal/leading/trailing whitespace, tab/newline, unsupported punctuation, slash, emoji or control characters when the source contract supports that expectation.\n\nMandatory module index: include a `## Module Index` table in README that lists every planned module as a canonical relative link of the exact form `[label](./<stem>.md)` plus a `testcase/md/<stem>.md` path cell, so a downstream deterministic manifest can parse the module list. Group by stable business resource/domain, not by CRUD operation: one resource's list/detail/create/update/delete cases belong in one module such as `resource_notes`; split only when a single module would exceed the per-child 16K output protocol, keep the total module count at the smallest safe value, and never exceed 8 modules. Name each module file with a stable lowercase business stem such as `health` or `resource_notes`. Pure hexadecimal/hash-like opaque stems such as `a401606` or `deadbeef` are forbidden. Do not use priority-only stems `p0`, `p1` or `p2`; Priority belongs only in the Coverage Matrix and never defines module files. Do not use Case-ID-like module filenames such as `BE-HEALTH.md` or `BE-NOTES.md`. The relative link target MUST equal the on-disk filename stem the sharded writer will create. For every automatable case, `自动化映射` must name exactly `testcase/test_<module>.py`, where <module> is that Markdown filename without `.md`, lowercased, with non-alphanumeric characters replaced by underscores. Example: `testcase/md/health.md` → `testcase/test_health.py`; `testcase/md/resource_notes.md` → `testcase/test_resource_notes.py`. Never invent a different pytest path in Markdown than the module stem implies.\n\nScenario Partitions (query/filter axes): for every affected GET/list operation, declare one row per enum or classification axis used for filtering (query/path parameters such as type/status/category). Add a mandatory machine-readable `## Scenario Partitions` section after the Coverage Matrix using exactly `| Partition ID | Operation | Axis | Domain | Required Slots | Expected by Slot | Bind Rule |` with the separator row. Partition ID is a stable `SP-<OPERATION>-<AXIS>` token; Domain must copy the legal values verbatim from the bound OpenAPI enum or requirement sentence (never guess); Required Slots writes `each-value` plus `omitted` only when the parameter is optional; Expected by Slot states the documented expectation per slot kind (`domain-value`, `default-behavior`, `empty-result`/`excluded-result` when documented, or `GAP` when the source does not document the complement expectation — never invent 空列表/400). POST/PUT body field-validation enums stay in the Coverage Matrix as `TP-<FIELD>-ENUM-*` and MUST NOT get a Scenario Partition row. Do not create partitions for axes without a documented legal-value domain. Cross-axis combinations stay as ONE nominal Case; never declare a cross-axis cartesian partition.\n\nBefore finalizing README, calculate the predicted collected-item count as `sum(max(1, number of variant Test Points in each Case))`. If the task declares an item budget, the prediction must not exceed it. Reduce excess only by removing duplicate execution and converting same-request checkpoints to assertions; never drop required rules, boundaries, enums, operation-specific inputs, or business states. Record the prediction in README. Use only environment-supported fixtures/targets/isolation, record evidence gaps in Chinese, and do not emit JSON, pytest, or execute commands.\n\n## Derived task contract: 需求.md\n\n# Backend test\n- AC-001 proof\n\n## Authoritative reference index\n\n[]\n\nFor each index entry, use `readPath` for Pi read-tool calls and copy `path` exactly into Markdown Source References. Bound files under .harness/tasks/<taskId>/source/** are read-only inputs: reading them is allowed even though writing .harness/** is forbidden. Never resolve `path` relative to the repository root, search for substitutes, or fall back to docs/** when a bound read fails.\n\nRead only precise indexed references needed for AC/API/field/rule evidence; references remain authoritative over derived text."
+			"subtask_prompt": "This is a required file-generation node. After reading the bounded inputs, immediately use write tools to create testcase/md/README.md. Do not end after analysis or planning, and do not return before a non-empty bounded diff exists. Write ONLY testcase/md/README.md in this node; module case cards are written by downstream sharded nodes.\n\nOutput budget protocol (hard, max output <=16K per turn): Never paste full Matrix, case bodies, or source text into assistant chat. README holds only Scope+Matrix+module index; never inline full case bodies. If a Completeness Gate / OUTPUT_LIMIT_RECOVERY retry is injected, continue only listed target paths.\n\nThe first non-empty response line must be exactly IMPLEMENTATION_OUTCOME: changed after the README has been written, or IMPLEMENTATION_OUTCOME: blocked when precise missing evidence prevents safe generation. already-satisfied is not valid for this node.\n\nRead the upstream environment report. Generate the Markdown-first backend test README under testcase/md/README.md.\n\nWrite human-readable content in Simplified Chinese by default. Keep English only for machine-readable IDs and technical literals such as Case/AC/REQ/BR IDs, HTTP methods, paths, field names, enum values, commands, filenames, code symbols and exact source citations.\n\nCreate testcase/md/README.md as the concise entry page: test objective, target/environment, isolation/cleanup, module summary and a linked case index table with Case ID, Chinese case name, scenario type, endpoint and expected status/result. Avoid repeating every case body in README.\n\nBefore the Coverage Matrix, write a mandatory machine-readable `## Coverage Scope` section in README using exactly `| Field | Value |`, immediately followed by the separator row `|---|---|`, and these six unique rows: `Change Classification`, `Coverage Policy`, `Affected Operations`, `Affected Rule Keys`, `Regression Floor`, `Scope Evidence`. Always set `Change Classification` to `new-operation` and `Coverage Policy` to `full-contract`; do NOT reason about whether operations are new or existing. Cover all in-scope rules from the requirement document at full depth; treat the product requirement as the coverage baseline and use API contract evidence (fields/status/enum/boundary/format) to supplement scenario dimensions. Scope is limited to operations/rules the requirement document (or its referenced API contract) explicitly describes; do not expand to unrelated operations that the requirement does not mention. List affected operations exactly as `METHOD /path`, stable rule keys separated by semicolons, and precise source pointers as Scope Evidence.\n\nCoverage depth is full over the in-scope rules: fully cover every documented status, request/response field rule, requiredness, enum, boundary, format, auth and business state of each affected operation the requirement describes, but do not re-test unrelated operations the requirement does not mention. Inspect shared validator/helper/DTO/query builder evidence and expand Affected Operations when the same affected path can affect them; unresolved impact stays visible as GAP/CONFLICT.\n\nBefore writing cases, build the mandatory machine-readable Coverage Matrix inside `testcase/md/README.md` itself. Its section heading line must be exactly `## Coverage Matrix` with no numeric prefix/suffix; never place the canonical Matrix only in a module file. Use this exact header: `| Rule Key | Priority | Source | Endpoint/Field | Dimension | Rule | Required Test Points | Case IDs | Status |`. Every data row must contain exactly 9 pipe-delimited cells and must never omit `Dimension`; use concise dimensions such as requirement, operation, response-status, requiredness, enum, boundary, format, business-state or error. Use only P0/P1/P2 and COVERED/PARTIAL/GAP/CONFLICT. Use stable `TP-<UPPERCASE-HYPHENATED-ID>` test points separated by semicolons.\n\nEach Rule Key must appear in exactly one Matrix row. Preserve each AC/REQ/BR Rule Key as one row; if one product rule spans multiple dimensions, use a concise composite Dimension in that single row instead of duplicating the key. Derive OpenAPI Rule Keys exactly as the deterministic analyzer does: operation token is `<HTTP-METHOD>-<PATH>` with braces removed and every non-alphanumeric run replaced by a hyphen, uppercase (for example POST `/api/resource-notes` → `POST-API-RESOURCE-NOTES`); response statuses use `API-<OPERATION>-RESPONSE-STATUS`; body/parameter fields use `API-<OPERATION>-<FIELD>-REQUIRED|ENUM|MIN-LENGTH|MAX-LENGTH|MINIMUM|MAXIMUM|PATTERN|FORMAT`. Do not invent aliases such as API-CREATE-FIELDS when a deterministic key applies.\n\nCoverage priority is strict inside the declared scope: P0 product requirements/task hard constraints always remain in scope; P1 exhaustively supplements documented operations, fields, business rules, statuses and errors only for Affected Operations; P2 adds bounded protocol robustness only when it is relevant to the change and does not invent product behavior. Coverage percentages describe the declared affected scope, never whole-API completeness unless every operation is explicitly listed. Conflicts or undefined expectations must stay visible as GAP/CONFLICT with precise source pointers, never guessed.\n\nFor uniqueness/lifecycle rules cover absent, active-existing, deleted-existing, create-delete-recreate, restore-then-recreate and documented scope/case-normalization states. For every enum cover every valid value plus bounded invalid equivalence classes (unknown, case variant, whitespace, empty, null/missing and wrong types as applicable). For every length/number rule cover min-1, min, nominal, max and max+1. For format rules cover each allowed class separately plus a valid mixed value, and representative forbidden classes including uppercase, internal/leading/trailing whitespace, tab/newline, unsupported punctuation, slash, emoji or control characters when the source contract supports that expectation.\n\nMandatory module index: include a `## Module Index` table in README that lists every planned module as a canonical relative link of the exact form `[label](./<stem>.md)` plus a `testcase/md/<stem>.md` path cell, so a downstream deterministic manifest can parse the module list. Group by stable business resource/domain, not by CRUD operation: one resource's list/detail/create/update/delete cases belong in one module such as `resource_notes`; split only when a single module would exceed the per-child 16K output protocol, keep the total module count at the smallest safe value, and never exceed 8 modules. Name each module file with a stable lowercase business stem such as `health` or `resource_notes`. Pure hexadecimal/hash-like opaque stems such as `a401606` or `deadbeef` are forbidden. Do not use priority-only stems `p0`, `p1` or `p2`; Priority belongs only in the Coverage Matrix and never defines module files. Do not use Case-ID-like module filenames such as `BE-HEALTH.md` or `BE-NOTES.md`. The relative link target MUST equal the on-disk filename stem the sharded writer will create. For every automatable case, `自动化映射` must name exactly `testcase/test_<module>.py`, where <module> is that Markdown filename without `.md`, lowercased, with non-alphanumeric characters replaced by underscores. Example: `testcase/md/health.md` → `testcase/test_health.py`; `testcase/md/resource_notes.md` → `testcase/test_resource_notes.py`. Never invent a different pytest path in Markdown than the module stem implies.\n\nScenario Partitions (query/filter axes): for every affected GET/list operation, declare one row per enum or classification axis used for filtering (query/path parameters such as type/status/category). Add a mandatory machine-readable `## Scenario Partitions` section after the Coverage Matrix using exactly `| Partition ID | Operation | Axis | Domain | Required Slots | Expected by Slot | Bind Rule |` with the separator row. Partition ID is a stable `SP-<OPERATION>-<AXIS>` token; Domain must copy the legal values verbatim from the bound OpenAPI enum or requirement sentence (never guess); Required Slots writes `each-value` plus `omitted` only when the parameter is optional; Expected by Slot states the documented expectation per slot kind (`domain-value`, `default-behavior`, `empty-result`/`excluded-result` when documented, or `GAP` when the source does not document the complement expectation — never invent 空列表/400). POST/PUT body field-validation enums stay in the Coverage Matrix as `TP-<FIELD>-ENUM-*` and MUST NOT get a Scenario Partition row. Do not create partitions for axes without a documented legal-value domain. Only GET/list query or path parameters whose bound source documents a finite enum or classification set may become a Scenario Partition. Do not create partitions for free-form strings, primary keys, required-or-optional-only parameters, or boundary/format-only axes. If an axis has no finite legal-value domain, do not declare a Partition row and do not invent NOT-IN-SET cases. Cross-axis combinations stay as ONE nominal Case; never declare a cross-axis cartesian partition.\n\nBefore finalizing README, calculate the predicted collected-item count as `sum(max(1, number of variant Test Points in each Case))`. If the task declares an item budget, the prediction must not exceed it. Reduce excess only by removing duplicate execution and converting same-request checkpoints to assertions; never drop required rules, boundaries, enums, operation-specific inputs, or business states. Record the prediction in README. Use only environment-supported fixtures/targets/isolation, record evidence gaps in Chinese, and do not emit JSON, pytest, or execute commands.\n\n## Derived task contract: 需求.md\n\n# Backend test\n- AC-001 proof\n\n## Authoritative reference index\n\n[]\n\nFor each index entry, use `readPath` for Pi read-tool calls and copy `path` exactly into Markdown Source References. Bound files under .harness/tasks/<taskId>/source/** are read-only inputs: reading them is allowed even though writing .harness/** is forbidden. Never resolve `path` relative to the repository root, search for substitutes, or fall back to docs/** when a bound read fails.\n\nRead only precise indexed references needed for AC/API/field/rule evidence; references remain authoritative over derived text."
 		},
 		{
 			"id": "materialize-backend-md-module-manifest-shell",
@@ -274,7 +274,7 @@
 				"type": "implementation-outcome-v1"
 			},
 			"outputContract": "First non-empty line is IMPLEMENTATION_OUTCOME: changed|already-satisfied|blocked. Perform exactly one bounded incremental synchronization of testcase/md/** against all bound source references; preserve valid Cases and report a concise summary.",
-			"subtask_prompt": "Perform one gap-targeted synchronization, not a full-suite rewrite or stylistic review. Start from explicit bound source IDs/error codes/DTO fields/normative quoted rules and the README Matrix; open and edit only modules that own a missing or conflicting rule. Preserve unrelated valid modules byte-for-byte and avoid optional wording cleanup.\n\nOutput budget protocol: never dump full Matrix/case bodies into assistant chat. Inspect README first, build a concise target list, then read/write only target modules one file per tool call. Do not traverse every module when the Matrix and source token inventory show no gap; return `already-satisfied`. When adding omitted in-scope cases, keep every required section. Do not bulk-delete in-scope cases to save tokens.\n\nFor every variant Test Point, ensure the Markdown scenario intent is machine-checkable and located inside that same Case body/自动化映射, never in a file-level appendix, implementation-details block, or another Case. Use an exact transport target: `场景意图: <TP-ID>; operation=<METHOD /path>; target=<body.field|query.field|path.field|header.field|request>; intent=<empty|missing|null|min-1|min|max|max+1|pattern-invalid|enum-invalid|wrong-type|nominal-operation|custom-literal:V>; bound=<n optional>; example=<optional>; expectedCode=<optional>`. Never use vague targets such as field=resource/health. Keep pytest params aligned to the exact target. For intent=missing/empty/default-omit, pytest may use `_OMIT` or delete the key; for intent=enum-invalid use a concrete invalid enum literal (for example `UNKNOWN_STATUS`), never `_OMIT`/missing-key; for trim/padded samples use `custom-literal:trim` or a real padded string, not a bare token like `filter-active` when the intent is `custom-literal:ACTIVE`.\n\nTreat the requirement document as the coverage baseline; scope is limited to operations/rules it (or its referenced API contract) describes, and API contract evidence supplements scenario dimensions. For every in-scope operation, check applicable lifecycle/uniqueness states (including deleted-existing when in scope), valid enum values, bounded invalid classes, min-1/min/nominal/max/max+1, allowed/forbidden format classes, required/null/missing/wrong-type semantics, status/error codes, auth and state transitions. Inspect shared validator/helper/DTO/query builder evidence and expand Affected Operations when the same affected path can affect them; unresolved impact stays visible as GAP/CONFLICT. Directly add in-scope omissions; reject scope expansion to operations absent from the requirement document; undefined impact remains GAP/CONFLICT rather than invented behavior.\n\nCheck AC completeness/meaning, endpoint, fields/shape, status/error codes, rules, states, documented boundaries/auth, positive/negative coverage, executable steps and assertable results. Require the exact `## Coverage Scope` Field/Value table with the `|---|---|` separator row, a valid classification-policy pair, non-empty Affected Operations/Rule Keys/Scope Evidence, and the classification-specific Regression Floor. Require the exact unnumbered `## Coverage Matrix` heading in `testcase/md/README.md`, exact headers, exactly 9 cells in every data row (including a non-empty Dimension), deterministic OpenAPI Rule Keys for every in-scope affected operation, exactly one Matrix row per Rule Key (merge multi-dimension product rows), and bidirectional Matrix Rule/Test Point ↔ Case bindings. Never describe affected-scope coverage as whole-API completeness. Every explicit AC ID must appear in at least one Case `验收标准`; every explicit in-scope AC/REQ/BR Rule Key cited by a Case must have exactly one Coverage Matrix row, and no Case may cite a source Rule Key omitted from the Matrix. Every Matrix Case ID must share at least one of that row's Required Test Points and the Case must cite that Rule Key. Perform an explicit execution-redundancy review: merge checkpoint-only parameter rows, repeated default/read-back assertions, DELETE status/body/follow-up-read checks, response schema/Content-Type checks, PUT full-update/timestamp checks, repeated list setup and identical null/empty inputs when endpoint, input partition, precondition state and expected outcome are the same. Preserve separate POST/PUT, boundary, enum, wrong-type, role/tenant and distinct business-state variants. Directly repair malformed headings/rows/keys and binding modes rather than merely commenting on them. Reject avoidable English prose, duplicated bilingual wording, repeated boilerplate, oversized unstructured sections, a `### 操作步骤` section that contains only a table without any numbered executable line, vague results such as ‘符合预期’, Case-ID-like module filenames (for example `BE-HEALTH.md`), dropped exact `### 操作步骤`/`### 预期结果` headings, and missing or drifted script/function mapping where it can be derived.\n\nCorrect testcase/md/** directly: add documented omissions, remove unsupported cases, rename module files to stable lowercase stems when needed, normalize every Case ID to hyphen-separated module segments plus exactly three zero-padded digits (`BE-RESOURCE_NOTES-01` → `BE-RESOURCE-NOTES-001`; `BE-RN-011A` must be renumbered or merged) consistently across headings/index/mappings, fix automation mappings so each automatable case points at `testcase/test_<module>.py` derived from that module filename and declares exactly one primary symbol (evidence-only meta cases may keep `脚本/primary symbol=无` with empty variants), assign every Test Point exactly one of `变体测试点`/`场景断言测试点`/`横切证据测试点`, then perform an exact-set check: each Case's `### 测试点` set must equal (not merely contain) the union of those three binding lists; delete stale/legacy aliases and ensure every binding-list Test Point is present, expand every variant parameter row into its own atomic TP ID, make every non-cross-cutting TP Case-specific and owned by exactly one Case, require every primary symbol to start with the canonical Case prefix, ensure every explicit AC ID appears in an applicable Case `验收标准`, merge execution duplicates, improve navigation/tables/Chinese wording, or record gaps in Chinese. Remove every credential/header value, placeholder, fake token and anti-example from Markdown. Sensitive key names may remain only as a plain list; values must be described as runtime-only and omitted, with no colon/value pair or literal example anywhere, including details blocks and explanatory text. Keep Case IDs, AC/REQ/BR IDs, HTTP methods, paths, fields, enum values, filenames, code symbols and source citations as exact machine-readable identifiers; only normalize Case ID separator/sequence formatting as specified above. Recalculate predicted collected items as `sum(max(1, variant count per Case))`; when the task declares a budget, directly merge redundant journeys/reclassify same-request checkpoints until the prediction is within budget, while preserving all required coverage. The validator accepts Chinese and legacy English section aliases; retain or converge to the Chinese human-readable headings without losing structure.\n\nThis is the single Markdown incremental synchronization round. Read every authoritative reference index entry whose role hints include acceptance-criteria, api-contract, data-contract or business-rule; do not rely on the derived PRD as a complete inventory. Preserve every explicit AC/REQ/BR ID, every documented HTTP/business error code, every DTO/JSON field, enum value, boundary, format, nested shape, transaction/state/idempotency/uniqueness/auth/tenant/cross-field rule. For each natural-language normative business rule preserved as required scope, include its exact source sentence without paraphrase together with source path and line/heading anchor so the deterministic ledger can verify quote/hash provenance. Ensure every Case declares exactly `Payload Contract: none` or the three labels `Payload Required Paths`, `Payload Allowed Paths`, and `Payload Enum`; every label must occupy its own machine-readable list line, and a Case must never concatenate target/setup operations or multiple `Payload Contract` tokens onto one line, and explanatory prose/details must not repeat any `Payload Contract:` token; never infer missing keys or enum values. A target GET/DELETE operation with no request body must remain `Payload Contract: none` even when its setup journey performs POST/PUT with a DTO; setup payloads never redefine the target Case payload contract. Add only missing Matrix rows/Test Points/Cases/assertions or repair exact drift; do not rewrite already-valid unrelated modules. Work gap-targeted: inspect source anchors and affected modules first, leave unrelated valid modules byte-stable, and return `already-satisfied` without restating the full suite when no gap exists.\n\nFor affected API fields, use one valid nominal payload plus atomic required/missing/null/empty/wrong-type, every documented enum value plus bounded invalid classes, documented min-1/min/nominal/max/max+1, formats and nested object/array constraints. Do not generate a Cartesian product or invent undocumented constraints. Do not invent a concrete identifier type when the source only requires presence; for a missing-resource 404 path with unspecified identifier syntax/type, synchronize the Case to a create-delete-derived valid identifier journey rather than an arbitrary UUID/text placeholder.\n\nScenario Partitions synchronization: when README declares `## Scenario Partitions`, verify each declared partition's slots are fully materialized as variant Test Points with exact `TP-<Partition ID>-...` IDs (each-value per Domain value, OMITTED only for optional axes, exactly one NOT-IN-SET with intent=enum-invalid). Directly add missing slot rows/Cases; never delete a declared partition or drop its complement slot to force coverage green. When the bound source does not document the complement expectation, keep the slot with GAP expected instead of guessing. Body-field validation enums (`TP-<FIELD>-ENUM-*`) are NOT partitions — do not add partition rows for them.\n\nBefore returning, verify that every explicit source AC/REQ/BR, error code and strong DTO field token appears in README or an applicable module Case. If a fact cannot be safely automated, retain it as GAP/CONFLICT with its exact source pointer instead of dropping it. Return already-satisfied only when no target file needs an incremental edit.\n\nRead only indexed source paths. Do not scan the repository, modify source/**, generate pytest, execute tests, or emit JSON.\n\n## Derived task contract: 需求.md\n\n# Backend test\n- AC-001 proof\n\n## Authoritative reference index\n\n[]\n\nFor each index entry, use `readPath` for Pi read-tool calls and keep `path` as the exact Markdown Source References citation. Bound files under .harness/tasks/<taskId>/source/** are read-only inputs: reading them is allowed even though writing .harness/** is forbidden. Never resolve `path` relative to the repository root, search for substitutes, or fall back to docs/** when a bound read fails.",
+			"subtask_prompt": "Perform one gap-targeted synchronization, not a full-suite rewrite or stylistic review. Start from explicit bound source IDs/error codes/DTO fields/normative quoted rules and the README Matrix; open and edit only modules that own a missing or conflicting rule. Preserve unrelated valid modules byte-for-byte and avoid optional wording cleanup.\n\nOutput budget protocol: never dump full Matrix/case bodies into assistant chat. Inspect README first, build a concise target list, then read/write only target modules one file per tool call. Do not traverse every module when the Matrix and source token inventory show no gap; return `already-satisfied`. When adding omitted in-scope cases, keep every required section. Do not bulk-delete in-scope cases to save tokens.\n\nFor every variant Test Point, ensure the Markdown scenario intent is machine-checkable and located inside that same Case body/自动化映射, never in a file-level appendix, implementation-details block, or another Case. Use an exact transport target: `场景意图: <TP-ID>; operation=<METHOD /path>; target=<body.field|query.field|path.field|header.field|request>; intent=<empty|missing|null|min-1|min|max|max+1|pattern-invalid|enum-invalid|wrong-type|nominal-operation|custom-literal:V>; bound=<n optional>; example=<optional>; expectedCode=<optional>`. Never use vague targets such as field=resource/health. Keep pytest params aligned to the exact target. For intent=missing/empty/default-omit, pytest may use `_OMIT` or delete the key; for intent=enum-invalid use a concrete invalid enum literal (for example `UNKNOWN_STATUS`), never `_OMIT`/missing-key; for trim/padded samples use `custom-literal:trim` or a real padded string, not a bare token like `filter-active` when the intent is `custom-literal:ACTIVE`.\n\nTreat the requirement document as the coverage baseline; scope is limited to operations/rules it (or its referenced API contract) describes, and API contract evidence supplements scenario dimensions. For every in-scope operation, check applicable lifecycle/uniqueness states (including deleted-existing when in scope), valid enum values, bounded invalid classes, min-1/min/nominal/max/max+1, allowed/forbidden format classes, required/null/missing/wrong-type semantics, status/error codes, auth and state transitions. Inspect shared validator/helper/DTO/query builder evidence and expand Affected Operations when the same affected path can affect them; unresolved impact stays visible as GAP/CONFLICT. Directly add in-scope omissions; reject scope expansion to operations absent from the requirement document; undefined impact remains GAP/CONFLICT rather than invented behavior.\n\nCheck AC completeness/meaning, endpoint, fields/shape, status/error codes, rules, states, documented boundaries/auth, positive/negative coverage, executable steps and assertable results. Require the exact `## Coverage Scope` Field/Value table with the `|---|---|` separator row, a valid classification-policy pair, non-empty Affected Operations/Rule Keys/Scope Evidence, and the classification-specific Regression Floor. Require the exact unnumbered `## Coverage Matrix` heading in `testcase/md/README.md`, exact headers, exactly 9 cells in every data row (including a non-empty Dimension), deterministic OpenAPI Rule Keys for every in-scope affected operation, exactly one Matrix row per Rule Key (merge multi-dimension product rows), and bidirectional Matrix Rule/Test Point ↔ Case bindings. Never describe affected-scope coverage as whole-API completeness. Every explicit AC ID must appear in at least one Case `验收标准`; every explicit in-scope AC/REQ/BR Rule Key cited by a Case must have exactly one Coverage Matrix row, and no Case may cite a source Rule Key omitted from the Matrix. Every Matrix Case ID must share at least one of that row's Required Test Points and the Case must cite that Rule Key. Perform an explicit execution-redundancy review: merge checkpoint-only parameter rows, repeated default/read-back assertions, DELETE status/body/follow-up-read checks, response schema/Content-Type checks, PUT full-update/timestamp checks, repeated list setup and identical null/empty inputs when endpoint, input partition, precondition state and expected outcome are the same. Preserve separate POST/PUT, boundary, enum, wrong-type, role/tenant and distinct business-state variants. Directly repair malformed headings/rows/keys and binding modes rather than merely commenting on them. Reject avoidable English prose, duplicated bilingual wording, repeated boilerplate, oversized unstructured sections, a `### 操作步骤` section that contains only a table without any numbered executable line, vague results such as ‘符合预期’, Case-ID-like module filenames (for example `BE-HEALTH.md`), dropped exact `### 操作步骤`/`### 预期结果` headings, and missing or drifted script/function mapping where it can be derived.\n\nCorrect testcase/md/** directly: add documented omissions, remove unsupported cases, rename module files to stable lowercase stems when needed, normalize every Case ID to hyphen-separated module segments plus exactly three zero-padded digits (`BE-RESOURCE_NOTES-01` → `BE-RESOURCE-NOTES-001`; `BE-RN-011A` must be renumbered or merged) consistently across headings/index/mappings, fix automation mappings so each automatable case points at `testcase/test_<module>.py` derived from that module filename and declares exactly one primary symbol (evidence-only meta cases may keep `脚本/primary symbol=无` with empty variants), assign every Test Point exactly one of `变体测试点`/`场景断言测试点`/`横切证据测试点`, then perform an exact-set check: each Case's `### 测试点` set must equal (not merely contain) the union of those three binding lists; delete stale/legacy aliases and ensure every binding-list Test Point is present, expand every variant parameter row into its own atomic TP ID, make every non-cross-cutting TP Case-specific and owned by exactly one Case, require every primary symbol to start with the canonical Case prefix, ensure every explicit AC ID appears in an applicable Case `验收标准`, merge execution duplicates, improve navigation/tables/Chinese wording, or record gaps in Chinese. Remove every credential/header value, placeholder, fake token and anti-example from Markdown. Sensitive key names may remain only as a plain list; values must be described as runtime-only and omitted, with no colon/value pair or literal example anywhere, including details blocks and explanatory text. Keep Case IDs, AC/REQ/BR IDs, HTTP methods, paths, fields, enum values, filenames, code symbols and source citations as exact machine-readable identifiers; only normalize Case ID separator/sequence formatting as specified above. Recalculate predicted collected items as `sum(max(1, variant count per Case))`; when the task declares a budget, directly merge redundant journeys/reclassify same-request checkpoints until the prediction is within budget, while preserving all required coverage. The validator accepts Chinese and legacy English section aliases; retain or converge to the Chinese human-readable headings without losing structure.\n\nThis is the single Markdown incremental synchronization round. Read every authoritative reference index entry whose role hints include acceptance-criteria, api-contract, data-contract or business-rule; do not rely on the derived PRD as a complete inventory. Preserve every explicit AC/REQ/BR ID, every documented HTTP/business error code, every DTO/JSON field, enum value, boundary, format, nested shape, transaction/state/idempotency/uniqueness/auth/tenant/cross-field rule. For each natural-language normative business rule preserved as required scope, include its exact source sentence without paraphrase together with source path and line/heading anchor so the deterministic ledger can verify quote/hash provenance. Ensure every Case declares exactly `Payload Contract: none` or the three labels `Payload Required Paths`, `Payload Allowed Paths`, and `Payload Enum`; every label must occupy its own machine-readable list line, and a Case must never concatenate target/setup operations or multiple `Payload Contract` tokens onto one line, and explanatory prose/details must not repeat any `Payload Contract:` token; never infer missing keys or enum values. A target GET/DELETE operation with no request body must remain `Payload Contract: none` even when its setup journey performs POST/PUT with a DTO; setup payloads never redefine the target Case payload contract. Add only missing Matrix rows/Test Points/Cases/assertions or repair exact drift; do not rewrite already-valid unrelated modules. Work gap-targeted: inspect source anchors and affected modules first, leave unrelated valid modules byte-stable, and return `already-satisfied` without restating the full suite when no gap exists.\n\nFor affected API fields, use one valid nominal payload plus atomic required/missing/null/empty/wrong-type, every documented enum value plus bounded invalid classes, documented min-1/min/nominal/max/max+1, formats and nested object/array constraints. Do not generate a Cartesian product or invent undocumented constraints. Do not invent a concrete identifier type when the source only requires presence; for a missing-resource 404 path with unspecified identifier syntax/type, synchronize the Case to a create-delete-derived valid identifier journey rather than an arbitrary UUID/text placeholder.\n\nScenario Partitions synchronization: when README declares `## Scenario Partitions`, verify each declared partition's slots are fully materialized as variant Test Points with exact `TP-<Partition ID>-...` IDs (each-value per Domain value, OMITTED only for optional axes, exactly one NOT-IN-SET with intent=enum-invalid). Directly add missing slot rows/Cases. You may delete an illegal Partition row that has no source-backed finite domain, together with its derived `TP-SP-*` slots/Cases. Never delete a legal source-backed partition or drop its complement slot to force coverage green. When the bound source does not document the complement expectation, keep the slot with GAP expected instead of guessing. Body-field validation enums (`TP-<FIELD>-ENUM-*`) are NOT partitions — do not add partition rows for them.\n\nBefore returning, verify that every explicit source AC/REQ/BR, error code and strong DTO field token appears in README or an applicable module Case. If a fact cannot be safely automated, retain it as GAP/CONFLICT with its exact source pointer instead of dropping it. Return already-satisfied only when no target file needs an incremental edit.\n\nRead only indexed source paths. Do not scan the repository, modify source/**, generate pytest, execute tests, or emit JSON.\n\n## Derived task contract: 需求.md\n\n# Backend test\n- AC-001 proof\n\n## Authoritative reference index\n\n[]\n\nFor each index entry, use `readPath` for Pi read-tool calls and keep `path` as the exact Markdown Source References citation. Bound files under .harness/tasks/<taskId>/source/** are read-only inputs: reading them is allowed even though writing .harness/** is forbidden. Never resolve `path` relative to the repository root, search for substitutes, or fall back to docs/** when a bound read fails.",
 			"retryPolicy": {
 				"maxAttempts": 2,
 				"backoff": "exponential",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.39.0-next.23",
+  "version": "0.39.0-next.25",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",
@@ -39,6 +39,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "engines": {
+    "node": ">=22.19.0"
+  },
   "scripts": {
     "dev": "node --import tsx/esm src/cli.ts",
     "cursor": "node --import tsx/esm src/cli.ts cursor-prompt",
@@ -64,6 +67,8 @@
     "verify:tree": "node scripts/pre-push-verify.mjs --verify-current-tree"
   },
   "dependencies": {
+    "@earendil-works/pi-ai": "0.83.0",
+    "@earendil-works/pi-coding-agent": "0.83.0",
     "commander": "^12.1.0",
     "katex": "^0.16.47",
     "mermaid": "^11.16.1",
@@ -71,13 +76,12 @@
     "rehype-katex": "^7.0.1",
     "remark-math": "^6.0.0",
     "semver": "^7.8.5",
+    "typebox": "1.3.7",
     "yaml": "^2.9.0",
     "zod": "^3.25.76"
   },
   "optionalDependencies": {
-    "@cursor/sdk": "^1.0.7",
-    "@earendil-works/pi-ai": "0.80.10",
-    "@earendil-works/pi-coding-agent": "0.80.10"
+    "@cursor/sdk": "^1.0.7"
   },
   "devDependencies": {
     "@remixicon/react": "^4.9.0",

package/skills/analyze-product-requirements/SKILL.md

@@ -48,8 +48,9 @@ IRON LAW：`product-analysis.md` 必须先写入正式路径，再对该正式
   - [ ] 知识库状态为 `executed-hit` 或 `executed-no-match`，或 `unavailable` 后用户明确确认跳过，才允许进入项目资料预扫描与常规代码探索；其余情况保持阻断。
   - [ ] 知识库门禁通过后，依次预扫描 `<project-root>/ai_workspace/project-how-to`、`code-specification`、`project-business`：先枚举文件，再读取入口文档及与当前需求直接相关的内容；缺失目录记录 `not-found` 并继续，不做无边界加载。
   - [ ] 然后读取并执行 `references/clarification-and-knowledge.md` 第 1 节，按需求问题和知识库结论定向探索代码库。当前宿主支持隔离的只读代码侦察 agent 时，优先委派限定范围的代码探索；不支持时由当前 agent 执行同等范围的定向搜索并只保留精简结果，不得阻断或扩大搜索范围。知识库结论不得替代代码落点证据。
+  - [ ] 执行「输入↔规范一致性核对」：将原始需求的每条明确声明与有效规范证据（`KB-FACT-*`、ai_workspace 项目资料、仓库规范文档）及代码现状事实（`CODE-FACT-*`）逐条比对，分类为 一致 / 规范补充 / 冲突 / 无规则。分类为"冲突"的条目必须逐条进入待确认问题，标注"输入声明 vs 规范/代码声明"与冲突来源，用户裁决前不选边。该核对是强制步骤，任何"输入明确"都不构成豁免；规范补充仅适用于规范类事实，代码现状在输入未说明时按 unknown 分流，不得静默填补。
   - [ ] 汇总原始需求、`KB-FACT-*`、项目资料与 `CODE-FACT-*`，识别可查明事实、冲突、unknown 和必须由用户选择的目标行为；完成以上顺序后才生成待确认问题并进入 Step 2。
-  - [ ] 区分明确需求、推断需求和待确认问题。推断需求一律视为未确认产品内容；每一项推断需求以及任何含糊、缺失、冲突或存在多种合理解释的产品问题，都必须进入 Step 2 逐题向用户澄清，不得因模型认为推荐答案合理而跳过。
+  - [ ] 区分明确需求、推断需求和待确认问题。推断需求一律视为未确认产品内容；每一项推断需求以及任何含糊、缺失、冲突或存在多种合理解释的产品问题，都必须进入 Step 2 逐题向用户澄清，不得因模型认为推荐答案合理而跳过。与有效规范或代码现状冲突的行为不属于"明确需求"，不得按 `source-requirement` 直接合并；冲突按 unknown 同款边界分流：影响范围、权限、业务规则、用户可感知输出/状态/边界或验收结果的冲突必须澄清，纯实现/技术细节冲突只记录事实、不生成问题。
   - [ ] scope 包含 backend 且需求涉及接口/API 时，必须确认实现范围为 Web、Remote 或 Web + Remote；只写笼统“接口/API”视为待确认问题。不得依据知识库或代码现状替用户选择。
   - [ ] 仅按 target 生成精简故事骨架和逐故事初步输出规范：`frontend` 只生成 `FE-US-*`，`backend` 只生成 `BE-US-*`，`both` 才生成两端。
   - [ ] Product Analysis 只记录验收关注点，不创建正式 `AC-*` 或完整 Given/When/Then。每个前端故事的同 ID 初步输出规范必须包含“页面路由”：独立页面写以 `/` 开头的目标 URL；组件、弹窗或抽屉无独立路由时写“`不适用；嵌入 /目标路径 页面`”（`/目标路径` 替换为真实路径）。
@@ -74,23 +75,23 @@ IRON LAW：`product-analysis.md` 必须先写入正式路径，再对该正式
   - [ ] 澄清进行中：每次合成后重写 `pending` Product Requirement，并保留“未决事项”；不得标为 `complete`。
   - [ ] pending Clarification 与 pending Product Requirement 写入后，使用 `--allow-pending` 运行二者校验器；两者状态必须一致。`--allow-pending` 仅用于内部中间产物校验，不得用于最终交付或下游消费。
   - [ ] 共同理解已确认后：生成 `complete` Product Requirement；Clarification 同步为 `complete`。
-  - [ ] 优先级：用户确认决策 > 原始明确需求 > 当前有效的知识库项目规范 > 模型推断；知识库/代码事实只用于理解项目规范与现状、发现冲突和辅助澄清，不得发明产品意图。
+  - [ ] 优先级（仅用于「输入↔规范一致性核对」与冲突澄清完成、用户裁决后的合成默认，不构成跳过澄清的依据）：用户确认决策 > 原始明确需求 > 当前有效的知识库项目规范 > 模型推断；知识库/代码事实只用于理解项目规范与现状、发现冲突和辅助澄清，不得发明产品意图。
   - [ ] 不得把 `KB-FACT-*`、`CODE-FACT-*`、知识库/仓库路径或代码符号原样写入 Product Requirement。
   - [ ] 用户故事只描述角色/使用方、目标/能力、价值、入口/触发方式和 AC 引用；详细产品行为只写在同 ID 输出规范中，正式 AC 嵌入该输出规范。
   - [ ] 逐个检查每个 `FE-US-*` 的同 ID 输出规范并写入“页面路由”，不得因多个故事共享页面而省略或合并该字段。独立页面写以 `/` 开头的目标 URL；组件、弹窗或抽屉无独立路由时写“`不适用；嵌入 /目标路径 页面`”（`/目标路径` 替换为真实路径）。
   - [ ] target 为 `backend` 或 `both` 时，后端故事只定义 API 的业务能力、输入输出语义、权限和规则；触发方式写 `API（Web）`、`API（Remote）` 或 `API（Web + Remote）`。Web + Remote 表示同一能力需要两个接口；具体 Method+Path 及 DTO 留给依赖 skill。
-  - [ ] 后端分页：每页条数允许值按“原始需求/用户确认 > 有效知识库分页规范 > 默认集合 `10`、`20`、`50`、`100`”确定。参数名、必填性、默认值和其他契约不得从知识库 API 文档自动带入。
+  - [ ] 后端分页：每页条数允许值与其他规则同等参与「输入↔规范一致性核对」。输入与有效分页规范冲突（含允许值集合的差异、子集或超集）时必须进入待确认问题澄清，用户裁决后以确认值为准；无冲突时按”用户确认 > 原始需求 > 有效知识库分页规范 > 默认集合 `10`、`20`、`50`、`100`”确定。参数名、必填性、默认值和其他契约不得从知识库 API 文档自动带入。
 - [ ] Step 5：验证并交付 ⛔ BLOCKING
   - [ ] 再次以只读方式向已冻结 Product Analysis 和 Product Requirement 校验器传入归一化 target，只运行三个当前产物校验器；Product Analysis 在 Step 1 已通过正式文件校验，本步不得因任何原因修改它。交付路径不得使用 `--allow-pending`。
   - [ ] Requirement Clarification 校验器核对 Product Analysis/Clarification 的原始需求身份，以及三个产物的 requirement ID、analysis scope 和状态；冻结不做脚本校验。
   - [ ] 只有所有命令返回 0 才能声明完成。本步只交付 complete V4 Product Requirement；下游 `analyze-product-dependencies` 首选消费该产物，其 `--target` 可为本次 `analysis_scope` 的子集。
   - [ ] `test-validators.mjs` 仅在修改本 skill 的输出契约、schema、validator、artifact version、示例、forward-test contract，或发布/安装/回归验证时运行；普通需求分析不运行 validator matrix。
 
-完整格式示例按需读取 `references/example.md`；维护或 forward-test 时读取 `references/forward-test-cases.md`。不要为了执行校验而阅读脚本，直接运行。
+完整格式示例按需读取 `references/example.md`（含无需澄清与输入↔规范冲突澄清两条路径）；维护或 forward-test 时读取 `references/forward-test-cases.md`。不要为了执行校验而阅读脚本，直接运行。
 
 ## 完成规则
 
-- `no-clarification-required` 仍生成三个产物，但只适用于“推断需求”为 `- 无未确认的推断需求。` 且“待确认问题”为 `- 无待确认问题。` 的场景；Clarification 使用“澄清结论、来源、合并结果”三章精简结构，并记录 `- 内容补充：用户已确认无需补充`；不得仅凭模型判断需求足够明确就自动完成。
+- `no-clarification-required` 仍生成三个产物，但只适用于”推断需求”为 `- 无未确认的推断需求。` 且”待确认问题”为 `- 无待确认问题。` 的场景，且必须完成「输入↔规范一致性核对」并在待确认问题记录 `- 一致性核对：…未发现冲突条目。`；Clarification 使用”澄清结论、来源、合并结果”三章精简结构，并记录 `- 内容补充：用户已确认无需补充`；不得仅凭模型判断需求足够明确就自动完成。
 - 需要澄清的 `complete` Clarification：全部分支 resolved，所有实际 `Q-*` 为 `confirmed/user`，决策索引含 `- 共同理解：已确认`，每个 `DEC-Q-*` 进入 Product Requirement 决策追溯。
 - Product Requirement 必须自包含；只描述目标产品行为，不得出现 `KB-FACT-*`、`CODE-FACT-*`、知识库/仓库文件路径、代码级类/函数/组件符号、模块调用关系、数据表名、证据位置或实现算法。
 - 不得生成独立用户角色、验收标准汇总、前后端契约、Open Questions、测试建议或独立边界 case 章节。
@@ -110,6 +111,8 @@ IRON LAW：`product-analysis.md` 必须先写入正式路径，再对该正式
 - 在 Product Analysis 写正式 `AC-*` 或 Given/When/Then。
 - 任何前端故事的同 ID Product Analysis 或 Product Requirement 输出规范缺少“页面路由”，或因共享页面而只在其中一个故事中填写。
 - 输入已给出分页允许值时，用知识库规范或默认 `10/20/50/100` 覆盖；或从知识库/API 文档自动带入路径、方法、参数名、必填性、默认值、响应、错误码或 DTO。
+- 输入与有效规范（知识库、ai_workspace、仓库规范）或代码现状冲突时，按"原始需求优先"静默采用输入而不进入澄清；分页允许值冲突也不例外。
+- 「输入↔规范一致性核对」漏掉任一证据通道，或把"规范补充"误判为"冲突"、把"冲突"静默当作"规范补充"处理，或用代码现状填补输入未说明的产品行为。
 - 生成独立用户角色、验收标准汇总、前后端契约、Open Questions、测试建议或边界 case 章节。
 
 ## 交付前自检

package/skills/analyze-product-requirements/references/acceptance-criteria.md

@@ -4,7 +4,7 @@
 
 每条验收标准必须独立可执行、结果可观察，并使用 Given/When/Then。一个用户故事存在多个关键流程时，拆成多个 AC，不要把互不相关的行为塞入一条 AC。
 
-涉及状态变量、空数据、loading、error、disabled、错误提示或恢复入口时，Then 与异常场景必须使用已查明的项目枚举、共享组件、文案和交互规范；不得用通用占位状态替代项目规范。明确需求与项目规范冲突时先澄清目标行为。
+涉及状态变量、空数据、loading、error、disabled、错误提示或恢复入口时，Then 与异常场景必须使用已查明的项目枚举、共享组件、文案和交互规范；不得用通用占位状态替代项目规范。明确需求与项目规范或代码现状冲突时先澄清目标行为。
 
 每条 AC 必须说明：
 

package/skills/analyze-product-requirements/references/clarification-and-knowledge.md

@@ -6,21 +6,21 @@
 
 项目资料预扫描的时机与顺序按 `kb-integration.md` 执行；命中内容不得替代真实代码证据。
 
-有效知识结果使用 `KB-FACT-*`，包含规范事实、来源文档及定位、版本/生效状态、适用范围、需求影响和置信度。知识库用于说明项目要求，代码库用于说明当前实现；知识库命中不能把代码文件、符号或调用关系标记为 confirmed。
+有效知识结果使用 `KB-FACT-*`，包含规范事实、来源文档及定位、版本/生效状态、适用范围、需求影响、置信度和与输入关系（一致 | 补充 | 冲突）。知识库用于说明项目要求，代码库用于说明当前实现；知识库命中不能把代码文件、符号或调用关系标记为 confirmed。
 
-提供代码仓库且当前宿主支持隔离的只读代码侦察 agent 时，优先将定向事实搜索交给该 agent：认证、权限、状态枚举、相似能力、字段类型、统一错误结构、设计系统、空数据及 loading/error 展示。委派内容仅包含待查问题、允许搜索的范围和适用的知识库规范结论，当前会话只保留结论、证据位置、置信度和未定位项。当前宿主不支持该能力时，由当前 agent 先限定故事、问题、目录或关键词，再沿直接相关引用定向搜索，不做无边界扫描；不得因此阻断流程或扩大搜索范围。文件搜索优先使用 `rg --files` 和 `rg`，没有 `rg` 时使用宿主提供的等价只读搜索能力，不得降低证据标准。事实使用 `CODE-FACT-*`，包含事实、证据位置和需求影响。代码只能回答现状，不能替代用户决定目标需求。
+提供代码仓库且当前宿主支持隔离的只读代码侦察 agent 时，优先将定向事实搜索交给该 agent：认证、权限、状态枚举、相似能力、字段类型、统一错误结构、设计系统、空数据及 loading/error 展示。委派内容仅包含待查问题、允许搜索的范围和适用的知识库规范结论，当前会话只保留结论、证据位置、置信度和未定位项。当前宿主不支持该能力时，由当前 agent 先限定故事、问题、目录或关键词，再沿直接相关引用定向搜索，不做无边界扫描；不得因此阻断流程或扩大搜索范围。文件搜索优先使用 `rg --files` 和 `rg`，没有 `rg` 时使用宿主提供的等价只读搜索能力，不得降低证据标准。事实使用 `CODE-FACT-*`，包含事实、证据位置、需求影响、证据类别（项目规范 | 代码现状）和与输入关系（一致 | 补充 | 冲突）。ai_workspace 项目资料与仓库规范文档统一记录为 `CODE-FACT-*` 并标注证据类别：项目规范；代码现状标注证据类别：代码现状。代码只能回答现状，不能替代用户决定目标需求。
 
-scope 包含 backend 且涉及分页时：每页条数允许值以原始需求/用户确认为准；未说明时优先采用 `kb-design-assist` 返回的当前有效分页规范，仍未查明才使用默认集合 `10`、`20`、`50`、`100`。不得把知识库/API 文档的路径、方法、参数名、必填性、默认值、响应、错误码或 DTO 自动合并为产品需求。分析状态变量、空数据、loading、error、disabled 或兜底行为时，优先以当前有效知识库规范为项目规范来源，再核验仓库级指令、设计系统、共享组件和同类实现；未查明时写 unknown，不得用通用惯例冒充项目规范。
+scope 包含 backend 且涉及分页时：每页条数允许值与其他明确声明一样参与「输入↔规范一致性核对」。输入与有效分页规范冲突（含允许值集合的差异、子集或超集）时必须进入澄清，用户裁决后以确认值为准；输入未说明时优先采用 `kb-design-assist` 返回的当前有效分页规范，仍未查明才使用默认集合 `10`、`20`、`50`、`100`。不得把知识库/API 文档的路径、方法、参数名、必填性、默认值、响应、错误码或 DTO 自动合并为产品需求。分析状态变量、空数据、loading、error、disabled 或兜底行为时，优先以当前有效知识库规范为项目规范来源，再核验仓库级指令、设计系统、共享组件和同类实现；未查明时写 unknown，不得用通用惯例冒充项目规范。
 
 unknown 按影响分流：会改变范围、权限、业务规则、用户可感知输出/状态/边界或验收结果时，提炼成目标行为的产品决策并进入澄清；只涉及代码位置、符号、实现方式、技术复用或证据缺失时，保留为 `CODE-FACT-*` unknown 并交给依赖分析，不向用户提问，也不进入 Product Requirement。不得询问用户“代码在哪里”；应询问用户希望产品表现为何。
 
 scope 包含 backend 且需求涉及接口/API 时，Web、Remote 或 Web + Remote 属于必须由用户确认的产品范围。只写笼统“接口/API”时生成一个澄清问题；确认结果写入现有“触发方式”，不得新增接口形态字段。Web + Remote 表示同一能力需要两个 HTTP 接口。
 
-知识库、代码或需求之间冲突时：保留来源证据、生成澄清问题、用户裁决前不选边。过期、适用范围不明、互相冲突或无来源定位的知识结果按 unknown 处理。
+执行「输入↔规范一致性核对」：将原始需求的每条明确声明与有效规范证据（`KB-FACT-*`、ai_workspace 项目资料、仓库规范文档，统一以 `KB-FACT-*`/`CODE-FACT-*` 记录并标注与输入关系）及代码现状事实（`CODE-FACT-*`）逐条比对，分类为 一致 / 规范补充 / 冲突 / 无规则。分类为"冲突"的条目必须进入待确认问题，保留双方声明与来源证据，用户裁决前不选边；"输入明确"不构成豁免。规范补充仅适用于规范类事实（`KB-FACT-*` 及"证据类别：项目规范"的 `CODE-FACT-*`），输入未说明时直接并入、不生成问题；代码现状不得静默填补产品行为。冲突按 unknown 同款边界分流：影响范围、权限、业务规则、用户可感知输出/状态/边界或验收结果的冲突必须逐条澄清；纯实现/技术细节冲突只标"与输入关系：冲突"、不生成问题，留待依赖分析。过期、适用范围不明、互相冲突或无来源定位的知识结果按 unknown 处理。
 
 ## 2. 决策树式访谈
 
-1. 从 Product Analysis 的全部推断需求、待确认问题和输出规范中的未确认产品内容提取顶层 `BR-*` 分支；每一项推断、含糊、缺失、冲突、多种合理解释或目标行为 unknown 都必须进入决策树，覆盖完整分支，不为满足数量制造分支。原始需求已明确且不存在歧义的行为直接作为 `source-requirement` 事实，不创建分支或问题。
+1. 从 Product Analysis 的全部推断需求、待确认问题和输出规范中的未确认产品内容提取顶层 `BR-*` 分支；每一项推断、含糊、缺失、冲突、多种合理解释或目标行为 unknown 都必须进入决策树，覆盖完整分支，不为满足数量制造分支。原始需求已明确、与有效规范及代码现状核对一致且不存在歧义的行为直接作为 `source-requirement` 事实，不创建分支或问题；与有效规范或代码现状冲突的行为视为存在歧义，必须进入决策树。
 2. 标注分支依赖，从范围、权限、核心流程、数据语义等基础决策开始。
 3. 每轮只处理一个决策问题：先给推荐答案和理由，再提问并等待回答。任何两个待决子项都不得合并为一次提问。
 4. 收到回答后重新识别剩余推断、模糊点、缺失项、冲突和新引入的未定义产品内容；只要仍存在未确认产品问题或需求，就开启下一轮。
@@ -32,7 +32,7 @@ scope 包含 backend 且需求涉及接口/API 时，Web、Remote 或 Web + Remo
 
 ### 回答复核
 
-收到用户回答后，先判断它是否直接覆盖当前问题的关键决策点、是否只有一种合理的产品解释、是否足以写成明确的范围/规则/输出行为/验收结果、是否与原始明确需求或已有决策冲突，以及是否引入新的未定义概念、例外条件或依赖关系。全部满足时才形成最终决策并标记为 confirmed。
+收到用户回答后，先判断它是否直接覆盖当前问题的关键决策点、是否只有一种合理的产品解释、是否足以写成明确的范围/规则/输出行为/验收结果、是否与原始明确需求、已有决策、有效规范或代码现状冲突，以及是否引入新的未定义概念、例外条件或依赖关系。全部满足时才形成最终决策并标记为 confirmed。
 
 任一条件不满足时：
 
@@ -43,6 +43,10 @@ scope 包含 backend 且需求涉及接口/API 时，Web、Remote 或 Web + Remo
 
 当前问题明确后，再扫描全部推断需求、其他未解决问题和本次回答新引入的模糊点。只要内容属于产品需求或目标行为且尚未确认，就必须继续澄清；纯措辞、代码位置、符号、实现方式、技术复用和其他不构成产品需求的下游技术细节不消耗澄清轮次。
 
+### 澄清轮中的规范冲突
+
+Product Analysis 冻结后，回答复核、用户回答或新证据暴露"用户回答或新增内容与有效规范/代码现状冲突"时：不得标记 confirmed；下一轮继续当前分支，把冲突双方声明与来源（`KB-FACT-*`/`CODE-FACT-*`）并列呈现，并在 Q-* 的"推荐理由"中成对写明，`最终决策` 记录用户裁决结果。已冻结的 Product Analysis 不回写。
+
 问题等级：
 
 - P0：改变范围、权限、关键流程、数据语义或验收结果；必须由用户明确确认。

package/skills/analyze-product-requirements/references/example.md

@@ -24,6 +24,7 @@ analysis_status: no-clarification-required
 - 无未确认的推断需求。
 ### 4.3 待确认问题
 - 无待确认问题。
+- 一致性核对：已逐条比对知识库、ai_workspace、仓库规范与代码现状，未发现冲突条目。
 - 理由：范围、权限、校验、失败恢复和非目标均已由原始需求明确。
 ### 4.4 初步非目标
 - 不修改头像。
@@ -102,3 +103,52 @@ Then：
 ```
 
 故事与输出规范使用同一 ID；故事只引用 AC，AC 正文只在对应输出规范中出现一次。
+
+# 需要澄清路径示例（输入 ↔ 规范冲突）
+
+需求：查询订单列表支持分页，pageSize 允许值为 5、10、20。
+知识库命中分页规范：允许值为 20、50、100。
+
+## Product Analysis 外部事实与冲突条目
+
+```md
+## 5. 外部事实
+### 5.1 知识库事实
+- 检索状态：executed-hit。
+- KB-FACT-001：分页允许值为 20、50、100；来源：分页规范 v3 §2；版本：当前有效；与输入关系：冲突。
+### 5.2 代码库事实
+- CODE-FACT-001：列表接口已存在，pageSize 为必填；证据位置：列表 controller；证据类别：代码现状；与输入关系：一致。
+
+## 4. 需求分析
+### 4.3 待确认问题
+- P0：分页允许值集合冲突；冲突描述：输入声明「5、10、20」vs 规范声明「20、50、100」；冲突来源：KB-FACT-001；影响范围：backend。
+```
+
+## Clarification Q-* 冲突记录
+
+澄清轮中不新增字段，冲突双方声明成对写入推荐理由，最终决策记录裁决结果。
+
+```md
+### Q-001 分页允许值
+- 澄清轮次：1
+- 分支：BR-001
+- 优先级：P0
+- 影响范围：backend
+- 推荐答案：采用项目分页规范 20、50、100
+- 推荐理由：输入声明为 5、10、20，项目规范（KB-FACT-001：分页规范 v3 §2）为 20、50、100，两者冲突；代码现状（CODE-FACT-001）未约束允许值集合，需用户裁决。
+- 用户回答：仍使用 5、10、20
+- 最终决策：分页允许值为 5、10、20，覆盖项目分页规范默认值
+- 决策来源：user
+- 状态：confirmed
+- 决策标记：DEC-Q-001
+- 目标位置：后端输出规范分页约定
+```
+
+## Product Requirement 合成
+
+```md
+## 4. 业务规则
+- 分页允许值集合为 5、10、20（用户裁决，覆盖项目分页规范默认值）。
+## 7. 决策追溯
+- DEC-Q-001：分页允许值为 5、10、20，已合并到后端输出规范分页约定。
+```

package/skills/analyze-product-requirements/references/forward-test-cases.md

@@ -9,7 +9,7 @@
 需求：登录用户在个人资料页修改自己的昵称；昵称 2–20 个字符；保存失败时保留输入并允许重试；不修改头像。
 ```
 
-核对：生成产物前直接询问用户是否还有内容需要补充；未收到明确的“无需补充/确认继续”前不冻结 Product Analysis、不生成 complete 产物；用户确认后，三个产物都在 `<project-root>/docs/product-analysis/<requirement-id>/`，三者 `analysis_scope` 均为 `frontend`；Product Analysis 为 `no-clarification-required` 且不含正式 AC，其“原始需求”包含有效 `inline:sha256:*` 身份，每个前端初步输出规范包含有效页面路由；Clarification 使用三章精简结构、记录相同的原始需求身份和 `内容补充：用户已确认无需补充`，且没有 BR/Q/DEC；Product Requirement 为 complete，不含“默认假设”或“未决事项”；故事与同 ID 输出规范一一对应，每个前端规范均包含有效页面路由。
+核对：生成产物前直接询问用户是否还有内容需要补充；未收到明确的“无需补充/确认继续”前不冻结 Product Analysis、不生成 complete 产物；用户确认后，三个产物都在 `<project-root>/docs/product-analysis/<requirement-id>/`，三者 `analysis_scope` 均为 `frontend`；Product Analysis 为 `no-clarification-required` 且不含正式 AC，其“原始需求”包含有效 `inline:sha256:*` 身份，“待确认问题”包含 `- 一致性核对：…未发现冲突条目。` 行且无任何“与输入关系：冲突”事实，每个前端初步输出规范包含有效页面路由；Clarification 使用三章精简结构、记录相同的原始需求身份和 `内容补充：用户已确认无需补充`，且没有 BR/Q/DEC；Product Requirement 为 complete，不含“默认假设”或“未决事项”；故事与同 ID 输出规范一一对应，每个前端规范均包含有效页面路由。
 
 ## Case 2：需要逐题澄清
 
@@ -65,7 +65,7 @@
 
 核对：Product Analysis 可记录 `CODE-FACT-*`、证据路径和现状；Clarification 可引用该证据辅助判断，但不得把现状自动视为目标决策；Product Requirement 只写“仅管理员可以导出用户数据”等产品规则，不包含 `CODE-FACT-*`、`src/auth/permission.ts`、`role=admin`、代码符号、模块结构或当前实现过程。
 
-## Case 8：分页允许值来源
+## Case 8：分页允许值来源与冲突澄清
 
 ```text
 显式调用 `analyze-product-requirements` skill，参数：`target=backend`。
@@ -73,7 +73,7 @@ A：需求明确 pageSize 为必填，但未给出允许值集合。
 B：需求明确 pageSize 允许值为 5、10、20。
 ```
 
-知识库分页规范允许值为 `20/50/100`。核对：A 使用有效知识库规范的 `20/50/100`；B 原样沿用 `5/10/20`，不得被知识库或默认集合覆盖。知识库不可用或未命中时，A 才使用默认集合 `10/20/50/100`。不得从知识库/API 文档自动带入路径、方法、参数名、必填性、默认值、响应、错误码或 DTO。
+知识库分页规范允许值为 `20/50/100`。核对：A 使用有效知识库规范的 `20/50/100`；B 的输入值与知识库规范冲突（集合差异），必须进入待确认问题（对应事实标记 `与输入关系：冲突`，条目含 `冲突来源` 引用）并向用户逐题澄清，不得静默采用输入或规范；用户裁决后以确认值为准。知识库不可用或未命中时，A 才使用默认集合 `10/20/50/100`。不得从知识库/API 文档自动带入路径、方法、参数名、必填性、默认值、响应、错误码或 DTO。
 
 ## Case 9：项目状态与空数据规范
 
@@ -89,7 +89,7 @@ B：需求明确 pageSize 允许值为 5、10、20。
 
 ## Case 12：原始明确行为不伪造问题
 
-原始需求明确指定页面路由、权限和错误恢复方式。核对：这些内容以 `source-requirement` 事实直接合并，不生成 `Q-*`、`DEC-Q-*` 或二次确认。
+原始需求明确指定页面路由、权限和错误恢复方式，且与有效规范（知识库、ai_workspace、仓库规范）及代码现状核对一致。核对：这些内容以 `source-requirement` 事实直接合并，不生成 `Q-*`、`DEC-Q-*` 或二次确认；任一通道与输入冲突时不得免澄清。
 
 ## Case 13：页面路由
 
@@ -111,9 +111,9 @@ B：需求明确 pageSize 允许值为 5、10、20。
 
 分别使用“看似不涉及项目规范”的简单需求、让 `kb-design-assist` 返回无结果，以及让调用失败。核对：简单需求仍先从需求提取检索词并真实调用知识库，不允许 `not-executed`；无结果记录 `executed-no-match`，在有仓库时降级为受限、定向的代码库规范搜索，无仓库时按 unknown 分流；调用失败记录 `unavailable`，必须先说明失败原因并询问用户选择“修复后重试”或“跳过知识库”，未选择前不得预扫描项目资料、探索代码库或生成 complete 产物；选择修复后按重试结果继续，明确选择跳过后才允许降级。不得把“未执行”误写成“未命中”，也不得绕过确认门禁。
 
-## Case 18：知识库与需求冲突
+## Case 18：知识库与需求冲突（四通道）
 
-原始需求明确分页允许值为 `5/10/20`，知识库规范为 `20/50/100`；另提供一份与原始错误恢复行为冲突的设计规范。核对：分页沿用原始需求；用户可见行为冲突进入逐题澄清，用户裁决前保持 pending；不得静默采用知识库结果。
+原始需求明确分页允许值为 `5/10/20`，知识库规范为 `20/50/100`；另提供与原始错误恢复行为冲突的设计规范、ai_workspace 校验规则冲突和代码现状冲突各一份。核对：四类冲突全部进入待确认问题并逐题澄清（含分页允许值，不得静默采用输入或规范）；每条冲突条目成对列出输入声明与规范/代码声明、标注 `冲突来源`，对应事实标记 `与输入关系：冲突`；用户裁决前保持 pending，裁决后以确认值为准。
 
 ## Case 19：Web + Remote 接口范围
 
@@ -125,7 +125,7 @@ B：需求明确 pageSize 允许值为 5、10、20。
 
 ## Case 20A：知识库、代码库与澄清顺序
 
-使用同时包含权限歧义、状态约定和已有相似实现的需求。核对执行轨迹严格为：从原始需求提取检索计划 → 调用 `kb-design-assist` → 项目资料预扫描 → 按知识结论定向探索代码库 → 汇总冲突与 unknown → 逐题向用户澄清。不得在知识库门禁通过前搜索代码，也不得在代码事实尚可查证时提前询问用户。
+使用同时包含权限歧义、状态约定和已有相似实现的需求。核对执行轨迹严格为：从原始需求提取检索计划 → 调用 `kb-design-assist` → 项目资料预扫描 → 按知识结论定向探索代码库 → 执行「输入↔规范一致性核对」→ 汇总冲突与 unknown → 逐题向用户澄清。不得在知识库门禁通过前搜索代码，也不得在代码事实尚可查证时提前询问用户。
 
 ## Case 21：提示词冻结与来源身份
 
@@ -142,3 +142,7 @@ B：需求明确 pageSize 允许值为 5、10、20。
 ## Case 23：严格结构与全局唯一性
 
 分别向三个产物 frontmatter 注入 `source_path`，让两个故事复用同一个 AC ID，并把 complete Clarification 的“最终决策”改为“未形成”。核对：额外 frontmatter 字段、重复 AC ID 和未形成最终决策都被 validator 拒绝。
+
+## Case 24：输入与规范冲突必须澄清
+
+需求：昵称 1–30 个字符；知识库/ai_workspace 规范为 2–20 个字符。核对：输入声明与规范冲突必须进入待确认问题（冲突描述成对列出双方声明、含 `冲突来源` 引用，对应事实标记 `与输入关系：冲突`），逐题澄清，用户裁决前保持 pending；用户确认后 Q-* 为 confirmed/user，Product Requirement 采用确认值。构造以下 Product Analysis 时 validator 必须拒绝：(a) 事实标记 `与输入关系：冲突` 但待确认问题未引用其 ID；(b) `no-clarification-required` 且存在冲突标记；(c) `no-clarification-required` 且待确认问题缺少 `- 一致性核对：…未发现冲突条目。` 行；构造 Clarification 未覆盖 PA 冲突条目（冲突事实 ID 未出现在任何 Q-*）时，complete 校验必须拒绝。

package/skills/analyze-product-requirements/references/kb-integration.md

@@ -13,7 +13,7 @@
 
 需求分析优先查询设计系统、交互/文案规范、用户可见状态枚举、共享状态组件、权限可见性、错误语义和分页允许值。Controller、Service、Entity、Response、Remote、Web API 或 `interfaces.md` 等纯实现规范仅用于判断当前问题是否属于下游技术设计，不得据此扩写产品需求。
 
-知识库状态已确定或用户确认跳过后，再按固定顺序预扫描 `<project-root>/ai_workspace/project-how-to`、`code-specification`、`project-business`，然后才进入常规代码搜索。目录缺失不阻断；命中内容作为项目资料事实记录，并按知识库、项目资料、代码现状之间的冲突规则处理。
+知识库状态已确定或用户确认跳过后，再按固定顺序预扫描 `<project-root>/ai_workspace/project-how-to`、`code-specification`、`project-business`，然后才进入常规代码搜索。目录缺失不阻断；命中内容统一记录为 `CODE-FACT-*` 条目并标注证据类别：项目规范，参与「输入↔规范一致性核对」。仓库规范文档（仓库级指令、README、设计系统、架构规范）同样记录为 `CODE-FACT-*` 并标注证据类别：项目规范。
 
 ## 结果状态
 
@@ -36,18 +36,18 @@
 
 ## 事实与优先级
 
-每条有效结果使用 `KB-FACT-*`，记录规范事实、来源文档及定位、版本/生效状态、适用范围、需求影响和置信度。过期、适用范围不明、相互冲突或无法定位来源的结果不得作为已确认规范，只能记录为冲突或 unknown。
+每条有效结果使用 `KB-FACT-*`，记录规范事实、来源文档及定位、版本/生效状态、适用范围、需求影响、置信度和与输入关系（一致 | 补充 | 冲突）。事实条目使用单行格式：`- <KB|CODE>-FACT-<编号>：<事实>；来源：<文档/证据定位>；证据类别：<项目规范|代码现状>（仅 CODE-FACT）；与输入关系：<一致|补充|冲突>`。标记为"冲突"的事实必须被 Product Analysis"待确认问题"的冲突条目引用。过期、适用范围不明、相互冲突或无法定位来源的结果不得作为已确认规范，只能记录为冲突或 unknown。
 
-产品行为来源优先级：
+产品行为来源优先级（仅用于「输入↔规范一致性核对」与冲突澄清完成、用户裁决后的合成默认，不构成跳过澄清的依据）：
 
 1. 用户已确认决策。
 2. 原始需求明确内容。
 3. 当前有效且适用于本项目的知识库规范。
 4. 模型推断或通用兜底。
 
-知识库与用户决策、原始需求或另一份有效规范冲突时，保留证据并生成产品澄清问题，用户裁决前不得选边。知识库事实只能填补项目规范，不得发明业务范围、业务规则或用户意图。
+"原始需求明确内容"不等于"无冲突"：输入声明与有效规范（知识库、ai_workspace 项目资料、仓库规范文档）或代码现状冲突时，保留证据并生成产品澄清问题，用户裁决前不得按优先级静默采用输入或规范。知识库事实只能填补项目规范，不得发明业务范围、业务规则或用户意图。
 
-分页允许值遵循：原始需求/用户确认 > 有效知识库分页规范 > 固定兜底 `10/20/50/100`。即使知识库命中 API 文档，也不得自动带入路径、方法、参数名、必填性、默认值、响应结构、错误码或 DTO。
+分页允许值与其他规则一样参与「输入↔规范一致性核对」：输入与有效知识库分页规范冲突（含集合差异、子集或超集）时进入澄清，用户裁决后以确认值为准；无冲突时遵循：原始需求/用户确认 > 有效知识库分页规范 > 固定兜底 `10/20/50/100`。即使知识库命中 API 文档，也不得自动带入路径、方法、参数名、必填性、默认值、响应结构、错误码或 DTO。
 
 ## 产物边界
 

package/skills/analyze-product-requirements/references/product-analysis-schema.md

@@ -18,7 +18,9 @@ Frontmatter 只允许以上五个字段，不得增加来源路径、项目根
 
 固定章节：原始需求、需求概述、业务目标、需求分析、外部事实。原始需求必须包含 `- 原始需求身份：inline:sha256:<64位小写十六进制>` 或 `- 原始需求身份：file:sha256:<64位小写十六进制>`，并保留准确原文；inline 摘要只绑定正文，file 摘要同时绑定规范化真实路径与正文，均使用 `scripts/compute-source-identity.mjs` 生成。不得把原始路径另写入 frontmatter。
 
-需求分析包含明确需求、推断需求、待确认问题、初步非目标；外部事实包含知识库事实、代码库事实。“知识库事实”必须先记录 `executed-hit | executed-no-match | unavailable` 状态；每个新 requirement 都必须真实执行知识检索，不允许未执行状态。若 complete 流程最终仍记录 `unavailable`，必须同时记录 `- 用户处置：已确认跳过知识库`，否则不得生成本产物。有效事实使用 `KB-FACT-*`，包含规范事实、来源文档及定位、版本/生效状态、适用范围、需求影响和置信度。“代码库事实”继续使用 `CODE-FACT-*`。
+需求分析包含明确需求、推断需求、待确认问题、初步非目标；外部事实包含知识库事实、代码库事实。”知识库事实”必须先记录 `executed-hit | executed-no-match | unavailable` 状态；每个新 requirement 都必须真实执行知识检索，不允许未执行状态。若 complete 流程最终仍记录 `unavailable`，必须同时记录 `- 用户处置：已确认跳过知识库`，否则不得生成本产物。有效事实使用 `KB-FACT-*`，包含规范事实、来源文档及定位、版本/生效状态、适用范围、需求影响、置信度和与输入关系。”代码库事实”继续使用 `CODE-FACT-*`（ai_workspace 项目资料与仓库规范文档统一归入此节），除上述字段外必须标注证据类别（项目规范 | 代码现状）和与输入关系。
+
+事实条目强制使用单行格式：`- <KB|CODE>-FACT-<编号>：<事实>；来源：<文档/证据定位>；证据类别：<项目规范|代码现状>（仅 CODE-FACT 必填）；与输入关系：<一致|补充|冲突>`。与输入关系为”冲突”的事实，其 ID 必须被”待确认问题”的冲突条目引用。
 
 按 scope 追加“初步前端用户故事/初步前端输出规范”或“初步后端用户故事/初步后端输出规范”。不得生成独立用户角色或验收标准汇总。
 
@@ -32,10 +34,12 @@ Frontmatter 只允许以上五个字段，不得增加来源路径、项目根
 
 状态变量、UI 状态、空数据、loading、error、disabled、错误文案和兜底行为必须优先采用 `kb-design-assist` 查明的当前有效项目规范，再核验设计系统、共享组件和同类实现；未查明时标为 unknown，不得把通用模式写成项目事实。影响产品行为或验收的 unknown 进入待确认问题；纯实现/代码落点 unknown 只保留在外部事实中。
 
-后端分页：以原始需求/用户确认为准。输入已给出每页条数允许值时原样记录；未说明时优先使用 `kb-design-assist` 返回的当前有效分页规范，仍未查明才按默认集合 `10`、`20`、`50`、`100` 生成。不得因此把知识库/API 文档的路径、方法、参数名、必填性、默认值、响应、错误码或 DTO 自动带入。Validator 不解析或推断分页允许值集合；该规则由生成流程和 forward-test 核对。
+后端分页：每页条数允许值参与「输入↔规范一致性核对」。输入与有效分页规范冲突（含集合差异、子集或超集）时，该冲突必须进入待确认问题澄清，用户裁决后以确认值为准；输入未说明时优先使用 `kb-design-assist` 返回的当前有效分页规范，仍未查明才按默认集合 `10`、`20`、`50`、`100` 生成。不得因此把知识库/API 文档的路径、方法、参数名、必填性、默认值、响应、错误码或 DTO 自动带入。Validator 不解析或推断分页允许值集合；该规则由生成流程和 forward-test 核对。
 
 Product Analysis 只记录验收关注点，不得出现正式 `AC-FE-*`、`AC-BE-*` 或 Given/When/Then 块。
 
-推断需求一律属于未确认产品内容。任何推断需求，以及原始需求、知识库、代码核验或分析过程中发现的含糊、缺失、冲突、多种合理解释或目标行为 unknown，都必须进入待确认问题并在后续逐题向用户澄清。纯代码位置、符号、复用点和实现方式不属于产品需求，继续留在代码库事实中。
+推断需求一律属于未确认产品内容。任何推断需求，以及原始需求、知识库、项目资料、仓库规范文档、代码核验或分析过程中发现的含糊、缺失、冲突、多种合理解释或目标行为 unknown，都必须进入待确认问题并在后续逐题向用户澄清。纯代码位置、符号、复用点和实现方式不属于产品需求，继续留在代码库事实中；纯实现/技术细节冲突只记录"与输入关系：冲突"的事实，不生成问题。
+
+「输入↔规范一致性核对」标记为"冲突"的条目必须进入待确认问题，采用如下结构：冲突描述（`输入声明：…` 与 `规范/代码声明：…` 成对列出）、`冲突来源：<KB-FACT-编号 | CODE-FACT-编号>`、影响范围（`common | frontend | backend | both`）与优先级（默认 P0）。冲突条目只陈述双方声明与来源，不得预选边；推荐职能由 Step 2 访谈轮承担。
 
-`no-clarification-required` 只允许在“推断需求”包含独立一行 `- 无未确认的推断需求。` 且“待确认问题”包含独立一行 `- 无待确认问题。` 时使用；待确认问题可另写理由，但不得出现问题标记、优先级、问句或其他未确认产品内容。`ready-for-clarification` 至少包含一个带优先级或问号的问题。
+`no-clarification-required` 只允许在”推断需求”包含独立一行 `- 无未确认的推断需求。` 且”待确认问题”包含独立一行 `- 无待确认问题。` 时使用；待确认问题可另写理由和一行 `- 一致性核对：…未发现冲突条目。`，但不得出现问题标记、优先级、问句或其他未确认产品内容；存在任何”与输入关系：冲突”的事实不得使用本状态。`ready-for-clarification` 至少包含一个带优先级或问号的问题。

package/skills/analyze-product-requirements/references/product-requirement-schema.md

@@ -16,7 +16,7 @@ Frontmatter 只允许以上五个字段，不得增加来源路径、项目根
 
 固定章节：需求概述、业务目标、需求范围、业务规则、决策追溯。需求范围包含“已确认范围”和“非目标”。`pending` 与 `complete` 均禁止“默认假设”章节。`pending` 文档另含“未决事项”；`complete` 文档禁止“未决事项”。不得生成独立用户角色、验收标准汇总、前后端契约、Open Questions、测试建议或独立边界 case 章节。
 
-Product Requirement 只描述目标产品行为，不承载知识检索或代码侦察记录。不得包含 `KB-FACT-*`、`CODE-FACT-*`、知识库/仓库文件路径、代码级类/函数/组件符号、模块调用关系、数据表名、证据位置、当前实现过程或实现算法。产品层的页面或组件名称仍可用于描述用户可见输出。当前有效知识库规范只能在不与用户决策或原始需求冲突时转换为项目既定的产品规则；代码库事实只可在经用户确认或被原始需求明确要求后转换为不含实现细节的产品规则。原始证据保留在 Product Analysis 或 Clarification。
+Product Requirement 只描述目标产品行为，不承载知识检索或代码侦察记录。不得包含 `KB-FACT-*`、`CODE-FACT-*`、知识库/仓库文件路径、代码级类/函数/组件符号、模块调用关系、数据表名、证据位置、当前实现过程或实现算法。产品层的页面或组件名称仍可用于描述用户可见输出。当前有效知识库规范在不与用户决策或原始需求冲突时可转换为项目既定的产品规则；与输入冲突时必须先经澄清、由用户裁决，裁决后方可转换。代码库事实只可在经用户确认或被原始需求明确要求后转换为不含实现细节的产品规则。原始证据保留在 Product Analysis 或 Clarification。
 
 机器校验至少拦截：`KB-FACT-*`、`CODE-FACT-*`、常见仓库路径（如 `src/`）、`*Controller/*Service/*Repository/*Handler/*Middleware` 符号，以及“证据位置”。其余实现泄漏仍按本契约人工遵守。知识库/仓库 API 技术惯例仅可在分析与澄清中查证；写入本产物的参数名、必填性、默认值必须来自原始需求或用户确认。
 
@@ -30,7 +30,7 @@ Product Requirement 只描述目标产品行为，不承载知识检索或代码
 
 状态变量、UI 状态、空数据、loading、error、disabled、错误文案和兜底行为必须遵循 `kb-design-assist` 或项目资料查明的当前有效规范，保留项目真实枚举、共享组件、文案和交互方式；影响产品行为的 unknown 未澄清前不得 complete，纯实现/代码落点 unknown 不进入本产物。
 
-后端分页允许值按“原始需求/用户确认 > 当前有效知识库分页规范 > 默认集合 `10`、`20`、`50`、`100`”确定。参数名、必填性、默认值和其他 API 契约必须来自原始需求或用户确认，不得从知识库/API 文档自动带入。Validator 不解析或推断分页允许值集合；该规则由生成流程和 forward-test 核对。
+后端分页允许值在澄清完成后按”用户确认/原始需求 > 当前有效知识库分页规范 > 默认集合 `10`、`20`、`50`、`100`”确定；输入与有效分页规范冲突（含集合差异、子集或超集）必须先经澄清、由用户裁决，未裁决不得 complete。参数名、必填性、默认值和其他 API 契约必须来自原始需求或用户确认，不得从知识库/API 文档自动带入。Validator 不解析或推断分页允许值集合；该规则由生成流程和 forward-test 核对。
 
 正式 `AC-FE-*` 或 `AC-BE-*` 作为四级标题嵌入对应输出规范。故事的验收标准引用必须与该规范中的 AC 完全一致；AC 遵循 `acceptance-criteria.md`。
 每个 AC ID 在整个 Product Requirement 中必须全局唯一，不得在不同故事或不同输出规范中复用。

package/skills/analyze-product-requirements/references/requirement-clarification-schema.md

@@ -53,7 +53,7 @@ Frontmatter 只允许以上六个字段，不得增加来源路径、项目根
 
 Clarification 与 Product Requirement 的状态必须一致：`pending` 只能配对 `pending`，`complete` 只能配对 `complete`。`--allow-pending` 只允许校验前一种内部中间状态；不带参数的交付校验只接受后一种。无需澄清的精简结构只能直接生成 complete，不存在 pending 精简结构。
 
-原始需求已经明确的产品行为作为 `source-requirement` 事实直接合并，不生成 `Q-*`、`DEC-Q-*` 或 `confirmed/user` 伪记录。代码事实用于查证现状，不作为产品决策来源；实现事实 unknown 不生成澄清问题。
+原始需求已经明确、与有效规范及代码现状核对一致且不存在冲突的产品行为作为 `source-requirement` 事实直接合并，不生成 `Q-*`、`DEC-Q-*` 或 `confirmed/user` 伪记录；输入与有效规范或代码现状冲突时不得免澄清。代码事实用于查证现状，不作为产品决策来源；实现事实 unknown 不生成澄清问题。
 
 `complete` 要求：
 

package/skills/analyze-product-requirements/scripts/test-validators.mjs

@@ -58,6 +58,7 @@ analysis_status: no-clarification-required
 - 无未确认的推断需求。
 ### 4.3 待确认问题
 - 无待确认问题。
+- 一致性核对：已逐条比对知识库、ai_workspace、仓库规范与代码现状，未发现冲突条目。
 - 理由：范围、权限和结果已经明确。
 ### 4.4 初步非目标
 - 不修改头像。
@@ -277,7 +278,7 @@ expectPass("valid V4 analysis", analysisValidator, [analysisPath, "--target", "f
 expectFail("analysis target mismatch", analysisValidator, [analysisPath, "--target", "backend"], "does not match");
 expectFail("analysis rejects extra frontmatter fields", analysisValidator, [variant("analysis-extra-frontmatter.md", analysis.replace("analysis_status: no-clarification-required", "analysis_status: no-clarification-required\nsource_path: /private/customer/prd.md"))], "unsupported field source_path");
 expectFail("analysis requires source identity", analysisValidator, [variant("analysis-no-source-identity.md", analysis.replace(`- 原始需求身份：${sourceIdentity}\n`, ""))], "原始需求身份");
-const analysisWithKnowledgeHit = analysis.replace("- 检索状态：executed-no-match。", "- 检索状态：executed-hit。\n- KB-FACT-001：采用项目统一空状态组件；来源为当前有效设计系统。");
+const analysisWithKnowledgeHit = analysis.replace("- 检索状态：executed-no-match。", "- 检索状态：executed-hit。\n- KB-FACT-001：采用项目统一空状态组件；来源为当前有效设计系统；与输入关系：补充。");
 writeFileSync(analysisPath, analysisWithKnowledgeHit);
 expectPass("analysis accepts executed-hit with KB fact", analysisValidator, [analysisPath, "--target", "frontend"]);
 writeFileSync(analysisPath, analysis);
@@ -290,6 +291,11 @@ const analysisWithKnowledgeUnavailable = analysis.replace("- 检索状态：exec
 writeFileSync(analysisPath, analysisWithKnowledgeUnavailable);
 expectPass("analysis unavailable accepts user skip confirmation", analysisValidator, [analysisPath, "--target", "frontend"]);
 writeFileSync(analysisPath, analysis);
+expectFail("analysis fact must declare 与输入关系", analysisValidator, [variant("analysis-fact-no-relation.md", analysis.replace("- 检索状态：executed-no-match。", "- 检索状态：executed-hit。\n- KB-FACT-001：采用项目统一空状态组件；来源为当前有效设计系统。"))], "must declare 与输入关系");
+expectFail("analysis CODE-FACT must declare 证据类别", analysisValidator, [variant("analysis-code-fact-no-evidence-class.md", analysis.replace("- 未提供代码仓库。", "- CODE-FACT-001：昵称校验已在表单层实现；证据位置：表单校验；与输入关系：一致。"))], "must declare 证据类别");
+expectFail("analysis conflict fact must be referenced by 待确认问题", analysisValidator, [variant("analysis-conflict-unreferenced.md", analysis.replace("- 检索状态：executed-no-match。", "- 检索状态：executed-hit。\n- KB-FACT-001：昵称允许 1–30 字符；来源：昵称规范 §2；与输入关系：冲突。"))], "not referenced by 待确认问题");
+expectFail("no-clarification analysis rejects conflict facts", analysisValidator, [variant("analysis-conflict-no-clarification.md", analysis.replace("- 检索状态：executed-no-match。", "- 检索状态：executed-hit。\n- KB-FACT-001：昵称允许 1–30 字符；来源：昵称规范 §2；与输入关系：冲突。\n- P0：昵称长度冲突；冲突描述：输入声明「2–20 字符」vs 规范声明「1–30 字符」；冲突来源：KB-FACT-001；影响范围：frontend。"))], "cannot contain facts marked 与输入关系：冲突");
+expectFail("no-clarification analysis requires 一致性核对 conclusion", analysisValidator, [variant("analysis-no-check-line.md", analysis.replace("- 一致性核对：已逐条比对知识库、ai_workspace、仓库规范与代码现状，未发现冲突条目。\n", ""))], "must record a 一致性核对 line");
 expectFail("analysis rejects formal AC", analysisValidator, [variant("analysis-ac.md", analysis.replace("验收关注点：", "验收关注点：AC-FE-001 "))], "must use acceptance concerns");
 expectFail("analysis requires matching spec", analysisValidator, [variant("analysis-no-spec.md", analysis.replace("### FE-US-001 修改昵称\n- 页面/组件", "### FE-US-002 修改昵称\n- 页面/组件"))], "missing output specification");
 expectFail("analysis rejects standalone roles", analysisValidator, [variant("analysis-roles.md", analysis.replace("## 4. 需求分析", "## 用户角色\n- 已登录用户。\n## 4. 需求分析"))], "must not contain standalone");
@@ -488,6 +494,10 @@ expectPass("complete question clarification with DEC markers", clarificationVali
 expectFail("complete clarification rejects unformed final decision", clarificationValidator, [analysisPath, variant("clarification-unformed-decision.md", completeQuestionClarification.replace("- 最终决策：保存成功后展示项目统一成功提示", "- 最终决策：未形成")), requirementPath], "must contain a formed final decision");
 expectPass("requirement with DEC markers", requirementValidator, [requirementPath, "--target", "frontend"]);
 expectFail("complete clarification requires shared-understanding marker", clarificationValidator, [analysisPath, variant("clarification-no-shared.md", completeQuestionClarification.replace("- 共同理解：已确认\n", "")), requirementPath], "共同理解：已确认");
+const conflictReadyAnalysis = readyAnalysis
+  .replace("- P1：保存成功后使用哪种反馈？", "- P0：昵称长度冲突；冲突描述：输入声明「2–20 字符」vs 规范声明「1–30 字符」；冲突来源：KB-FACT-001；影响范围：frontend。")
+  .replace("- 检索状态：executed-no-match。", "- 检索状态：executed-hit。\n- KB-FACT-001：昵称允许 1–30 字符；来源：昵称规范 §2；与输入关系：冲突。");
+expectFail("complete clarification must cover PA conflict facts", clarificationValidator, [variant("conflict-analysis-uncovered.md", conflictReadyAnalysis), clarificationPath, requirementPath], "must be covered by a Q-* record");
 expectFail("analysis frontend output requires page route", analysisValidator, [variant("analysis-no-route.md", analysis.replace("- 页面路由：/account/profile\n", "")), "--target", "frontend"], "missing field 页面路由");
 expectFail("analysis route must be a product path", analysisValidator, [variant("analysis-bad-route.md", analysis.replace("- 页面路由：/account/profile", "- 页面路由：ProfileRoute 组件")), "--target", "frontend"], "must start with /");
 const embeddedRouteAnalysis = analysis.replace("- 页面路由：/account/profile", "- 页面路由：不适用；嵌入 /account/profile 页面");