project-tiny-context-harness 0.2.70 → 0.2.71

package/assets/skills/context_surface_contract/SKILL.md

@@ -67,12 +67,13 @@ Use when turning audit findings or user decisions into Context candidates.
 
 Output:
 
-- Project-level Product Surface Contract candidate when responsibilities cross surfaces or areas.
-- Area-level Screen Contract candidate when ownership belongs inside one domain.
-- `context.toml` candidate registration with `role = "contract"` when durable registration is needed.
-- `global.md#Context Index` candidate entry when a new Context file is added.
-- Verification candidate for repeatable surface checks.
-- Repo-local Skill task-block candidate when the user wants project-specific enforcement.
+- Project-level Product Surface Contract candidate when responsibilities cross surfaces or areas.
+- Area-level Screen Contract candidate when ownership belongs inside one domain.
+- `context.toml` candidate registration with `role = "contract"` when durable registration is needed.
+- `global.md#Context Index` candidate entry when a new Context file is added.
+- Verification candidate for repeatable surface checks.
+- Source-to-Context Coverage candidate when an external product, architecture, technical or acceptance source changes durable surface responsibility.
+- Repo-local Skill task-block candidate when the user wants project-specific enforcement.
 
 Do not assume business responsibilities from current code shape alone. Ask for confirmation if the candidate would silently choose between competing product or information-architecture meanings.
 
@@ -104,11 +105,13 @@ Use after implementation or during review.
 
 Output:
 
-- Surface Contract Conformance.
-- Remaining Drift.
-- Missing Context.
-- Implementation Drift.
-- Verification run / not_run / failed.
+- Surface Contract Conformance.
+- Source-to-Context Coverage status when a plan surface exists.
+- Context-to-Implementation Binding status when a plan surface exists.
+- Remaining Drift.
+- Missing Context.
+- Implementation Drift.
+- Verification run / not_run / failed.
 
 Do not store one-off evidence, screenshots, logs, raw outputs or implementation summaries in Context.
 
@@ -123,7 +126,8 @@ For each touched surface, answer only what is relevant:
 - What must move to drilldown, diagnostics, operations, evidence or technical detail?
 - Which long-running or mutating actions require task id, progress, retry, import, recovery or history?
 - Which empty, loading, stale, unavailable, fixture or fallback states matter?
-- What validation path can prove conformance?
+- What validation path can prove conformance?
+- If this came from an external plan/source, which source constraints are covered by existing Context, require new Context, are task-local only, are explicitly out of scope, need user decision or remain under-scoped?
 
 ## Repo-Local Task Block Candidate
 
@@ -143,11 +147,13 @@ For any task touching user-facing surfaces, information placement, forms, filter
 - Main Surface Forbids: `<backend fields, raw payloads, diagnostics, debug ids, fake states, etc.>`
 - Drilldown Ownership: `<details / evidence / operations / diagnostics / technical details>`
 - Long Task State Requirement: `<run id, progress, retry, recovery, import, history, or none>`
-- Context Delta: `<none | required>`
-- Verification: `<view-model test / component test / browser smoke / CLI smoke / manual check>`
-```
-
-Do not add this task block to package-managed default Skills as a universal gate. Projects opt in through separate project-local Skills.
+- Context Delta: `<none | required>`
+- Verification: `<view-model test / component test / browser smoke / CLI smoke / manual check>`
+- Source-to-Context Coverage: `<covered | new_context_required | context_updated | task_local_only | out_of_scope_explicit | needs_user_decision | under_scoped>`
+- Context-to-Implementation Binding: `<bound | partial | missing | blocked | out_of_scope_explicit | needs_user_decision | contradicted_by_current_state>`
+```
+
+Do not add this task block to package-managed default Skills as a universal gate. Projects opt in through separate project-local Skills.
 
 ## Implementation Alignment
 
@@ -159,7 +165,9 @@ When implementation is also requested, align code with the Product Surface Contr
 - Tests should assert user-facing state semantics, not only backend field plumbing.
 - Browser, app, CLI or game smoke checks should validate actual surface behavior when feasible.
 
-Final handoff should include concise `Surface Contract Conformance`: contract source, implementation alignment, remaining drift and verification status.
+Final handoff should include concise `Surface Contract Conformance`: contract source, implementation alignment, remaining drift and verification status.
+
+If a `plan.md` or equivalent temporary plan surface exists, conformance must also check its Source-to-Context Coverage and Context-to-Implementation Binding. Remaining `under_scoped` or unresolved `new_context_required` rows mean the implementation cannot be described as fully aligned to the source surface responsibilities. Non-bound surface implementation rows mean it cannot be described as fully aligned to Context; component, modal, viewmodel or unit evidence alone cannot prove main-surface ownership.
 
 ## Output Boundaries
 
@@ -167,5 +175,5 @@ Final handoff should include concise `Surface Contract Conformance`: contract so
 - Do not update Context for ordinary CSS tweaks, copy edits or one-off UI bug fixes unless durable surface responsibility changes.
 - Do not treat current backend fields, enums, JSON, screenshots or terminal output as product intent.
 - Do not invent rationale; rejected alternatives or tradeoffs belong in Context only when they are stable enough to affect future surface decisions.
-- Do not add a validator, edit-order gate or package-level mandatory Surface Contract gate.
+- Do not add a surface-specific validator, edit-order gate or package-level mandatory Surface Contract gate. The generic plan-contract validator may check declared surface binding consistency when a temporary plan surface exists.
 - Do not include business-domain examples in this package-managed Skill.

package/assets/skills/context_uiux_design/SKILL.md

@@ -25,7 +25,7 @@ Project-specific UI/UX and visual design rules belong in a separate project-loca
    - 若缺失且本任务改变 durable surface responsibility，输出 `Surface Contract Delta: required`，把界面职责写入 `project_context/**`；视觉 token、颜色、字体、间距、圆角和视觉 rationale 仍写入 `DESIGN.md`。
 5. 涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或加载/空态/错误态等 UI 控件时，用“控件交互框架”检查控件语义、反馈状态、校验、错误预防、可供性和信息密度；这只是通用判断框架，不是固定控件处方。
 6. 界面职责、流程归属和长期交互契约以 `project_context/**` 为准；`DESIGN.md` 负责视觉 token 和视觉 rationale；代码、截图和搜索结果只说明当前实现状态。Context 决定“应该是什么”，代码和截图揭示“现在是什么”，代码不能静默重定义 Context。
-7. 设计判断或第一处实现编辑前，若任务涉及页面职责、流程边界、信息架构、交互契约、状态或调度语义、可访问性约束、设计验证关键路径或部署关键路径，先编译当前任务契约；契约第一段用 `Context Delta: none|required` 完成唯一正式长期事实判断，再写本次 `Task Contract`。
+7. 设计判断或第一处实现编辑前，若任务涉及页面职责、流程边界、信息架构、交互契约、状态或调度语义、可访问性约束、设计验证关键路径或部署关键路径，先编译当前任务契约；契约第一段用 `Context Delta: none|required` 完成唯一正式长期事实判断，再写本次 `Task Contract`。如果输入包含产品方案、架构方案、技术方案、界面方案或验收方案，先在 `plan.md` 或等价临时计划面做 Source-to-Context Coverage，确认方案中的 durable surface / IA / interaction / verification constraints 已被现有 Context 或 `DESIGN.md` 覆盖、需要更新、仅属 task-local、显式 out-of-scope、需要用户决策或仍 under-scoped。
 8. 普通 UI bug、局部样式或 CSS 修复、测试修复或探索性 spike 不更新 Context，可先改代码；一旦形成长期交互或视觉结论，继续对齐或交付前必须回写 Context 或 `DESIGN.md`。不要把 Context 机械补成代码改动摘要。
 9. 如果二者冲突，显式标记为实现漂移、缺失工作或 Context 过期。
 10. 如果涉及已有 UI，优先结合代码入口、运行截图或用户提供的参考图来描述差异。
@@ -46,13 +46,18 @@ Project-specific UI/UX and visual design rules belong in a separate project-loca
 - `Context Delta` 必须先出现，取值为 `none` 或 `required`：
   - `none`：本次只是按既有 Context / `DESIGN.md` / 设计原则落地，不新增长期事实。
   - `required`：说明长期事实类型、应写入的 Context / role 或 `DESIGN.md` 位置、需要沉淀的事实，以及明确不写入 Context 的一次性内容。
-- `Task Contract` 用短列表说明页面 / 组件任务、用户判断、主信息和辅助信息归属、动作层级、输入语义、loading / empty / no results / stale / error / degraded / success 状态、布局稳定性、非目标和验收入口。
-- 触及 Product Surface 时，`Task Contract` 同时说明 surface platform、primary user question、main allows/forbids、drilldown ownership、long-task state requirement 和 verification；代码字段、枚举、JSON 或截图只是实现证据，不是产品职责来源。
-- 对长任务、多页面/组件、多 agent、容易发生 `Context Delta` 调头或多轮截图 / 手动验证的任务，可以用 `plan.md` 或等价临时计划面暂存 `Context Delta`、`Task Contract`、`Implementation Steps` 和 `Contract Conformance`；它只是临时执行缓存。
-- `plan.md` 中出现的长期界面、交互或视觉事实必须提炼回 `project_context/**` 或 `DESIGN.md`；否则不要把临时计划当作事实源、交付产物或后续引用依据。
-- `Context Delta: required` 时先更新 `project_context/**` 或 `DESIGN.md`，再继续实现；`none` 时直接按 Task Contract 实现。
-- `Contract Conformance` 是交付前的软检查：实现偏差修实现，契约遗漏回 Task Contract，长期事实缺失回 `Context Delta` 并先更新 Context / `DESIGN.md`。
-- 不为普通 UI bug、局部 CSS 修复、小重构、测试修复或探索性 spike 强制编译任务契约。
+- `Task Contract` 用短列表说明页面 / 组件任务、用户判断、主信息和辅助信息归属、动作层级、输入语义、loading / empty / no results / stale / error / degraded / success 状态、布局稳定性、非目标和验收入口。
+- 触及 Product Surface 时，`Task Contract` 同时说明 surface platform、primary user question、main allows/forbids、drilldown ownership、long-task state requirement 和 verification；代码字段、枚举、JSON 或截图只是实现证据，不是产品职责来源。
+- 对长任务、多页面/组件、多 agent、外部产品/架构/技术/界面/验收方案输入、容易发生 `Context Delta` 调头或多轮截图 / 手动验证的任务，使用 `plan.md` 或等价临时计划面暂存 `Source-to-Context Coverage`、`Context-to-Implementation Binding`、`Context Delta`、`Task Contract`、`Implementation Steps` 和 `Contract Conformance`；它只是临时执行缓存。
+- small code task 指现有 Context / `DESIGN.md` 已足够、且不改变 durable product / architecture / API-schema / runtime-state / verification-deployment / security-redaction / surface ownership 事实的局部实现任务；它按语义风险判断，不按代码行数判断，不应创建 `plan.md`、完整 trace tables、Source-to-Context Coverage 或 Context-to-Implementation Binding，除非它发现长期事实变化或扩展成高风险工作。
+- `Source-to-Context Coverage` 表使用字段：`Source item | Durable constraint | Type | Existing Context Hit | Context action | Owning Context | Coverage status`。这张表只回答 source 约束是否进入或命中 Context / `DESIGN.md`，不写实现路径。
+- `Coverage status` 取值：`covered`、`new_context_required`、`context_updated`、`task_local_only`、`out_of_scope_explicit`、`needs_user_decision`、`under_scoped`。存在 `under_scoped` 或未处理的 `new_context_required` / `needs_user_decision` 时，不能声称已按方案完整实现。
+- `Context-to-Implementation Binding` 表使用字段：`Context fact | Implementation obligation | Expected surfaces | Implemented paths | Forbidden shortcuts | Verification path | Binding status`。
+- `Binding status` 取值：`bound`、`partial`、`missing`、`blocked`、`out_of_scope_explicit`、`needs_user_decision`、`contradicted_by_current_state`。UI/surface 项不能只用 component / viewmodel / mock / unit evidence 冒充 `bound`。
+- `plan.md` 中出现的长期界面、交互或视觉事实必须提炼回 `project_context/**` 或 `DESIGN.md`；否则不要把临时计划当作事实源、交付产物或后续引用依据。
+- `Context Delta: required` 时先更新 `project_context/**` 或 `DESIGN.md`，再继续实现；`none` 时直接按 Task Contract 实现。
+- `Contract Conformance` 是交付前的软检查：实现偏差修实现，契约遗漏回 Task Contract，长期事实缺失或 source coverage under-scoped 回 `Context Delta` 并先更新 Context / `DESIGN.md`。
+- 不为 small code task、普通 UI bug、局部 CSS 修复、小重构、测试修复或探索性 spike 强制编译任务契约。
 
 ## 信息呈现校准
 

package/assets/skills/superpowers-long-task/SKILL.md

@@ -104,6 +104,7 @@ The prompt must require the future executor to create or initialize `tmp/ty-cont
 Each behavior-affecting Technical Realization Plan item must have a trace entry with:
 
 - plan item id and plan requirement.
+- acceptance ids covered by the plan item when applicable.
 - expected surfaces.
 - implemented paths.
 - missing paths.
@@ -112,6 +113,8 @@ Each behavior-affecting Technical Realization Plan item must have a trace entry
 - scope assessment.
 - status.
 - drift.
+- Context fact refs when Context Delta is required.
+- For Product Surface, IA or architecture-migration items: conformance type, owner surface, required user paths, forbidden primary surfaces, real page evidence, negative surface checks and default visibility requirement.
 
 Allowed plan-conformance statuses:
 
@@ -122,6 +125,7 @@ Allowed plan-conformance statuses:
 - `blocked`
 - `scope_changed_requires_user_approval`
 - `contradicted_by_current_state`
+- `out_of_scope_NA`
 
 Hard rules:
 
@@ -130,6 +134,7 @@ Hard rules:
 - A local audit cannot narrow plan scope or mark completion.
 - Scope correction requires explicit user approval or a revised product/architecture source, Technical Realization Plan and checklist.
 - Every behavior-affecting plan section must have an implementation trace entry.
+- Product Surface, IA or architecture-migration rows cannot be complete without owner surface, required user paths, real page evidence, negative surface checks for forbidden primary surfaces and Context fact refs when Context Delta is required.
 - Any `partial`, `sampled_only`, `not_implemented`, unresolved blocker, unapproved scope change or current contradiction prevents overall done.
 
 ## Acceptance Evidence Gate
@@ -139,6 +144,7 @@ The prompt must require the future executor to generate `tmp/ty-context/plan-acc
 Each AC verdict entry must include:
 
 - AC id or acceptance item.
+- related plan item ids when applicable.
 - status.
 - required evidence.
 - fresh evidence.
@@ -153,14 +159,18 @@ Allowed AC statuses:
 - `blocked`
 - `not_run`
 - `invalidated`
+- `out_of_scope_NA`
 
 Hard rules:
 
 - Final completion requires an AC-by-AC final acceptance verdict.
+- Before any completion claim, run `ty-context validate-plan-acceptance tmp/ty-context/plan-acceptance/<plan-slug>`; failure prevents final complete and must produce partial / blocker / missing-evidence output.
+- `validate-plan-acceptance` rejects contradictory matrix/verdict JSON, weak-proof complete rows, missing cross-references and declared surface/architecture binding gaps; it checks artifact consistency and references, not product quality.
 - Current API/UI/runtime/data/test contradictions override historical passing evidence.
 - local audit, subagent summaries, final result card text, passing test logs, stale artifacts, partial smoke, dry-run or sampled paths cannot prove completion by themselves.
 - Any current contradiction downgrades the affected AC and overall status.
 - Scope narrowing in audit does not modify acceptance unless the user approved a revised source/plan/checklist.
+- `out_of_scope_NA` requires explicit reason and source reference; arbitrary prose cannot waive missing evidence.
 
 ## Evidence Layer Separation
 
@@ -220,7 +230,7 @@ Bind the target prompt to the official Skill names and their documented roles:
 - Prefer `superpowers:subagent-driven-development` when subagents are available.
 - Use `superpowers:executing-plans` when executing a written plan without the same-session subagent workflow.
 - Plan or AC behavior gap -> TDD: each behavior gap uses `superpowers:test-driven-development` to write a failing test, observe failure, then implement minimally.
-- Before any completion claim, use `superpowers:verification-before-completion` against both `plan-conformance-matrix.*` and `final-acceptance-verdict.*` with fresh evidence.
+- Before any completion claim, use `superpowers:verification-before-completion` against both `plan-conformance-matrix.*` and `final-acceptance-verdict.*` with fresh evidence, then run `ty-context validate-plan-acceptance tmp/ty-context/plan-acceptance/<plan-slug>`.
 - review / finish cannot override the plan-conformance matrix or full checklist; if either gate is unsatisfied, continue implementation or report blockers.
 
 If Superpowers is missing, install it through the current platform's official Superpowers installation path. If installation is blocked by permissions, network or platform limits, record the blocker in local audit and do not count it as complete.
@@ -284,7 +294,7 @@ Superpowers 输入包：
 7. 每个实现 slice 后更新 matrix 和 audit。
 8. Candidate done 前跑 Plan Conformance Gate：测试通过不等于按图纸完成；sampled path 不等于 full implementation；每个行为 plan item 必须有 code/API/UI/runtime/test/evidence trace。
 9. 再跑 Acceptance Evidence Gate：按验收清单生成 final verdict；current API/UI/runtime/data/test contradiction 高于历史通过记录。
-10. 完成声明前用 superpowers:verification-before-completion 同时检查 matrix 和 verdict；两关不过就继续或报告 blocker。
+10. 完成声明前用 superpowers:verification-before-completion 检查 matrix/verdict，并运行 ty-context validate-plan-acceptance tmp/ty-context/plan-acceptance/<plan-slug>；失败就继续或报告 blocker。
 
 权限/卡点：在当前平台/仓库/工具/用户已授权权限内最大自主推进；已授权 sudo/gsudo/admin elevation 先尝试，不算用户阻塞。只有本地无法解决的账号/凭证/真实环境/人工审批/敏感字段等才暂停，并给最小用户执行清单（具体页面/系统、字段位置、脱敏/勿发值、拿到后下一步）。
 禁止完成于：local audit、subagent summary、final card、只改代码/计划、只跑部分测试、旧/部分/抽样证据、runtime 未演练、artifact 未被 validator accepted、API/UI 未 reflected、未批准 scope narrowing、任何 API/UI/data/runtime/test 矛盾。
@@ -318,10 +328,10 @@ Execution order:
 7. After each slice, update matrix and audit.
 8. Before candidate done, run Plan Conformance Gate: passing tests does not prove plan conformance; sampled path does not prove full implementation; every behavior plan item needs code/API/UI/runtime/test/evidence trace.
 9. Then run Acceptance Evidence Gate: generate final verdict from the checklist; current API/UI/runtime/data/test contradictions override old passing evidence.
-10. Before completion, use superpowers:verification-before-completion against both matrix and verdict; if either gate fails, continue or report blockers.
+10. Before completion, run superpowers:verification-before-completion on matrix/verdict and ty-context validate-plan-acceptance tmp/ty-context/plan-acceptance/<plan-slug>; if either fails, continue/report blockers.
 
 Autonomy/blockers: within current platform/repo/tool/user-authorized permissions, do all safe self-service discovery/execution/verification. Authorized sudo/gsudo/admin elevation is not a user blocker; try it first. Pause only for locally unsatisfiable account/credential/real-env/human-approval/sensitive-field needs; give exact page/system, field location, redaction/do-not-send values and next agent step.
-Never complete on: local audit, subagent summary, final card, code-only/plan-only work, partial tests, stale/partial/sampled evidence, unexercised runtime, artifact not accepted by validator, API/UI not reflected, unapproved scope narrowing or any API/UI/data/runtime/test contradiction.
+Never complete on: local audit, subagent summary, final card, code-only/plan-only work, partial tests, stale/partial/sampled evidence, unexercised runtime, artifact not accepted by validator, API/UI not reflected, missing validate-plan-acceptance pass, unapproved scope narrowing or any API/UI/data/runtime/test contradiction.
 ```
 
 Before final response, check the prompt length. If it exceeds 3850 characters, tighten wording while preserving paths, input roles, official Superpowers skill names, Product Context Delta, Technical Context Delta, plan-conformance matrix, final verdict, state machine, UI gate, blockers and invalid evidence.

package/dist/commands/index.js

@@ -18,6 +18,8 @@ export const commands = {
     "validate-context": (args) => validate(["validate-context", ...args]),
     "validate-code-modularity": (args) => validate(["validate-code-modularity", ...args]),
     "validate-harness": (args) => validate(["validate-harness", ...args]),
+    "validate-plan-contract": (args) => validate(["validate-plan-contract", ...args]),
+    "validate-plan-acceptance": (args) => validate(["validate-plan-acceptance", ...args]),
     package: packageSource
 };
 export function help() {
@@ -34,8 +36,12 @@ export function help() {
                        Export temporary Context, code snapshot or bounded Source Pack artifacts
   validate <gate>      Run a Harness validation gate
   validate-context     Validate Minimal Context fact-source recoverability
-  validate-code-modularity
-                       Enforce touched handwritten source file modularity
-  validate-harness     Run validate-context and validate-code-modularity
+  validate-code-modularity
+                       Enforce touched handwritten source file modularity
+  validate-harness     Run validate-context and validate-code-modularity
+  validate-plan-contract <plan.md|dir>
+                       Validate workflow-contract plan surface consistency
+  validate-plan-acceptance <dir>
+                       Validate plan-conformance matrix and final verdict consistency
   package <subcommand> Maintain package canonical source`);
 }

package/dist/commands/validate.js

@@ -1,7 +1,7 @@
 import { runValidator } from "../lib/validators.js";
 export async function validate(args) {
     const gate = args[0] ?? "validate-harness";
-    const report = await runValidator(process.cwd(), gate);
+    const report = await runValidator(process.cwd(), gate, args.slice(1));
     for (const line of report.info) {
         console.log(line);
     }

package/dist/lib/plan-acceptance-json.d.ts

@@ -0,0 +1,15 @@
+export declare const MATRIX_STATUSES: Set<string>;
+export declare const AC_STATUSES: Set<string>;
+export declare const NON_COMPLETE_MATRIX: Set<string>;
+export declare const NON_COMPLETE_AC: Set<string>;
+export declare function findJsonFile(targetDir: string, marker: string): Promise<string | undefined>;
+export declare function readJson(file: string, errors: string[]): Promise<unknown>;
+export declare function findRows(value: unknown, preferredKeys: string[]): Record<string, unknown>[];
+export declare function overallStatus(value: unknown): string;
+export declare function statusOf(row: Record<string, unknown>): string;
+export declare function isOutOfScope(row: Record<string, unknown>): boolean;
+export declare function contextDeltaRequired(value: unknown): boolean;
+export declare function isSurfaceConformanceRow(row: Record<string, unknown>): boolean;
+export declare function hasExplicitNoTestScope(row: Record<string, unknown>): boolean;
+export declare function assertSurfaceConformance(row: Record<string, unknown>, label: string, errors: string[]): void;
+export declare function assertStructuredNa(row: Record<string, unknown>, label: string, errors: string[]): void;

package/dist/lib/plan-acceptance-json.js

@@ -0,0 +1,129 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { readText } from "./fs.js";
+import { isBlankish, primitiveText, valuesAsArray } from "./plan-validator-common.js";
+export const MATRIX_STATUSES = new Set([
+    "complete",
+    "partial",
+    "sampled_only",
+    "not_implemented",
+    "blocked",
+    "scope_changed_requires_user_approval",
+    "contradicted_by_current_state",
+    "out_of_scope_NA"
+]);
+export const AC_STATUSES = new Set(["complete", "partial", "blocked", "not_run", "invalidated", "out_of_scope_NA"]);
+export const NON_COMPLETE_MATRIX = new Set([
+    "partial",
+    "sampled_only",
+    "not_implemented",
+    "blocked",
+    "scope_changed_requires_user_approval",
+    "contradicted_by_current_state"
+]);
+export const NON_COMPLETE_AC = new Set(["partial", "blocked", "not_run", "invalidated"]);
+export async function findJsonFile(targetDir, marker) {
+    const entries = await fs.readdir(targetDir, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".json") && entry.name.includes(marker))
+        .map((entry) => path.join(targetDir, entry.name))
+        .sort()[0];
+}
+export async function readJson(file, errors) {
+    try {
+        return JSON.parse(await readText(file));
+    }
+    catch (error) {
+        errors.push(`${file} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+}
+export function findRows(value, preferredKeys) {
+    if (Array.isArray(value) && value.every((item) => item && typeof item === "object" && !Array.isArray(item))) {
+        return value;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return [];
+    }
+    const object = value;
+    for (const key of preferredKeys) {
+        const rows = findRows(object[key], []);
+        if (rows.length > 0) {
+            return rows;
+        }
+    }
+    return Object.values(object).map((item) => findRows(item, [])).sort((a, b) => b.length - a.length)[0] ?? [];
+}
+export function overallStatus(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return "";
+    }
+    const object = value;
+    return String(object.overall_status ?? object.overallStatus ?? object.status ?? "").trim();
+}
+export function statusOf(row) {
+    return String(row.status ?? "").trim();
+}
+export function isOutOfScope(row) {
+    return statusOf(row) === "out_of_scope_NA" || /out[_ -]?of[_ -]?scope|n\/a|not applicable/i.test(primitiveText(row));
+}
+export function contextDeltaRequired(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const object = value;
+    return [
+        object.context_delta,
+        object.contextDelta,
+        object.product_context_delta,
+        object.productContextDelta,
+        object.technical_context_delta,
+        object.technicalContextDelta
+    ].some((item) => /\brequired\b/i.test(primitiveText(item)));
+}
+export function isSurfaceConformanceRow(row) {
+    return (/\b(product[_ -]?surface|surface|ia|information[_ -]?architecture|architecture[_ -]?migration|ui)\b/i.test(primitiveText(row.conformance_type)) ||
+        !isBlankish(row.owner_surface) ||
+        !isBlankish(row.forbidden_primary_surfaces) ||
+        !isBlankish(row.required_user_paths));
+}
+export function hasExplicitNoTestScope(row) {
+    return /\b(no[- ]?test|no automated test|test out of scope|tests? not required)\b/i.test(primitiveText([row.test_scope, row.no_test_scope, row.tests]));
+}
+export function assertSurfaceConformance(row, label, errors) {
+    if (isBlankish(row.owner_surface)) {
+        errors.push(`${label} is surface/architecture conformance but owner_surface is empty`);
+    }
+    if (isBlankish(row.required_user_paths)) {
+        errors.push(`${label} is surface/architecture conformance but required_user_paths is empty`);
+    }
+    if (isBlankish(row.real_page_evidence)) {
+        errors.push(`${label} is surface/architecture conformance but real_page_evidence is empty`);
+    }
+    if (isBlankish(row.context_fact_refs)) {
+        errors.push(`${label} is surface/architecture conformance but context_fact_refs is empty`);
+    }
+    if (!isBlankish(row.forbidden_primary_surfaces) && isBlankish(row.negative_surface_checks)) {
+        errors.push(`${label} declares forbidden_primary_surfaces but negative_surface_checks is empty`);
+    }
+    const userPathText = primitiveText([row.required_user_paths, row.primary_user_paths]);
+    for (const forbiddenSurface of valuesAsArray(row.forbidden_primary_surfaces)) {
+        if (userPathText.toLowerCase().includes(forbiddenSurface.toLowerCase())) {
+            errors.push(`${label} routes a required/primary user path through forbidden surface: ${forbiddenSurface}`);
+        }
+    }
+    if (row.default_visibility_required === true && !mentionsDefaultVisibility(primitiveText(row.real_page_evidence))) {
+        errors.push(`${label} requires default visibility but real_page_evidence does not record default-visible proof`);
+    }
+}
+export function assertStructuredNa(row, label, errors) {
+    if (isBlankish(row.na_reason) && isBlankish(row.out_of_scope_reason)) {
+        errors.push(`${label} is out_of_scope_NA but lacks na_reason or out_of_scope_reason`);
+    }
+    if (isBlankish(row.scope_source) && isBlankish(row.approval_source) && isBlankish(row.source_reference)) {
+        errors.push(`${label} is out_of_scope_NA but lacks scope_source, approval_source or source_reference`);
+    }
+}
+function mentionsDefaultVisibility(value) {
+    return /\b(default[- ]?visible|visible by default|primary entry|first-level|top-level|main entry)\b/i.test(value);
+}

package/dist/lib/plan-acceptance-validator.d.ts

@@ -0,0 +1,2 @@
+import type { ValidatorReport } from "./validators.js";
+export declare function validatePlanAcceptance(projectRoot: string, args?: string[]): Promise<ValidatorReport>;

package/dist/lib/plan-acceptance-validator.js

@@ -0,0 +1,187 @@
+import { pathExists } from "./fs.js";
+import { AC_STATUSES, MATRIX_STATUSES, NON_COMPLETE_AC, NON_COMPLETE_MATRIX, assertStructuredNa, assertSurfaceConformance, contextDeltaRequired, findJsonFile, findRows, hasExplicitNoTestScope, isOutOfScope, isSurfaceConformanceRow, overallStatus, readJson, statusOf } from "./plan-acceptance-json.js";
+import { assertReferencedPathsExist, hasRealPageEvidence, isBlankish, isUiFacing, primitiveText, repoRelative, resolveInputDir, valuesAsArray, weakProofHit } from "./plan-validator-common.js";
+export async function validatePlanAcceptance(projectRoot, args = []) {
+    const info = [];
+    const errors = [];
+    const targetDir = await resolveInputDir(projectRoot, args[0], "tmp/ty-context/plan-acceptance");
+    if (!(await pathExists(targetDir))) {
+        return { info, errors: [`plan acceptance directory is missing: ${repoRelative(projectRoot, targetDir)}`] };
+    }
+    const matrixFile = await findJsonFile(targetDir, "plan-conformance-matrix");
+    const verdictFile = await findJsonFile(targetDir, "final-acceptance-verdict");
+    if (!matrixFile) {
+        errors.push(`plan acceptance directory is missing *-plan-conformance-matrix.json`);
+    }
+    if (!verdictFile) {
+        errors.push(`plan acceptance directory is missing *-final-acceptance-verdict.json`);
+    }
+    if (!matrixFile || !verdictFile) {
+        return { info, errors };
+    }
+    const matrix = await readJson(matrixFile, errors);
+    const verdict = await readJson(verdictFile, errors);
+    if (matrix === undefined || verdict === undefined) {
+        return { info, errors };
+    }
+    const matrixRows = findRows(matrix, ["plan_items", "items", "matrix", "entries", "plan_conformance"]);
+    const verdictRows = findRows(verdict, ["acceptance_items", "ac_verdicts", "verdicts", "items", "entries", "acs"]);
+    await validateMatrixRows(projectRoot, matrixRows, overallStatus(matrix), errors);
+    await validateVerdictRows(projectRoot, verdictRows, overallStatus(verdict), errors);
+    validateCrossReferences(matrixRows, verdictRows, errors);
+    validateContextFactReferences(matrix, verdict, matrixRows, verdictRows, errors);
+    info.push(`checked plan acceptance ${repoRelative(projectRoot, targetDir)} matrix_rows=${matrixRows.length} verdict_rows=${verdictRows.length}`);
+    if (errors.length === 0) {
+        info.push("Plan acceptance validation passed");
+    }
+    return { info, errors };
+}
+async function validateMatrixRows(projectRoot, rows, overall, errors) {
+    if (rows.length === 0) {
+        errors.push("plan-conformance matrix has no trace rows");
+    }
+    for (const [index, row] of rows.entries()) {
+        const label = `plan-conformance matrix row ${index + 1}`;
+        const status = statusOf(row);
+        if (!MATRIX_STATUSES.has(status)) {
+            errors.push(`${label} has unsupported status: ${status || "<empty>"}`);
+        }
+        if (status === "out_of_scope_NA") {
+            assertStructuredNa(row, label, errors);
+        }
+        if (overall === "complete" && NON_COMPLETE_MATRIX.has(status)) {
+            errors.push(`${label} is ${status} but overall_status is complete`);
+        }
+        if (status === "complete" && !isBlankish(row.missing_paths)) {
+            errors.push(`${label} is complete but missing_paths is not empty`);
+        }
+        if (status === "complete") {
+            if (isBlankish(row.plan_requirement)) {
+                errors.push(`${label} is complete but plan_requirement is empty`);
+            }
+            if (isBlankish(row.expected_surfaces)) {
+                errors.push(`${label} is complete but expected_surfaces is empty`);
+            }
+            if (isBlankish(row.implemented_paths)) {
+                errors.push(`${label} is complete but implemented_paths is empty`);
+            }
+            if (isBlankish(row.tests) && !hasExplicitNoTestScope(row)) {
+                errors.push(`${label} is complete but tests is empty and no explicit no-test scope is recorded`);
+            }
+            if (isBlankish(row.runtime_evidence) && isBlankish(row.artifact_evidence) && isBlankish(row.real_page_evidence)) {
+                errors.push(`${label} is complete but has no runtime, artifact or real-page evidence`);
+            }
+            if (isBlankish(row.scope_assessment)) {
+                errors.push(`${label} is complete but scope_assessment is empty`);
+            }
+            if (isBlankish(row.drift)) {
+                errors.push(`${label} is complete but drift is empty`);
+            }
+            const weak = weakProofHit(primitiveText(row));
+            if (weak) {
+                errors.push(`${label} is complete but contains weak-proof language matching /${weak}/`);
+            }
+            if (isUiFacing(primitiveText([row.expected_surfaces, row.plan_requirement, row.conformance_type]))) {
+                const realPageEvidence = primitiveText([
+                    row.real_page_evidence,
+                    row.user_path_evidence,
+                    row.fresh_evidence,
+                    row.runtime_evidence,
+                    row.artifact_evidence
+                ]);
+                if (!hasRealPageEvidence(realPageEvidence)) {
+                    errors.push(`${label} is UI/surface-facing but lacks real_page_evidence`);
+                }
+            }
+            if (isSurfaceConformanceRow(row)) {
+                assertSurfaceConformance(row, label, errors);
+            }
+            await assertReferencedPathsExist(projectRoot, label, primitiveText([
+                row.implemented_paths,
+                row.tests,
+                row.runtime_evidence,
+                row.artifact_evidence,
+                row.real_page_evidence,
+                row.negative_surface_checks,
+                row.context_fact_refs
+            ]), errors);
+        }
+    }
+}
+async function validateVerdictRows(projectRoot, rows, overall, errors) {
+    if (rows.length === 0) {
+        errors.push("final acceptance verdict has no AC rows");
+    }
+    for (const [index, row] of rows.entries()) {
+        const label = `final acceptance verdict row ${index + 1}`;
+        const status = statusOf(row);
+        if (!AC_STATUSES.has(status)) {
+            errors.push(`${label} has unsupported status: ${status || "<empty>"}`);
+        }
+        if (status === "out_of_scope_NA") {
+            assertStructuredNa(row, label, errors);
+        }
+        if (overall === "complete" && NON_COMPLETE_AC.has(status)) {
+            errors.push(`${label} is ${status} but overall_status is complete`);
+        }
+        if (status === "complete" && isBlankish(row.fresh_evidence)) {
+            errors.push(`${label} is complete but fresh_evidence is empty`);
+        }
+        if (status === "complete" && isBlankish(row.required_evidence)) {
+            errors.push(`${label} is complete but required_evidence is empty`);
+        }
+        if (status === "complete" && isBlankish(row.decision)) {
+            errors.push(`${label} is complete but decision is empty`);
+        }
+        if (status === "complete" && !isBlankish(row.missing_evidence)) {
+            errors.push(`${label} is complete but missing_evidence is not empty`);
+        }
+        if (status === "complete" && !isBlankish(row.contradictions)) {
+            errors.push(`${label} is complete but contradictions is not empty`);
+        }
+        if (status === "complete") {
+            const text = primitiveText(row);
+            const weak = weakProofHit(text);
+            if (weak) {
+                errors.push(`${label} is complete but contains weak-proof language matching /${weak}/`);
+            }
+            if (isUiFacing(text) && !isOutOfScope(row) && !hasRealPageEvidence(primitiveText(row.fresh_evidence))) {
+                errors.push(`${label} is UI-facing but lacks fresh real-page evidence or explicit N/A`);
+            }
+            await assertReferencedPathsExist(projectRoot, label, primitiveText([row.fresh_evidence, row.context_fact_refs]), errors);
+        }
+    }
+}
+function validateCrossReferences(matrixRows, verdictRows, errors) {
+    const planIds = new Set(matrixRows.map((row) => String(row.plan_item_id ?? row.id ?? "")).filter(Boolean));
+    const acIds = new Set(verdictRows.map((row) => String(row.ac_id ?? row.id ?? row.acceptance_item ?? "")).filter(Boolean));
+    let checked = 0;
+    for (const [index, row] of matrixRows.entries()) {
+        for (const acId of valuesAsArray(row.acceptance_ids ?? row.ac_ids)) {
+            checked += 1;
+            if (!acIds.has(acId)) {
+                errors.push(`plan-conformance matrix row ${index + 1} references unknown AC id: ${acId}`);
+            }
+        }
+    }
+    for (const [index, row] of verdictRows.entries()) {
+        for (const planId of valuesAsArray(row.related_plan_item_ids ?? row.plan_item_ids)) {
+            checked += 1;
+            if (!planIds.has(planId)) {
+                errors.push(`final acceptance verdict row ${index + 1} references unknown plan item id: ${planId}`);
+            }
+        }
+    }
+    if (matrixRows.length > 0 && verdictRows.length > 0 && checked === 0) {
+        errors.push("plan acceptance artifacts must include acceptance_ids or related_plan_item_ids cross references");
+    }
+}
+function validateContextFactReferences(matrix, verdict, matrixRows, verdictRows, errors) {
+    if (!contextDeltaRequired(matrix) && !contextDeltaRequired(verdict)) {
+        return;
+    }
+    const rows = [...matrixRows, ...verdictRows];
+    if (!rows.some((row) => !isBlankish(row.context_fact_refs))) {
+        errors.push("Context Delta is required but matrix/verdict rows do not cite context_fact_refs");
+    }
+}

package/dist/lib/plan-contract-validator.d.ts

@@ -0,0 +1,2 @@
+import type { ValidatorReport } from "./validators.js";
+export declare function validatePlanContract(projectRoot: string, args?: string[]): Promise<ValidatorReport>;