project-tiny-context-harness 0.8.0 → 0.8.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +40 -32
- package/assets/README.md +141 -60
- package/assets/README.zh-CN.md +48 -40
- package/assets/agents/AGENTS_CORE.md +16 -12
- package/assets/context_templates/architecture.md +5 -5
- package/assets/context_templates/area.md +5 -5
- package/assets/context_templates/global.md +6 -6
- package/assets/context_templates/screen-contract.md +18 -18
- package/assets/github/harness.yml +2 -2
- package/assets/skills/context_development_engineer/SKILL.md +7 -5
- package/assets/skills/context_full_project_export/SKILL.md +42 -42
- package/assets/skills/context_uiux_design/SKILL.md +27 -13
- package/assets/skills/design-resource-authoring/SKILL.md +7 -7
- package/assets/skills/design-resource-authoring/references/downstream-handoff.md +12 -12
- package/assets/skills/design-resource-authoring/references/open-design-provider.md +21 -21
- package/assets/skills/design-resource-authoring/references/resource-selection.md +3 -3
- package/assets/skills/long-task-workflow/SKILL.md +17 -17
- package/assets/skills/long-task-workflow/agents/openai.yaml +4 -4
- package/assets/skills/long-task-workflow/references/authority-lifecycle.md +11 -9
- package/assets/skills/long-task-workflow/references/contract-authoring.md +19 -15
- package/assets/skills/long-task-workflow/references/evidence-design.md +18 -17
- package/assets/skills/long-task-workflow/references/source-authoring.md +15 -12
- package/assets/skills/normal-long-task/SKILL.md +12 -12
- package/dist/commands/design-resource.js +2 -2
- package/dist/commands/index.js +26 -26
- package/dist/commands/long-task-authoring.js +83 -9
- package/dist/commands/long-task.js +15 -15
- package/dist/lib/context-graph-snapshot.js +7 -0
- package/dist/lib/design-md.js +5 -4
- package/dist/lib/design-resource-handoff-shape-evidence.js +3 -0
- package/dist/lib/design-resource-handoff-shape-primitives.js +1 -3
- package/dist/lib/design-resource-handoff-types.d.ts +2 -0
- package/dist/lib/design-resource-handoff-validation-coverage.js +1 -0
- package/dist/lib/design-resource-handoff-validation-structure.js +2 -0
- package/dist/lib/doctor.js +2 -2
- package/dist/lib/execution-target-capabilities.d.ts +2 -0
- package/dist/lib/execution-target-capabilities.js +31 -0
- package/dist/lib/long-task-acceptance-shape.js +81 -20
- package/dist/lib/long-task-applicability-shape.d.ts +4 -0
- package/dist/lib/long-task-applicability-shape.js +54 -0
- package/dist/lib/long-task-assertions-v2.js +8 -0
- package/dist/lib/long-task-authoring-preflight-diagnostics.js +5 -0
- package/dist/lib/long-task-authoring-preflight-repair-order.js +3 -0
- package/dist/lib/long-task-authoring-preflight.js +12 -8
- package/dist/lib/long-task-authority-materials.js +46 -4
- package/dist/lib/long-task-authority-policy.d.ts +54 -0
- package/dist/lib/long-task-authority-policy.js +61 -0
- package/dist/lib/long-task-authority-types.d.ts +12 -2
- package/dist/lib/long-task-authority.js +9 -2
- package/dist/lib/long-task-check-shape.js +6 -1
- package/dist/lib/long-task-claim-definitions.js +27 -42
- package/dist/lib/long-task-claims.js +275 -146
- package/dist/lib/long-task-contract-types.d.ts +42 -8
- package/dist/lib/long-task-control-fields.d.ts +12 -0
- package/dist/lib/long-task-control-fields.js +66 -0
- package/dist/lib/long-task-control-types.d.ts +1 -0
- package/dist/lib/long-task-control-types.js +1 -0
- package/dist/lib/long-task-counterfactual-claim-policy.js +7 -0
- package/dist/lib/long-task-counterfactual-sandbox.js +1 -2
- package/dist/lib/long-task-counterfactual-types.d.ts +12 -0
- package/dist/lib/long-task-delivery-compiler.js +1 -0
- package/dist/lib/long-task-delivery-preflight.js +24 -0
- package/dist/lib/long-task-delivery-shape.d.ts +1 -0
- package/dist/lib/long-task-delivery-shape.js +1 -0
- package/dist/lib/long-task-delivery-types.d.ts +1 -0
- package/dist/lib/long-task-delivery-types.js +1 -0
- package/dist/lib/long-task-delivery-validation.js +46 -0
- package/dist/lib/long-task-design-resource-handoff.js +48 -7
- package/dist/lib/long-task-evidence-capability-codec.js +37 -0
- package/dist/lib/long-task-evidence-capability-policy.js +80 -38
- package/dist/lib/long-task-evidence-capability-runtime.js +36 -0
- package/dist/lib/long-task-evidence-capability-types.d.ts +13 -1
- package/dist/lib/long-task-evidence-findings.js +3 -0
- package/dist/lib/long-task-evidence-sensitivity-policy.js +38 -0
- package/dist/lib/long-task-evidence-v2.js +7 -1
- package/dist/lib/long-task-final-integrity.d.ts +16 -0
- package/dist/lib/long-task-final-integrity.js +98 -0
- package/dist/lib/long-task-final-v2.js +17 -34
- package/dist/lib/long-task-outcome-parser.js +22 -4
- package/dist/lib/long-task-playwright-case-evidence.d.ts +2 -0
- package/dist/lib/long-task-playwright-case-evidence.js +10 -2
- package/dist/lib/long-task-playwright-evidence.d.ts +1 -0
- package/dist/lib/long-task-playwright-evidence.js +32 -0
- package/dist/lib/long-task-product-shape.d.ts +3 -1
- package/dist/lib/long-task-product-shape.js +100 -4
- package/dist/lib/long-task-requirement-shape.js +3 -0
- package/dist/lib/long-task-root-shape.js +12 -6
- package/dist/lib/long-task-runner-freeze.js +16 -0
- package/dist/lib/long-task-runtime-types.d.ts +11 -2
- package/dist/lib/long-task-semantic-assurance-policy.d.ts +4 -0
- package/dist/lib/long-task-semantic-assurance-policy.js +52 -0
- package/dist/lib/long-task-semantic-contract-types.d.ts +18 -1
- package/dist/lib/long-task-semantic-drift-migration.js +33 -2
- package/dist/lib/long-task-semantic-mutation.d.ts +7 -0
- package/dist/lib/long-task-semantic-mutation.js +81 -0
- package/dist/lib/long-task-shape-primitives.d.ts +1 -1
- package/dist/lib/long-task-shape-primitives.js +1 -0
- package/dist/lib/long-task-source-authority-types.d.ts +2 -0
- package/dist/lib/long-task-source-item-parser.d.ts +1 -1
- package/dist/lib/long-task-source-item-parser.js +150 -104
- package/dist/lib/long-task-source-markers.d.ts +12 -0
- package/dist/lib/long-task-source-markers.js +146 -0
- package/dist/lib/long-task-source-target-continuity.d.ts +1 -1
- package/dist/lib/long-task-source-target-continuity.js +80 -55
- package/dist/lib/long-task-source-target-index.js +7 -29
- package/dist/lib/long-task-status-v2.d.ts +1 -0
- package/dist/lib/long-task-status-v2.js +2 -2
- package/dist/lib/long-task-target-policy.js +20 -0
- package/dist/lib/long-task-ui-design-policy.js +27 -1
- package/dist/lib/long-task-ui-surface-shape.js +21 -1
- package/dist/lib/long-task-ui-surface-types.d.ts +7 -0
- package/dist/lib/long-task-verification-preview.d.ts +10 -0
- package/dist/lib/long-task-verifier-dependency-closure.d.ts +3 -0
- package/dist/lib/long-task-verifier-dependency-closure.js +179 -0
- package/dist/lib/long-task-verifier-v2.js +12 -2
- package/dist/lib/long-task-workspace.js +5 -1
- package/dist/schemas/long-task-delivery-v2/long-task-delivery-v2.schema.json +99 -25
- package/migrations/README.md +8 -8
- package/package.json +84 -84
package/assets/README.zh-CN.md
CHANGED
|
@@ -50,7 +50,7 @@ ty-context enable long-task
|
|
|
50
50
|
|
|
51
51
|
初始输入可以是一段产品意图,也可以是 Web GPT 等外部服务给出的详细初始方案。涉及独立设计资源时:
|
|
52
52
|
|
|
53
|
-
- **长程任务:** 初始方案 → 项目尚无设计系统时由用户显式调用 `/design-system-authoring` 生成、选择并采纳 → `/design-resource-authoring` 生成/选择资源、按需完整冻结实现级 Source、一次性回改已接受决策,并生成通过校验的残余 `design-resource-handoff-v1` → 把“修订后的初始方案 + handoff + 选定且身份稳定的设计资源”交给 `/long-task-workflow`;输入立即进入同一个原生 Goal 内的 Source-bound Contract Draft 循环。
|
|
53
|
+
- **长程任务:** 初始方案 → 项目尚无设计系统时由用户显式调用 `/design-system-authoring` 生成、选择并采纳 → `/design-resource-authoring` 生成/选择资源、按需完整冻结实现级 Source、一次性回改已接受决策,并生成通过校验的残余 `design-resource-handoff-v1` → 把“修订后的初始方案 + handoff + 选定且身份稳定的设计资源”交给 `/long-task-workflow`;输入立即进入同一个原生 Goal 内的 Source-bound Contract Draft 循环。
|
|
54
54
|
- **非长程任务:** 使用同样步骤 → 把“修订后的初始方案 + 已校验 handoff + 选定设计资源”直接交给 Codex 当前原生 Goal,按默认 Workflow Contract 执行。
|
|
55
55
|
|
|
56
56
|
设计系统通常在项目冷启动时确定,但该 Skill 只由用户调用,`init`、`sync` 与下游 Skill 都不会自动执行。`/design-resource-authoring` 只对高保真、品牌化、视觉处理等 style-bearing 资源设门禁;低保真结构、IA/流程与纯语义状态研究不受此门禁。旧 Source Plan 仍可作为普通输入,但不再是推荐中间服务。
|
|
@@ -80,7 +80,7 @@ manifest/trigger 命中的少量 area/role Context
|
|
|
80
80
|
|
|
81
81
|
这次搜索只补充语义判断,不会把所有关键词命中都当成 Authority,也不会创建向量/持久索引、缓存、Registry、search state 或第二权威。它仍可能漏掉完全不同的同义词或间接依赖,因此每个实现需求仍要执行 Architecture Deliberation 与收尾 Conformance。
|
|
82
82
|
|
|
83
|
-
`ty-context doctor` 会报告确定性的默认 Context 文件/字节规模、单文件与总量软预算超限、字节完全相同的默认文件,以及 `DESIGN.md` 权威状态。这些只是维护提示,不是新验证 Gate
|
|
83
|
+
`ty-context doctor` 会报告确定性的默认 Context 文件/字节规模、单文件与总量软预算超限、字节完全相同的默认文件,以及 `DESIGN.md` 权威状态。这些只是维护提示,不是新验证 Gate 或运行时状态。如果真实的近乎通用恢复事实超过字节启发式预算,应保留事实并接受 warning;绝不能为了满足预算而遗漏、过度压缩或错误分类必需 Context。
|
|
84
84
|
|
|
85
85
|
Context 负责耐久的意图和边界,代码负责当前实现,测试/CI/浏览器或运行时证据/人工负责行为与产品验收。
|
|
86
86
|
|
|
@@ -121,28 +121,30 @@ Harness 只路由仓库原生 lint/AST/dependency/contract check,不实现跨
|
|
|
121
121
|
|
|
122
122
|
`context_surface_contract` 继续使用现有 `contract`、area/subdomain 和 verification 角色。`product-surface-contract.md` 负责跨页面、主层/下钻与共享职责;可选且按需读取的 `screen-contract.md` 负责单屏 entry/exit/shared state、信息层级、语义区域、导航/变体、material controls 和 target/verification 引用。它们不新增 `design`、`screen` 或 product-surface Context role,局部样式修复也不要求补建 Screen Contract。
|
|
123
123
|
|
|
124
|
-
material UI 在实现前执行 **UI Authority Closure**:每个稳定 surface/control/target key 必须归类为现有 Context 已覆盖、需要 Context 更新、task-local、显式 out-of-scope 或真正 decision-required。Surface
|
|
124
|
+
material UI 在实现前执行 **UI Authority Closure**:每个稳定 surface/control/target key 必须归类为现有 Context 已覆盖、需要 Context 更新、task-local、显式 out-of-scope 或真正 decision-required。Design Source Projection 把长期 surface/flow/Screen/Control/state 含义放入既有 Surface 或 Screen/interaction Context,把视觉系统/token/motion policy/rationale 放入 `DESIGN.md`,把精确构图/数值/条件/asset 留在 versioned target,把可重复证明路径放入 verification Context,而 delivery-local coverage/provenance/blocker 留在任务或 Contract Source。出现冲突时 fail closed;当前代码、时间戳、YAML 或实现截图不能静默胜出。
|
|
125
125
|
|
|
126
126
|
### 视觉交付指导
|
|
127
127
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
provider-neutral handoff 是残余语义与索引层,不是 CSS 的文本副本。它逐一闭合每个适用的 subject × selected target × declared condition × UI/UX dimension 单元格,覆盖 surface/flow、visual/content、component/control、state/interaction、motion、adaptation/input、accessibility、assets 八个维度,并记录明确排除/不适用/未决含义、Source Item、verification method
|
|
131
|
-
|
|
132
|
-
这些输入仍是普通 Source
|
|
128
|
+
两种开发路径共享一个条件式设计目的:当存在已选 implementation handoff 时,让 Agent 的开发、验收和测试在 UI/UX 方面完整遵循选定设计资源在声明范围与条件内明确表达的全部材料性信息。它不授权从静态图推断未表达的交互,也不能证明用户没有遗漏要求。Open Design 有能力输出实现级 HTML/CSS/JS、spec、token 与 asset,但“有能力”不等于每次都产出:选定 Web/App 实现 handoff 时,`/design-resource-authoring` 必须显式委托并完整取得一个机器可读 canonical entry 及其精确 dependency closure,逐文件冻结 digest,并暴露稳定的 typed locator;进入 `ready` 前,还要在这些不可变字节上逐项执行声明的 verification method,无法消除的 code/spec/token/asset 冲突保持未决/不可用并阻塞。这是源资源 QA,不是生产验收。PNG 只能作为派生视觉基线,不能成为唯一实现源。
|
|
129
|
+
|
|
130
|
+
provider-neutral handoff 是残余语义与索引层,不是 CSS 的文本副本。它逐一闭合每个适用的 subject × selected target × declared condition × UI/UX dimension 单元格,覆盖 surface/flow、visual/content、component/control、state/interaction、motion、adaptation/input、accessibility、assets 八个维度,并记录明确排除/不适用/未决含义、Source Item、verification method、blocker 及每个 blocker 精确需要的目标运行能力。preflight 会把每个 typed HTML/Markdown/JSON/CSS locator 对着其声明的不可变资源真实解析,校验 source/dependency closure,并拒绝不可解析或 media 不兼容的证据;探索候选仍不需要 schema。
|
|
131
|
+
|
|
132
|
+
这些输入仍是普通 Source。默认 Workflow 对 covered Source Items、declared verification methods、blockers、targets 和 conditions 保持精确但 task-local 的 accounting;每一项都必须到达生产 owner、冷启动旅程和已经执行的 final-candidate check,并能在失败时明确归因。任何 unresolved、unmapped、unexecuted、stale 或无法区分的项都会阻止“完整遵循”声明并作为 gap 报告。Long-Task 把同一组含义投影进已有 Claims、method Assertions、`surface_bindings`、typed evidence 和 Final Gate。两种证明载体互斥:active Long-Task 不再执行默认 closure。生成成功、截图、hash 与 preflight 只证明输入完整性或资源完整性。
|
|
133
133
|
|
|
134
|
-
默认 Workflow 会在 material 产品、设计、实现或验收判断前执行 UI Authority Closure 和条件式 Design Authority Check
|
|
134
|
+
默认 Workflow 会在 material 产品、设计、实现或验收判断前执行 UI Authority Closure 和条件式 Design Authority Check。它沿稳定 key 到 exactly-one canonical adoption record,再主动打开每个受影响的 selected `exact-target`/`constraint`;只看到 registry 或 handoff index 不算已消费。项目/系统/component-family target 由 `DESIGN.md` canonical 记录,单 screen/interaction target 由 owning Screen Contract 记录;该 record 独占 interpretation、selection basis、immutable locator/digest、condition coverage 和 editable upstream/update route,其他层只保留 stable key、owner/anchor 和 local applicability。缺失、不可读、过期或冲突时 fail closed;更新必须产生新 immutable version,不能覆盖旧基线。未配置 starter、候选稿、只有风格文字或灵感图都不能授权 agent 发明生产布局。明确的设计系统采纳请求路由到 `/design-system-authoring`,独立资源生成请求路由到 `/design-resource-authoring`;已有充分权威的普通实现、局部样式修复和 throwaway prototype 仍保持轻量。
|
|
135
135
|
|
|
136
|
-
只要是已经选定、准备进入实现的设计资源,两种开发路径都会先运行 `ty-context design-resource preflight <handoff.md>`。取得不完整、缺少或多出未声明依赖、不安全路径、过期 digest、虚构 locator、未闭合的适用单元格、不成立的证据类型或未决语义都会 fail closed。preflight 只证明设计输入语义完整且资源身份正确;开发流程仍必须打开真实资源,并从生产入口证明当前实现。
|
|
136
|
+
只要是已经选定、准备进入实现的设计资源,两种开发路径都会先运行 `ty-context design-resource preflight <handoff.md>`。取得不完整、缺少或多出未声明依赖、不安全路径、过期 digest、虚构 locator、未闭合的适用单元格、不成立的证据类型或未决语义都会 fail closed。preflight 只证明设计输入语义完整且资源身份正确;开发流程仍必须打开真实资源,并从生产入口证明当前实现。
|
|
137
137
|
|
|
138
|
-
对 material 工作,`context_uiux_design`
|
|
138
|
+
对 material 工作,`context_uiux_design` 应用上面的投影规则并让风险比例化 coverage reasoning 保持 task-local。`context_development_engineer` 用稳定 surface/control key 把每个选定 target/condition 及 handoff 精确集合追踪到生产 route/component owner、冷启动真实用户旅程及可独立归因的渲染/交互检查。第一个有价值的可运行纵向切片只是建议性的真实入口反馈点,不是实现门禁;最终候选仍必须重跑受影响的冷启动旅程。所有已声明/适用组合必须完整覆盖,不能用 risk-only 或 pairwise 抽样替代,除非权威 Source 明确收窄范围或项目自有证明建立等价性。只报告真正检查过的组合;资源哈希、manifest 和数量只证明资源完整性,实现截图既不能成为自己的目标,也不能单独证明实现一致性。
|
|
139
139
|
|
|
140
|
-
显式 Long-Task
|
|
140
|
+
显式 Long-Task 是同一共享义务的强机器载体。它在 Compile 前解决缺失/冲突的 UI 权威,并用 `field_coverage` 闭合每个真实 Control 的全部 22 个 canonical 字段:每个字段只能是具有具体语义的 `specified`、带明确理由的 `not_applicable` 或会阻断的 `unresolved`;省略绝不等于不适用。specified/not-applicable 项会在每个声明的 applicability profile 下生成独立受保护 Control Claim;即使关系不适用,`control_relation_closure` 也会成为带精确 applicability 的负向 Claim。`control_relation_closure` 与 `control_relations` 同时闭合跨 Control/系统的共享状态、依赖/顺序、导航、权限、校验、反馈和恢复链。聚合的 Product `surface_bindings` 把每个 Control 连接到 owner surface、required product target、既有 Technical route/component Bindings 和 root-entry 成功旅程。选定 exact/constraint target 用 typed `design_conformance` 把冻结输入和声明条件绑定到当前 actual/comparison artifacts;每个 `verification_method_binding` 都有独立 `design_method` 记录,并在每个精确 condition 下声明 method record 与 method-native primary observation,其当前路径和 digest 均不得被另一单元复用。Playwright 的每个 project instance 必须显式附带两类 artifact。每个 blocker 保留精确 Source-item/method/required-capability lineage,只能由 capability 完整的精确目标上的机器 Claim 闭合,否则保留为阻断目标的 External Confirmation。它们不能在 Contract 内自行豁免,缩减范围必须修订 Source/Contract 权威。现有 Claim、Assertion、Check、Stage、Binding、revision 与 Final Gate 是唯一 Long-Task 生命周期和 closure。
|
|
141
141
|
|
|
142
142
|
combined design-and-implementation 可以先用普通 Outcome/Stage 生成候选,但 candidate/planned target 不能解锁 fidelity implementation;选定结果必须先成为真实 marked Context-reachable Source,并由 owning Context/`DESIGN.md` reference 连接,Authority Lock 后再通过 Authority Revision 采用。浏览器视觉 AC 使用 `ui_browser`;浏览器代理、独立 route 或深链接不能证明可独立失败的原生/root 旅程。资源完整性和 `visual_render` 不能替代选定目标的实现一致性。冻结 baseline 是 verifier input,生成的 actual render/diff 是当前 artifact,主观批准保持外部。这不新增 `uiux_delivery`、视觉 Claim type、resource registry、risk level、lifecycle state、Gate、必需设计目录、逐控件截图矩阵或通用像素阈值。
|
|
143
143
|
|
|
144
144
|
`ty-context doctor` 保留兼容的项目级 `missing | unconfigured | configured` 状态,并增加 Design Authority Index、token source 和已分类 reference 的 advisory 信号。它明确不推断页面实现就绪;material surface 仍需 owning Screen/Control meaning、selected target/constraints 与项目自己的验证路径。
|
|
145
145
|
|
|
146
|
+
静态 guidance 测试只能证明分发、投影与 canonical ownership 文案存在,不能证明 Agent 实际恢复了全部 UI/UX 信息。可选 delivery-mechanism benchmark 提供固定 fresh-agent UI/UX Context/target recovery task、routing gold 和隐藏 production oracle;只有独立配对运行才可以支持 effectiveness/ROI 结论。
|
|
147
|
+
|
|
146
148
|
### 显式 Design System Authoring
|
|
147
149
|
|
|
148
150
|
只有用户明确要求初始化、生成、选择、采纳、替换或修复项目设计系统/设计风格时,才使用 `/design-system-authoring`。安装只让冷启动能力可用,不会自动运行。Skill 会发现 Open Design 当前真实 MCP resource/tool;若当前版本只通过 MCP 读取设计系统而没有创建 tool,则使用同一个已安装 Open Design daemon 的官方 generation/revision/accept API,不复制 provider prompt,也不把 daemon 调用冒充 MCP。
|
|
@@ -157,11 +159,11 @@ Skill 把明确输出或开发内容当作硬 scope ceiling。局部功能只可
|
|
|
157
159
|
|
|
158
160
|
Skill 会先分类 visual-style dependency。高保真/品牌化输出、视觉方向、字体/颜色/密度、组件视觉处理和 production-style prototype 属于 style-bearing:若 `DESIGN.md` 未配置或没有唯一 authored token source/direction,Skill 必须在创建 provider project/run 前停下,并提示用户显式调用 `/design-system-authoring`,绝不自动初始化。低保真结构、IA/flow topology 和纯语义 behavior/state study 属于 non-fidelity。style-bearing 工作必须把已采纳 provider ID 传给 MCP `create_project.designSystem`,并用 `get_project.designSystemId` 验证一致。
|
|
159
161
|
|
|
160
|
-
Skill 只通过结构化 MCP(必要时有限使用 CLI/daemon/UI fallback)委托最小充分资源集。一个可定位、可检查的大页面稿、原型或组件族 workbench 可以覆盖多个事项;重复控件映射到共享变体,只有仍缺少材料性含义的独特/复杂控件才需要专门状态或交互稿。静态/default 页面不能自动代表没展示的动态状态、交互、动效、响应式或可访问性。原型、低/高保真组合、组件板、provider-native 输入、逐控件一份稿、变体数量和目录都不是全局必选项。设计资源可以表达用户可感知的交互语义和产品规则的呈现方式,但业务、数据、权限和算法逻辑仍由产品/技术 Source 所有。Tiny Context 不复制 Open Design 的 prompt/template,也不内置 provider catalogue。
|
|
161
|
-
|
|
162
|
-
面向 Web/App 实现时,Skill 必须取得上文所述完整 canonical entry/dependency set 与可寻址事实。Figma 适合已经存在的设计团队权威,需要原生 Components/Variables/Variants、共享库、Dev Mode 或 Code Connect 的场景;Penpot 适合明确需要开放、自托管多人设计基础设施的场景;OpenPencil 可作为本地静态布局 sidecar,但当前 prototype/motion 模型仍不完整。把完整 Open Design Source 默认转换为另一种表示会增加同步和运维成本,却不会关闭新的 enforcement gap,因此三者都不是默认依赖。
|
|
163
|
-
|
|
164
|
-
探索模式只做最小完整性检查并尽快展示指定候选,不需要 handoff schema。明确或受托最终选择且资源将进入实现时,Skill 只做一次合并、幂等的初始方案回改,并在任意获准的项目路径写一个 provider-neutral、带 Source marker、且只含一个严格残余 `design-resource-handoff-v1` block 的 Markdown。它记录 implementation source profile、typed locator、适用 subject/target/condition coverage、残余产品含义、Source-item/verification-method binding 和 acceptance blocker;随后运行共享 preflight,不能把取得不完整、不可寻址、`decision_required`、`unavailable`、证据不成立或过期输入称为 ready。这里没有固定目录、provider pack 或逐控件一份稿;适配器只是普通 Source,不是 Design Authority 或验收结果。Skill 不会修改 Source Plan、`project_context/**`、`DESIGN.md`、生产代码或 Delivery Contract。
|
|
162
|
+
Skill 只通过结构化 MCP(必要时有限使用 CLI/daemon/UI fallback)委托最小充分资源集。一个可定位、可检查的大页面稿、原型或组件族 workbench 可以覆盖多个事项;重复控件映射到共享变体,只有仍缺少材料性含义的独特/复杂控件才需要专门状态或交互稿。静态/default 页面不能自动代表没展示的动态状态、交互、动效、响应式或可访问性。原型、低/高保真组合、组件板、provider-native 输入、逐控件一份稿、变体数量和目录都不是全局必选项。设计资源可以表达用户可感知的交互语义和产品规则的呈现方式,但业务、数据、权限和算法逻辑仍由产品/技术 Source 所有。Tiny Context 不复制 Open Design 的 prompt/template,也不内置 provider catalogue。
|
|
163
|
+
|
|
164
|
+
面向 Web/App 实现时,Skill 必须取得上文所述完整 canonical entry/dependency set 与可寻址事实。Figma 适合已经存在的设计团队权威,需要原生 Components/Variables/Variants、共享库、Dev Mode 或 Code Connect 的场景;Penpot 适合明确需要开放、自托管多人设计基础设施的场景;OpenPencil 可作为本地静态布局 sidecar,但当前 prototype/motion 模型仍不完整。把完整 Open Design Source 默认转换为另一种表示会增加同步和运维成本,却不会关闭新的 enforcement gap,因此三者都不是默认依赖。
|
|
165
|
+
|
|
166
|
+
探索模式只做最小完整性检查并尽快展示指定候选,不需要 handoff schema。明确或受托最终选择且资源将进入实现时,Skill 只做一次合并、幂等的初始方案回改,并在任意获准的项目路径写一个 provider-neutral、带 Source marker、且只含一个严格残余 `design-resource-handoff-v1` block 的 Markdown。它记录 implementation source profile、typed locator、适用 subject/target/condition coverage、残余产品含义、Source-item/verification-method binding 和 acceptance blocker;随后运行共享 preflight,不能把取得不完整、不可寻址、`decision_required`、`unavailable`、证据不成立或过期输入称为 ready。这里没有固定目录、provider pack 或逐控件一份稿;适配器只是普通 Source,不是 Design Authority 或验收结果。Skill 不会修改 Source Plan、`project_context/**`、`DESIGN.md`、生产代码或 Delivery Contract。
|
|
165
167
|
|
|
166
168
|
实际生成仍由已配置的 Open Design/Product Design、Figma、图片生成、原型工具或人工设计流程负责。这些输出以普通 external Source 进入默认 Workflow 或 Long-Task。candidate 与 inspiration 不授权 fidelity;adopted exact target/constraint 作为 Context-reachable Source,由 owning Context/`DESIGN.md` 把稳定 key 连接到覆盖条件、不可变身份/digest 和 editable upstream owner/locator/update route。`context_uiux_design` 在下游执行 UI Authority Closure,只把耐久事实采纳到 Context/`DESIGN.md`;实现截图与 diff 仍是证据 artifact,不能自我授权为目标。
|
|
167
169
|
|
|
@@ -176,17 +178,19 @@ Skill 只通过结构化 MCP(必要时有限使用 CLI/daemon/UI fallback)
|
|
|
176
178
|
只有用户显式调用 `/long-task-workflow`,或当前 worktree 已有 active long task 时才使用。它固定为:
|
|
177
179
|
|
|
178
180
|
- 一个平台原生、持续的 Goal;
|
|
179
|
-
-
|
|
181
|
+
- 一个用户选定的仓库与最终验证/收敛 worktree;
|
|
180
182
|
- 一次完整选定交付、一个 Contract、一个 Final Gate;
|
|
181
|
-
- Outcome
|
|
183
|
+
- Outcome 依赖只表示验收与中间证明就绪关系,不限制实现顺序,也不表示 Worker 调度;
|
|
182
184
|
- 第一次 Authority Lock 后、正式实现前有一次用户模型选择;
|
|
183
|
-
- 当前 Goal
|
|
184
|
-
- targeted verify
|
|
185
|
+
- 当前 Goal 自主选择实现顺序、局部计划、工具,并可按 ROI 选择单 agent 或多开平台原生 agent/subagent;Harness 不负责分配、调度、重试或恢复,agent 报告不是 Progress 或证明,所有结果必须汇入同一验证 worktree;Frontier 只提供验收/验证建议;
|
|
186
|
+
- targeted verify 是可选反馈与修复证据,永远不能 accepted,也不构成继续实现或进入 Final Gate 的门禁;
|
|
185
187
|
- scope-only revision 可先做无状态候选诊断,机械边界内的修复自动采用;只有稳定且确需用户决策的候选才至多询问一次精确 identity;
|
|
186
188
|
- Final Gate 在一个当前快照上重跑全部 Check;
|
|
187
|
-
- Stop Hook 在结果 stale 时阻止完成。
|
|
188
|
-
|
|
189
|
-
|
|
189
|
+
- Stop Hook 在结果 stale 时阻止完成。
|
|
190
|
+
|
|
191
|
+
它的证明命题有明确前提:Source 在声明观察粒度下完整且准确,Source→Contract 投影保持语义,所有实际适用单元被展开,且具名项目 Oracle 与 verifier/runtime 可信边界语义正确;在这些前提下,只有 fresh `machine_accepted` 且没有任何待定 External Confirmation 的 `AcceptedDeliveryTerminal` 才严格推出完整声明可观察漂移为空。`machine_accepted_external_pending` 只能推出机器可验证范围内的声明漂移为空,完整交付仍是带限定的未完成状态,Harness 不完成原生 Goal。Harness 会机械强制并冻结其中许多前提,但无法发现未声明要求,也无法自动证明任意项目 Oracle 对现实语义忠实。
|
|
192
|
+
|
|
193
|
+
原始/修订方案、选定设计资源和混合附件会立即进入一个 Source-bound Contract Draft 循环;完整 input inventory、稳定 Key、控件级含义、acceptance/risk、direct/derived/delegated/evidence-backed 溯源、Source 归属与 Contract 映射一起收敛。声明为 Source 的 Markdown 中,每一行非空文本都必须属于一个 Material `ty-source-item` 块、唯一且通过 schema 校验的 `design-resource-handoff-v1` formal block,或满足封闭语法的 background:`markdown-structure` 只能包含不承载自然语言的锚点/分隔线,`provenance` 只能包含固定 `input`、`mode`、条件式 `source` 与可选 `sha256` 字段的 `ty-source-provenance` 注释;有文字的标题或自由说明字段可能表达权威含义,因此不能放进 background。任意背景说明文字和其他未分类文本都 fail closed。每次交付至少有一个标注 `aspect=architecture` 的 technical obligation Source Item,并映射到可独立证明的架构 obligation。若未知偏好会实质改变调研或选型,Preflight/Compile 成功前必须先询问;标准明确后,有依据的推荐才写入真实 Source,不能只藏在 YAML。方案委托不授权真实高危外部动作;输入冲突、用户保留、偏好缺失或无可靠推荐仍为 `decision_required`。旧 Source Plan 结构本身不构成阻塞。
|
|
190
194
|
|
|
191
195
|
第一次正式 Compile 成功前,`delivery-contract.yaml` 是同一份非权威 Contract Draft。`/long-task-workflow` 从入口开始,跨 Source 细化、仓库/Context 读取、映射和 Preflight 修复持续修改它,不要求一次响应生成完整 Contract。Source 完备性是 Preflight/Compile 的收敛条件,不是前置阶段。不存在单独 Contract Draft Skill、Draft Receipt 或 Authoring State。
|
|
192
196
|
|
|
@@ -211,11 +215,15 @@ Skill 只通过结构化 MCP(必要时有限使用 CLI/daemon/UI fallback)
|
|
|
211
215
|
|
|
212
216
|
Long-Task Skill 采用渐进读取:主 `SKILL.md` 只保留目标、硬边界和路由;Draft 输入/Contract Authoring、Evidence Design 与 Authority Lifecycle 细节按当前活动读取一层 reference,其中 Draft 输入与 Contract mapping 同时进行。这只是指令组织,不产生第二权威。共享 Architecture Deliberation 在 Source-bound Draft authoring 中完成;material 架构不变量使用已有 obligations/constraints/forbidden shortcuts、owner/path/Binding 和项目原生 executable Checks,Final Gate 是唯一的 Long-Task Architecture Conformance 承载点。
|
|
213
217
|
|
|
214
|
-
Draft Outcome 只是 Authority Lock 前的 Outcome。Outcome
|
|
218
|
+
Draft Outcome 只是 Authority Lock 前的 Outcome。Outcome 按可独立观察、判断、纵向闭环和定向验证的结果拆分,用于投影 acceptance/verification-ready 工作集、定位失败、恢复 finding 并精确失效旧局部结果。`depends_on` 只表示 acceptance 与中间证明 readiness,不授权或禁止实现编辑。每个 Outcome 属于一个有序 Stage;Stage gate 传递依赖同 Stage 其余 Outcome,后续 Stage 依赖前置 gate。Rolling Frontier 和 Stage 状态都由普通 Outcome Progress 临时派生,只是建议性验证/诊断投影。当前 Goal 可按代码现实跨 Outcome/Stage 实现、检查或返工,也可使用平台原生 opaque delegation;Harness 不创建 delegation scheduler、不把委派当证明,所有结果必须汇入选定验证 worktree。Outcome 不是 Worker、scheduler task、queue 或并行单元,Stage 也没有 Receipt 或第二个 Gate。Outcome 拆分诊断和证明归属,不拆分完成权威,因此最终仍必须在当前最终快照运行一次完整 Final Gate。
|
|
219
|
+
|
|
220
|
+
Contract 声明一个有界 target profile、非空 required product target refs,以及每个 target 的 runtime family、root entrypoint 和显式 capabilities;required product target 必须声明对应 family、`cold-start` 与 `production-root` 能力。Web/process 代理不能代替单独要求的 Native/desktop 目标;browser 目标由 Playwright 证明,Native/desktop 目标由 project binary 证明。每个 `critical_user_path` Outcome 和 Stage gate 都必须从每个 required target 的 root 证明 `target_runtime`;多 Outcome Stage gate 还必须证明至少两个不同 surface 对应同一运行时状态。
|
|
215
221
|
|
|
216
|
-
|
|
222
|
+
如果一个声明结果可能在代理表面通过、却在目标运行时独立失败,最早拥有可运行边界的 Outcome 必须声明项目自有的真实运行 Check,并在当前 Check 执行中启动或触达目标、从同一会话产生结构化 Observation。仓库内状态报告、截图、二进制、日志或历史运行不能单独证明目标运行时。Check 显式声明带 Key 的 Given/When 场景与 journey role;global/Outcome applicability profile 绑定精确 target、journey、不可重复且每个维度只有一个值的原子 dimensions、Given condition/input/state refs 与有序 When refs。每个 Claim 列出全部适用 profile,每个 Claim-bearing Assertion 只证明一个 Claim 在一个完全匹配 profile 下的语义;每个实际 applicability × proof-surface 单元都必须可归因,不能由 risk-based、pairwise 或抽样替代。Assertion 声明 all-of Evidence Capability,并由类型化的当前执行记录证明。静态 `presence` 不能证明行为,降级路径不能替代要求的成功路径,固定输入不能证明输入变化,产生 side effect 的组件也不能自行证明其边界效果。每个行为型 Claim-bearing Assertion 还必须有同 Check、Claim-local 的 `replace_json_value` 或 `replace_text` Counterfactual:错误语义使它失败,同时列入 `preserved_assertions` 的无 Claim target-runtime liveness Assertion 必须继续通过;整文件替换不能证明语义绑定。Population 必须把真实 universe carrier 纳入 owning Check 快照,并证明 universe = eligible = observed + 合法 exclusions。Runner identity 会递归冻结受支持的 direct-literal 本地 verifier module/config/data graph:静态 import/export、literal dynamic import、`require` 形式和 literal `new URL(..., import.meta.url)` 文件;非 literal loader 与 `createRequire` 会 fail closed,package script 必须具有可恢复的静态 Node entry。候选/runtime 材料由 `input_paths`、`expected_output_paths` 或 `artifact_globs` 显式归类;其他间接 Oracle 访问必须进入 `verification_inputs`,否则属于具名可信边界。每个 Check 的 `input_paths`/Binding 应是最小可信失效范围,每个 Counterfactual carrier 都要能从声明的 target root 解释其路径。第一个有价值的可运行切片和合并后的相关变化只是默认建议反馈点;只有中间判断实际依赖某条 Progress 时才必须刷新。继续实现或进入 Final Gate 不要求先跑 targeted verify,因为 Final Gate 会忽略 Progress 并重跑全部 Check。`verify --explain` 可提前展示 Main/Counterfactual/重试次数,但不执行、不写 Progress,也不能看见 runner 内部构建。它不增加通用可达性断言、实现门禁、第二个执行型 diagnose 模式、调度器、逐平台 Progress 或逐编辑完整重建;运行时专属依赖探测、构建进度和进程清理由项目 runner 负责,Final Gate 仍是接受权所有者。
|
|
217
223
|
|
|
218
|
-
|
|
224
|
+
长程任务工作流的“防劣化保障”同时保护当前因果链的真实性、跨版本的漂移拦截强度,以及相邻的 `F = 实现自由边界(Implementation Freedom Boundary)`。Context 对“当前实现”的描述必须与索引到的真实代码/运行逻辑一致;当前实现必须继续承担“需求/架构意义表达”和“fail-closed 识别、返工、最终快照复验”两项共同必要职责,并在明确的 Source 完整性、语义绑定、可观察性和可信边界下推出“不错误完成”的设计目的。`F` 是效率与反流程膨胀边界,不是第三项机制职责或无漂移定理前提:在 Source/Contract、架构、安全、禁止捷径、不可逆影响与外部动作边界内,实现顺序、方法、局部反馈节奏以及可选的单 agent/多 agent 或 subagent 实现由当前 Goal 决定;Harness 不建立开发阶段/方法 Gate、逐编辑强制验证、agent 调度/状态或委派证明。设计目的、关键逻辑、两项职责、成立边界和 `F` 都属于受保护设计不变量;弱化或替换它们必须由项目 owner 显式作出设计目的变更决策并给出替代证明,不能由 Agent 推断、文档/代码/测试同步改写或成本理由暗中授权。新增开发期限制还必须解决 Final Gate 或更轻项目检查无法覆盖的独立风险,并具有正净 ROI。该保障复用现有 Context、索引、测试、关键哨兵、路由和一致性门禁,不新增第二 Authority、Gate 或状态;它也不能补出未表达/不可观察的需求,或对拥有全部修改权限者的蓄意联合弱化提供绝对不可变保证。
|
|
225
|
+
|
|
226
|
+
工作流变更随后必须依次通过两道硬门槛。第一阶段先证明 `Coverage_new ⊇ Coverage_old`、`FalseNegative_new ⊆ FalseNegative_old`,并保持 Authority、fail-closed、完整/当前/最终候选快照证明均不可绕过;无法证明时必须保留当前正式验收路径,任何成本下降都不能补偿漂移识别能力下降。第二阶段才要求防劣化或设计目的达成的增量收益,大于 Authoring、Runtime、State、Recovery、维护、测试、流程、引入和迁移等全部增量成本。正净 ROI 只使候选进入考虑集,不代表自动采用。
|
|
219
227
|
|
|
220
228
|
只有 `weak_observability` 同时遇到多 Stage 或多个 required product runtime family 时,才额外要求一个只读 Global Product Conformance Check。它从 required root product target 启动,使用独立 Raw Execution,并在既有 Final Gate 内运行。单 Stage、单 family 继续使用原有 same-Check sensitivity,不支付额外 conformance 执行成本。
|
|
221
229
|
|
|
@@ -242,14 +250,14 @@ ty-context long-task abandon <workdir> [--force-corrupt-state]
|
|
|
242
250
|
```
|
|
243
251
|
|
|
244
252
|
- `init` 创建单文件 inline Outcome 的 Compact Contract 模板。
|
|
245
|
-
- `preflight` 应用 Compact 默认值并一次输出 Source
|
|
246
|
-
- `compile` 重复同一 fail-closed workspace
|
|
253
|
+
- `preflight` 应用 Compact 默认值并一次输出 Source 非空文本归属、REQ、CTRL 字段/关系闭包、OBL/AC、applicability、Stage closure、required-target/root/runner、scenario/journey、capability、external impact、Product Conformance、Context、风险、路径/Binding、Runner/Input、语义 witness/liveness、Proof 与 workspace-scope 诊断。首次 Authority Lock 前,它把每个 HEAD-relative 当前变化路径分类为 protected、expected change、allowed support、forbidden 或 unclassified;后两类中的 forbidden/unclassified 都阻塞。它完全只读,不创建 Authority Lock、marker、cache、progress、Receipt、pending revision、状态锁,也不运行项目 Check。
|
|
254
|
+
- `compile` 重复同一 fail-closed workspace 分类和 activation validator,因此直接 Compile 不能绕过 Preflight,再按精确 applicability 生成 Global 与 Outcome Result/Requirement/Control-field/Control-relation/Non-completing/Technical Claim,拒绝未覆盖单元,并让第一次正式成功 Compile 成为 Authority Lock。首次 enable 仅保护配置的 managed destination 中当前 package asset tree 实际存在的精确文件,以及精确的 config/hook 文件;managed 目录根和宽泛 `.codex/**` 均不豁免。每次结果都包含 lifecycle event、`delivery_completed_by_this_event: false`、`native_goal_effect: none` 和 next action。第一次结果附带 `execution_model_checkpoint.required: true` 及 terminal-turn/explicit-choice 契约,后续 Compile 返回 `false`;这些字段不进入 Authority state。
|
|
247
255
|
- `diagnose-revision` 只做无副作用候选 Compile;仅 scope-only 候选能运行 Active Authority 已有且未更换的 Check,输出固定为非验收、非 Progress、非 pending。
|
|
248
256
|
- `compile --revise` 自动采用单调或机械边界内的修订;需要用户决策时返回 `authority_revision_pending`、精确 id、确定性 material 摘要、`user_decision_reasons` 和自包含 `decision_brief`。先展示 brief;只有已明确且精确覆盖全部 reason 的当前任务指令可直接承载该 id。候选再变会生成新 id 并使旧批准失效。采用后证据失效、输出 `authority_revision_adopted` 并回到滚动执行,不表示交付完成。
|
|
249
|
-
- `verify` 在重查 active task/revision/compiled/worktree identity 并依据 immutable baseline 应用同一 workspace 分类后写 scoped Progress;targeted verify
|
|
250
|
-
- `status` 输出 `unverified`、`progress_passing`、`progress_failing`、`progress_stale` 或 `blocked_external`,由当前 Progress 派生 `stages`、`ready_stages`
|
|
251
|
-
- `resume` 完全只读,恢复 task/contract identity、风险、相关 Context、Git 状态、相同的 Final/target/Stage/external/pending surface、ready Outcome、findings
|
|
252
|
-
- `final-gate`
|
|
257
|
+
- `verify` 在重查 active task/revision/compiled/worktree identity 并依据 immutable baseline 应用同一 workspace 分类后写 scoped Progress;targeted verify 始终只是可选反馈/修复证据。`verify --explain` 只读地合并 Main Raw Execution、列出适用 Counterfactual 调用与声明的重试次数上界,不执行命令、不写 Progress,也不预测耗时或 runner 内部子进程。
|
|
258
|
+
- `status` 输出 `unverified`、`progress_passing`、`progress_failing`、`progress_stale` 或 `blocked_external`,由当前 Progress 派生 `stages`、`ready_stages` 和建议性的验收/验证 Outcome frontier,不持久化 Stage 完成。兼容字段 `ready_for_implementation` 只是该投影的别名,不是实现门禁。它同时报告 fresh `final_workflow_status`、target profile/state、完整 `external_confirmations` 与唯一的 `pending_authority_revision`。`progress_passing` 只能表述为定向修复证据,不能简称“Outcome 完成”;`progress_stale` 是证据新鲜度事实,不是当前通过或每次编辑后立即重跑的指令;`final_workflow_status: null` 表示 Goal 尚未完成。
|
|
259
|
+
- `resume` 完全只读,恢复 task/contract identity、风险、相关 Context、Git 状态、相同的 Final/target/Stage/external/pending surface、ready Outcome、findings 和建议性的验证/修复 next action;该建议不限制实现顺序。
|
|
260
|
+
- `final-gate` 在执行前重新编译 Source Authority,并捕获 Contract/fragments、Source、Controlling Context、verifier/runner、verification inputs 和 workdir inputs 的语义与原始受保护身份;完成全部 Check 后,再次编译并哈希同一完整集合。任一输入竞争变化都会 fail closed,并发 revision 也不能产生 accepted。Receipt 把每个 Stage 派生为 `passed`、`failed`、`blocked_external` 或 `blocked_dependency`,把 `target_state` 派生为 `not_accepted`、`blocked_external` 或 Contract 精确声明的 `implementation_complete`、`target_profile_usable`、`production_release_ready`。
|
|
253
261
|
- `stop-check` 与 `close` 自己运行 Live Final Gate,并只用 accepted identity 做 CAS clear。每次机器接受的 Stop 都给一个非阻塞 terminal-scope `systemMessage`;外部待确认时同时列出全部确认项。Final/Stop/close 输出 `acceptance_scope: declared_machine_authority` 与 `native_goal_effect: none`,close 另输出 `closed_scope: machine_authority`。`status: closed` 只表示机器 Authority 已清理,不表示原生 Goal 或完整外部交付完成。
|
|
254
262
|
- `abandon --force-corrupt-state` 仅用于损坏/mismatch/legacy-unrecoverable 状态或遗留锁,只删除确定性 active state 与 `<workdir>/.ty-context/**`。
|
|
255
263
|
|
|
@@ -265,13 +273,13 @@ Contract 顶层包含:
|
|
|
265
273
|
- `global`:非目标、owner boundary、技术约束、禁止路径/捷径和全局 Check;
|
|
266
274
|
- `outcomes`:可独立判断并可定向验证的纵向结果、所属 Stage、依赖、明确 success/degradation 要求、REQ、产品/控件状态与位置、稳定技术义务和命名 AC。
|
|
267
275
|
|
|
268
|
-
Runner 支持 `package_script`、`project_binary`、`node_oracle`、`playwright_test
|
|
276
|
+
Runner 支持 `package_script`、`project_binary`、`node_oracle`、`playwright_test`;正式验收中的 package script 必须能恢复静态 Node entry 及其本地依赖闭包。Proof surface 支持 `ui_browser`、`runtime_behavior`、`api_contract`、`data_state`、`security_boundary`、`population_coverage`、`implementation_structure`。Execution target family 是有界的 `browser`、`native`、`desktop`、`service`、`process`、`external`,role 是 `product`、`support`、`observer`;required ref 只能指向具有 family/cold-start/production-root capabilities 的 product target。Browser target 只能由 `playwright_test` 证明,Native/desktop target 只能由 `project_binary` 证明。
|
|
269
277
|
|
|
270
278
|
### 一个 Contract 与 Source Claim
|
|
271
279
|
|
|
272
280
|
用户选定的一次完整交付始终只有一个 Contract 和一个 Final Gate。Outcome 只按“可独立判断、可定向验证”的结果拆分;模型输出长度、YAML/文件长度、前后端层、模块数量、并行偏好或 Agent 容量都不是拆分依据。
|
|
273
281
|
|
|
274
|
-
V2 强制至少一个真实 `source_path` 与一个 `source_claim`,且每个声明的 Source 文件至少包含一个 Material Item。Authoring 阶段必须在原始 Markdown 中仅插入不渲染的 `ty-source-item:start/end` 标记,不得改写 Item
|
|
282
|
+
V2 强制至少一个真实 `source_path` 与一个 `source_claim`,且每个声明的 Source 文件至少包含一个 Material Item;每次交付还必须有一个 `aspect=architecture` 的 technical obligation Source Item。Authoring 阶段必须在原始 Markdown 中仅插入不渲染的 `ty-source-item:start/end` 标记,不得改写 Item 原文;其他每一行非空文本只能位于唯一且 schema-valid 的 handoff formal block,或内容符合 `markdown-structure`/`provenance` 封闭语法的 background 中。任意背景说明、未分类、嵌套、重叠、未闭合或空 section 均 fail closed。Marker key 与 Source Claim key 必须集合完全相等且全局唯一。Parser 能证明语法归属并阻断把任意材料性文字塞进 background,但不能证明用户已表达所有真实需求或 Source 对现实事实准确;后两者是显式上游前提。
|
|
275
283
|
|
|
276
284
|
类型化 disposition 分开整体结果、Requirement/Control/Obligation/Non-completing Claim、单一命名 Acceptance Assertion、Global Constraint/Non-goal、Risk Fact/Affected Outcome、External Confirmation 与真实决策。Outcome Source Acceptance 必须原样对应一个 `<outcome>.<check>.<assertion>` criterion,并证明至少一个被独立 Source Item 支撑的非 Result Claim。`out_of_scope` 已退休:排除原本在范围内的要求只能进入 `decision_required`。
|
|
277
285
|
|
|
@@ -289,15 +297,15 @@ V2 强制至少一个真实 `source_path` 与一个 `source_claim`,且每个
|
|
|
289
297
|
|
|
290
298
|
最终接受来自当前可执行证据,不来自 Agent 文本。Evidence Adapter 由 Runner 派生:只有 `playwright_test → playwright_json_v1` 可以证明 `ui_browser`,其余 Runner 使用 `structured_json_v2` Adapter 证明非浏览器 Surface,并在需要 capability record 时输出增量 `long-task-check-result-v3` payload。V2 payload 只保留解码兼容,不能满足非 `presence` 能力。
|
|
291
299
|
|
|
292
|
-
每个 Check 声明非空、带 Key 的 `scenario.given`/`scenario.when`,并使用 `success`、`degradation`、`recovery`、`stage_gate`、`conformance` journey role
|
|
300
|
+
每个 Check 声明非空、带 Key 的 `scenario.given`/`scenario.when`,并使用 `success`、`degradation`、`recovery`、`stage_gate`、`conformance` journey role。Global/Outcome applicability profile 绑定精确 target、journey、原子 dimensions、Given condition/input/state refs 和有序 When refs;每个 Claim-bearing Assertion 只证明一个 Claim 在一个匹配 profile 下的语义,全部实际适用 proof-surface 单元都必须覆盖。每个 Assertion 声明 `presence`、`interaction_trace`、`state_delta`、`cross_surface_consistency`、`durable_readback`、`boundary_invocation`、`external_side_effect`、`failure_injection`、`visual_render`、`design_conformance`、`design_method`、`target_runtime`、`input_variation` 中所需的 all-of 集合。除了静态 `presence`,每种能力恰好需要一条绑定该 Assertion 的当前执行记录;缺失、重复、未知或未声明记录全部 fail closed。Result 只能由 success Check 证明;success 与 degradation 不能共用一个 Check;外部边界从 observer target 观察;input variation 至少证明两个不同输入、两个输出 hash 和一个失败样例。
|
|
293
301
|
|
|
294
|
-
每个 Outcome 至少有一个非 Result 原子 Claim,且 `required_proof_surfaces` 必须 all-of 全覆盖。Claim-bearing Assertion 使用显式 Expected 比较;`truthy/falsy` 禁止,`exists` 仅允许证明 `implementation_structure` Obligation。
|
|
302
|
+
每个 Outcome 至少有一个非 Result 原子 Claim,且 `required_proof_surfaces` 必须 all-of 全覆盖。Claim-bearing Assertion 使用显式 Expected 比较;`truthy/falsy` 禁止,`exists` 仅允许证明 `implementation_structure` Obligation。每个行为型 Claim-bearing Assertion 还必须用 same-Check、Claim-local 的 `replace_json_value` 或 `replace_text` 替换错误语义,并要求无 Claim 的 target-runtime liveness Assertion 在 `preserved_assertions` 中继续通过;`replace_file` 仅保留兼容性,不能证明语义绑定。Population 必须通过真实 universe Binding 证明全集,但不能豁免这条语义 witness。
|
|
295
303
|
|
|
296
|
-
Targeted verify、Progress、status、Receipt 与 compiled cache 都不是完成权威。Final Gate 要求 clean candidate commit
|
|
304
|
+
Targeted verify、Progress、status、Receipt 与 compiled cache 都不是完成权威。Final Gate 要求 clean candidate commit,先拒绝已经 stale 的 accepted authority inputs,再从 Source 重新 Compile,在同一 Git-tree snapshot 上运行全部 Global/Outcome Check;执行前后都重新编译并核对 Contract/fragments、Source、完整 Controlling Context、verifier/runner、受支持 direct-literal 本地 verifier graph、verification inputs 与 workdir inputs 的完整受保护身份,同时复核 active identity。只有全部不变时它才可以生成 `machine_accepted` 或 `machine_accepted_external_pending`;后者仍必须明确列出外部确认项,并且不属于完整交付无漂移定理的前件。
|
|
297
305
|
|
|
298
306
|
## 兼容与迁移
|
|
299
307
|
|
|
300
|
-
|
|
308
|
+
当前 V2 的语义保证闭包还要求 full Context、architecture-classified Source obligation、原子 applicability dimensions、显式 target capabilities、带 applicability 的 Control-relation closure、Population universe carrier、Claim-local 语义 mutation、逐 method/condition 的 method-record/primary-observation artifacts、blocker-required capabilities 与受支持 direct-literal verifier dependency closure。缺少这些含义的旧 V2 Contract 会报告可索引的人工迁移 `long-task-v2-semantic-drift-authority`;必须依据 Source 重新表达。Upgrade 不会猜测这些含义,也不会把旧 Progress/Receipt 当作通过证据。
|
|
301
309
|
|
|
302
310
|
## 开发与验证
|
|
303
311
|
|
|
@@ -328,7 +336,7 @@ make validate-harness
|
|
|
328
336
|
- 它不能证明用户从未遗漏未声明需求。
|
|
329
337
|
- bounded Context keyword search 仍可能漏掉同义词或间接依赖,只能补充语义判断。
|
|
330
338
|
- Harness 不能切换 host 选择的模型,只能在第一次 Authority Lock 后要求一次用户选择。
|
|
331
|
-
-
|
|
339
|
+
- Tiny Context 不提供并行 mutation/delegation runtime;平台 Goal 可使用自身 opaque implementation delegation,但 Harness 不持久化它,也不把它当证据。
|
|
332
340
|
- 它不观测平台 token 或模型调用数。
|
|
333
341
|
- Network policy 会约束传给 runner 的代理环境,但不是操作系统 sandbox。
|
|
334
342
|
- 同用户/管理员文件篡改、系统级 Hook 绕过不在安全边界内。
|
|
@@ -1,8 +1,6 @@
|
|
|
1
1
|
# Minimal Context Harness Protocol
|
|
2
2
|
|
|
3
|
-
This project uses Tiny Context. The Harness maintains durable Context and workflow authority; project tests, CI, runtime evidence and human acceptance prove product quality.
|
|
4
|
-
|
|
5
|
-
Tiny Context has three capabilities: Minimal Context, the default Workflow Contract, and the explicitly enabled Single-Goal Long-Task Workflow.
|
|
3
|
+
This project uses Tiny Context. The Harness maintains durable Context and workflow authority; project tests, CI, runtime evidence and human acceptance prove product quality. Its three capabilities are Minimal Context, the default Workflow Contract and the explicitly enabled Single-Goal Long-Task Workflow.
|
|
6
4
|
|
|
7
5
|
## Shared Architecture Quality Obligation
|
|
8
6
|
|
|
@@ -16,16 +14,22 @@ Unless an active Long-Task binding exists:
|
|
|
16
14
|
|
|
17
15
|
1. Read `project_context/global.md`, `project_context/architecture.md`, `project_context/context.toml` and the default area root, then collect graph/trigger candidates.
|
|
18
16
|
2. Before deciding `Context Delta`, run one bounded text search over `project_context/**` using a small set of high-signal task terms such as explicit area/module names and API/schema/state/security/verification/deployment terms. Merge matching Context with manifest candidates and read only relevant files; search supplements rather than replaces semantic judgment.
|
|
19
|
-
3. For UI/product-surface work, confirm information/action/feedback ownership and use `context_surface_contract` when durable responsibility is unclear or changes
|
|
17
|
+
3. For UI/product-surface work, confirm information/action/feedback ownership and use `context_surface_contract` when durable responsibility is unclear or changes. For material UI, reconcile affected stable surface/control/target keys as Context-covered, requiring a Context update, task-local, out of scope or decision-required; traverse owning Context and `DESIGN.md`; and open every affected selected `exact-target` or `constraint`. Missing, stale, unreadable or conflicting authority fails closed for the affected claim. Local fixes and explicit non-fidelity prototypes stay lightweight.
|
|
20
18
|
4. Complete the shared `Architecture Deliberation`, then decide exactly one `Context Delta: none|required`. Update owning Context before code when durable product ownership, architecture, API/schema/data, state/recovery, dependency, security, product-surface responsibility or repeatable verification/deployment changes. Local fixes preserving durable semantics are `none`.
|
|
21
19
|
5. Use the agent/platform internal plan. Keep `Architecture Context Hit`, `Decision Rationale Hit: existing|required|none` and `Modularity Check: none|required|exception` as internal routing and maintenance questions, not artifacts or extra deltas.
|
|
22
|
-
6. Implement precisely, run project-owned verification, perform Contract Conformance including the shared `Architecture Conformance
|
|
20
|
+
6. Implement precisely, run project-owned verification, perform Contract Conformance including the shared `Architecture Conformance` and any selected-design closure below, then run the separate Context drift check. Report implementation, verification, architecture conformance, Context status and blockers. For material UI, inspect the real production entry after the first runnable vertical slice and rerun the affected cold-start journey on the final candidate; a detached route, specimen or deep link is supplemental evidence only.
|
|
23
21
|
|
|
24
22
|
The default workflow never requires a plan artifact, matrix, verdict, evidence ledger or result document. Optional scratch is not Context or completion proof. The bounded Context search creates no index, cache, state or second authority.
|
|
25
23
|
|
|
26
|
-
|
|
24
|
+
## Selected-Design Conformance Obligation
|
|
25
|
+
|
|
26
|
+
This shared obligation activates only for a selected implementation handoff. Run `ty-context design-resource preflight <handoff.md>` before UI Authority Closure. A Web/App target needs one completely acquired machine-readable canonical entry and its exact dependency closure; unresolved locators/cells/meaning, unsupported evidence or stale digests fail closed. Preflight and hashes prove input completeness/integrity, never production conformance.
|
|
27
|
+
|
|
28
|
+
Every adopted target has exactly one canonical record: `DESIGN.md` for project/system/component-family scope or the owning Screen Contract for one-screen/interaction scope. That record owns interpretation, selection basis, immutable locator/digest, condition coverage and editable-upstream update route; other layers keep only the stable key, owner/anchor and local applicability. Use the on-demand UIUX Skill for deterministic Design Source Projection. Never overwrite an adopted baseline; update upstream, approve a new immutable version and update the canonical record.
|
|
29
|
+
|
|
30
|
+
Default work keeps one ephemeral exact accounting of covered Source Items, declared verification methods, blockers, targets and conditions. Route every applicable item to the production owner, cold-start journey and an executed final-candidate project check whose failure remains attributable; one check may cover several methods only when each method/fact can fail distinctly. A selected-target, implementation or declared check-input change stales closure. Any unresolved, unmapped, unexecuted, stale or indistinguishable item blocks a complete-conformance claim and must be reported as a gap. This creates no file, matrix, Claim set, state or Gate.
|
|
27
31
|
|
|
28
|
-
For external product, architecture, technical or acceptance
|
|
32
|
+
Externally authored resources remain ordinary Source and exploration remains schema-free. `design-system-authoring` is explicit-only; `design-resource-authoring` keeps the requested scope ceiling and may reconcile final accepted decisions into the initial proposal once, but neither authoring path changes Context/code/Contract or claims acceptance. An active Long-Task projects this same obligation into its existing Claims, Assertions, bindings and Final Gate and never also runs the default closure. For every external product, architecture, technical or acceptance constraint, internally classify it as covered by Context, requiring a Context update, task-local, out of scope or decision-required; Conformance confirms it reached the correct owner and verification without shortcuts or duplicate authority.
|
|
29
33
|
|
|
30
34
|
## Long-Task Routing
|
|
31
35
|
|
|
@@ -35,24 +39,24 @@ Do not infer long-task mode from duration, complexity, file count or agent prefe
|
|
|
35
39
|
2. Explicit `/long-task-workflow` authors or resumes exactly one complete `long-task-delivery-v2` Contract for the selected delivery.
|
|
36
40
|
3. `/normal-long-task` is a retirement pointer. Otherwise remain on the default Workflow Contract, even when work is long.
|
|
37
41
|
|
|
38
|
-
Raw/revised proposals, selected design resources and mixed attachments enter one Source-bound Contract Draft loop immediately. Source inventory, refinement, provenance, markers and Contract mapping converge in the same non-authoritative `delivery-contract.yaml` until Preflight is ready and formal Compile creates Authority Lock; there is no prior or internal Source-authoring stage. A legacy Source Plan remains ordinary input. Candidate resources authorize no fidelity Claim. A selected implementation handoff must pass the shared design-resource preflight; its marked residual handoff enters `task.source_paths`, its handoff and source-profile entry/dependencies enter target Check `verification_inputs`, and Long-Task Preflight/Compile requires exact target/condition/file equality, covered Source Claims, one independent positive Assertion
|
|
42
|
+
Raw/revised proposals, selected design resources and mixed attachments enter one Source-bound Contract Draft loop immediately. Source inventory, refinement, provenance, markers and Contract mapping converge in the same non-authoritative `delivery-contract.yaml` until Preflight is ready and formal Compile creates Authority Lock; there is no prior or internal Source-authoring stage. Every non-empty line in declared Markdown Source belongs to one Material Item, the one validated formal handoff block or a closed-grammar background block containing only text-free anchors/horizontal rules or fixed-field `ty-source-provenance` comments; text-bearing headings, free-form provenance, arbitrary background prose and unclassified text fail closed unless classified as Material. At least one technical-obligation Source Item has `aspect=architecture` and maps to an independently provable architecture obligation. A legacy Source Plan remains ordinary input. Candidate resources authorize no fidelity Claim. A selected implementation handoff must pass the shared design-resource preflight; its marked residual handoff enters `task.source_paths`, its handoff and source-profile entry/dependencies enter target Check `verification_inputs`, and Long-Task Preflight/Compile requires exact target/condition/file equality, covered Source Claims, one independent positive Assertion plus typed `design_method` evidence, a distinct record path and primary-observation path/current digest for every method × condition cell, and blocker Source-item/method/capability lineage before Authority Lock. Playwright emits method evidence only when every project instance explicitly attaches both cell artifacts. After lock, resource changes use Authority Revision.
|
|
39
43
|
|
|
40
|
-
When an Outcome declares Controls,
|
|
44
|
+
When an Outcome declares Controls, all 22 canonical fields close through `field_coverage` as concrete `specified`, justified `not_applicable` or blocking `unresolved`; cross-Control/shared-state/navigation/permission/recovery meaning closes through applicability-bound `control_relation_closure` and `control_relations`, including a negative Claim when relations are not applicable. Its Product `surface_bindings` bind every Control to an owner surface, required product target, existing route/component Bindings and a root-entry success journey. Each bound Control's navigation result—or interaction, trigger or location fallback—must be proved on that target with interaction plus target-runtime evidence. Global and Outcome applicability profiles bind every Claim to its exact target, journey, atomic duplicate-free dimension assignments, Given condition/input/state refs and ordered When refs; every Claim-bearing Assertion proves one Claim in one matching profile, and every actual applicable proof-surface cell is covered without representative/pairwise sampling. Required product targets declare their family, cold-start and production-root capabilities. Selected exact/constraint targets additionally bind declared conditions and frozen inputs to current actual/comparison artifacts through `design_conformance`; `verification_method_bindings` map every handoff method to a separate positive Assertion, typed method record and distinct record/primary-observation artifacts whose current primary identities cannot be reused across cells. Every behavioral Claim-bearing Assertion has a same-Check claim-local `replace_json_value` or `replace_text` Counterfactual and a claimless target-runtime liveness Assertion that must remain passing; whole-file replacement cannot prove semantic binding. Population binds its universe carrier into the owning Check input snapshot and proves universe = eligible = observed plus valid exclusions. Every declared design-acceptance blocker preserves exact Source-item/method/required-capability provenance and resolves to a machine Claim proved on the exact capability-qualified target or a target-blocking External Confirmation; it cannot be dismissed in-band, and scope removal requires revised Source/Contract authority. These are protected Contract semantics, not a UI registry, second Gate or per-surface state.
|
|
41
45
|
|
|
42
|
-
The workflow uses one native Goal, one selected workspace, one Contract and one Final Gate. New authoring uses inline vertical Outcomes grouped by ordered Stages; existing `outcome_files` are physical compatibility only. Target profiles name required product targets
|
|
46
|
+
The workflow uses one native Goal, one selected verification workspace, one Contract and one Final Gate. New authoring uses inline vertical Outcomes grouped by ordered Stages; existing `outcome_files` are physical compatibility only. New authority uses explicit `context_snapshot_mode: full`. Target profiles name required product targets, root runtimes and capabilities; Checks declare Given/When journeys and all-of Evidence Capabilities. Compile freezes declared verification inputs plus the supported direct-literal local verifier module/config/data graph; Check inputs/outputs/artifacts remain explicitly classified runtime material, non-literal loaders fail closed, and other indirect runtime access belongs in `verification_inputs` or the named project Oracle TCB. Stage/frontier state is derived from ordinary Progress and creates no implementation gate, second Gate, Receipt, scheduler or completion authority. `F = Implementation Freedom Boundary` keeps implementation order, local planning, methods, repair/feedback cadence and optional use of one or multiple platform-native agents/subagents Goal-owned within Source/Contract, architecture, safety, forbidden-shortcut and irreversible/external-action boundaries. Harness creates no development phase/method Gate, per-edit mandate, agent allocator/scheduler, delegation state or proof; agent reports are non-authoritative and all outputs converge into the selected workspace. Anti-Degradation Assurance requires current-implementation Context to match indexed code/runtime and keeps the controlling purpose, enabling key logic, two necessary implementation responsibilities, theorem boundary and adjacent `F` protected from implicit weakening. Replacing one requires an explicit project-owner design-purpose decision and replacement proof; a new development-stage constraint must additionally close a distinct path that final proof or a lighter project check cannot cover and have positive net ROI. Mechanism changes first prove `Coverage_new ⊇ Coverage_old`, `FalseNegative_new ⊆ FalseNegative_old` and non-bypassable Authority/fail-closed/final-snapshot proof; otherwise preserve the current formal acceptance path. Only after that hard gate may positive net ROI compare anti-degradation or purpose benefit with all incremental authoring/runtime/state/recovery/maintenance/test/process/introduction/migration cost, and cost never compensates for weaker drift interception. This is project governance and verification, not another Authority, Gate or state.
|
|
43
47
|
|
|
44
48
|
After the first Authority Lock, treat `execution_model_checkpoint.required: true` as a terminal-turn boundary. Unless the user already stated an explicit task-specific choice naming current-model continuation or a model switch, end the current turn before product implementation, file edits, builds or tests and ask the user to choose `continue_current_model` or switch models and then resume. Generic continue/resume/finish/continue-goal language does not satisfy the checkpoint; later revisions do not repeat it. Harness records no model route or checkpoint acknowledgement state.
|
|
45
49
|
|
|
46
50
|
During Draft authoring, proof design or authority lifecycle work, read the applicable references in the package-managed `long-task-workflow` Skill. Use `ty-context long-task help` for CLI syntax instead of treating this startup router as a command reference. Before first Authority Lock, Preflight and Compile classify current HEAD-relative workspace changes against protected paths and declared expected/support ownership; after lock, Verify and Final Gate apply the same fail-closed categories against the immutable baseline. During first enable, protection covers only exact files present in the current package asset tree for configured managed destinations plus the exact harness config/hook files; managed directory roots and broad `.codex/**` are never exempt.
|
|
47
51
|
|
|
48
|
-
Final Gate, Stop and close recompile the source Contract and rerun every declared Check on one clean current snapshot. Final Gate is the Long-Task path's sole `Architecture Conformance` owner; do not run
|
|
52
|
+
Final Gate, Stop and close first reject stale accepted authority inputs, recompile the source Contract and rerun every declared Check on one clean current snapshot. Final Gate records the semantic and raw identity of the Contract/fragments, Source, full Controlling Context, verifier/runner, recursively frozen local verifier dependencies, verification inputs and workdir inputs before execution, then recompiles and re-hashes that full protected set afterward; any race fails closed. Final Gate is the Long-Task path's sole `Architecture Conformance` and selected-design closure owner; do not run either default-workflow closure. Required targets cannot substitute for one another; presence cannot prove behavior; resource integrity or `visual_render` cannot substitute for selected-target `design_conformance`; success and degradation remain distinct; typed boundary effects require an observer; unresolved design blockers remain blocking. `verify --explain` is a read-only declared-execution preview and creates no proof or Progress. Targeted verify is optional repair feedback only; `progress_stale` is a freshness fact, not a per-edit rerun instruction. Coalesce related edits and refresh the cheapest reliable owning Check only before intermediate reliance; implementation and Final Gate may proceed because Final Gate ignores Progress and reruns all Checks. Status, progress, Stage/frontier projections, receipts and compiled cache are audit/recovery surfaces only; prose, historical tests or Agent judgment never create acceptance. Authority Revision separates authority change from user decision: mechanically bounded revisions may auto-adopt but still invalidate affected evidence; semantic/proof/forbidden-boundary/verifier-kernel changes and unknown reasons require one exact decision. Present the self-contained brief first. If an explicit current task instruction exactly covers every listed reason, mechanically relay it without a second question; generic continuation, blanket authorization, recommendation or Agent inference never qualifies. Coalesce withdrawn candidates and ask only for the final blocking identity. An adopted revision returns to rolling execution and is never delivery completion. External confirmations remain typed and explicit: exactly fresh `machine_accepted` with no pending confirmation is the complete-delivery accepted terminal covered by the full no-drift implication; `machine_accepted_external_pending` proves only the declared machine scope and cannot authorize completing the platform-native Goal, CI, deployment or human acceptance. The theorem remains conditional on complete/accurate declared Source and a semantically sound named project oracle; Harness/runtime packages and Git metadata are explicit trusted-computing-boundary components.
|
|
49
53
|
|
|
50
54
|
Tiny Context does not create or restore platform Goals, invoke models, spawn agents, call an App Server, create branches/worktrees, merge, push, open PRs, deploy or manage process trees. `ty-context enable long-task` installs the Long-Task Workflow Skill, the retired Source Plan compatibility pointer and package-owned completion Hook.
|
|
51
55
|
|
|
52
56
|
## Durable Facts And Generated Surfaces
|
|
53
57
|
|
|
54
58
|
- Context is intended ownership/boundary/contract truth; code is current implementation truth. Treat disagreement as drift, missing work or stale Context.
|
|
55
|
-
- Long-term facts live only in `project_context/**` or `DESIGN.md`; adopted decision-relevant design targets remain Context-reachable project Source/verifier inputs through stable keys
|
|
59
|
+
- Long-term facts live only in `project_context/**` or `DESIGN.md`; adopted decision-relevant design targets remain Context-reachable project Source/verifier inputs through stable keys and exactly one canonical adoption record rather than becoming Context themselves. Generated implementation screenshots/diffs, logs, raw evidence, secrets, runtime state and receipts do not become Context.
|
|
56
60
|
- Managed `AGENTS.md` blocks, `<harnessRoot>/ty-context-managed/**` and package-managed Skills are generated and sync-overwritten.
|
|
57
61
|
- Explicit upgrades use `context_harness_upgrade`; package sync never imports retired Campaign or development-period authority state.
|
|
58
62
|
|
|
@@ -14,11 +14,11 @@ This is the restrained architecture context. Keep only facts that help a fresh a
|
|
|
14
14
|
|
|
15
15
|
- Summarize only the durable request, event, state or data flow that is hard to infer from code alone.
|
|
16
16
|
|
|
17
|
-
## Design Rationale
|
|
18
|
-
|
|
19
|
-
- Record architecture-level choices, rejected alternatives and tradeoffs that still constrain future work; leave this empty when no stable architecture reason exists.
|
|
20
|
-
- Do not invent rationale or store implementation summaries, PR notes, command output, test result claims, debug history, agent reasoning or reasons inferred only from current code shape.
|
|
21
|
-
- Architecture boundary changes should be captured here before implementation alignment.
|
|
17
|
+
## Design Rationale
|
|
18
|
+
|
|
19
|
+
- Record architecture-level choices, rejected alternatives and tradeoffs that still constrain future work; leave this empty when no stable architecture reason exists.
|
|
20
|
+
- Do not invent rationale or store implementation summaries, PR notes, command output, test result claims, debug history, agent reasoning or reasons inferred only from current code shape.
|
|
21
|
+
- Architecture boundary changes should be captured here before implementation alignment.
|
|
22
22
|
|
|
23
23
|
## Constraints And Tradeoffs
|
|
24
24
|
|
|
@@ -15,11 +15,11 @@
|
|
|
15
15
|
|
|
16
16
|
## Module Design Capsule
|
|
17
17
|
|
|
18
|
-
- Principles: stable execution constraints that should affect future module work.
|
|
19
|
-
- Design Logic: the minimum logic for choosing, rejecting, degrading or composing module behavior.
|
|
20
|
-
- Design Rationale: only durable reasons, rejected alternatives and tradeoffs that change later implementation or verification decisions; leave it empty when no stable reason exists.
|
|
21
|
-
- Do not invent rationale or store implementation summaries, PR notes, command output, test result claims, screenshot review notes, debug history, agent reasoning or reasons inferred only from current code shape.
|
|
22
|
-
- Current standards, thresholds and commands belong in the relevant contract or verification Context, not as permanent principles.
|
|
18
|
+
- Principles: stable execution constraints that should affect future module work.
|
|
19
|
+
- Design Logic: the minimum logic for choosing, rejecting, degrading or composing module behavior.
|
|
20
|
+
- Design Rationale: only durable reasons, rejected alternatives and tradeoffs that change later implementation or verification decisions; leave it empty when no stable reason exists.
|
|
21
|
+
- Do not invent rationale or store implementation summaries, PR notes, command output, test result claims, screenshot review notes, debug history, agent reasoning or reasons inferred only from current code shape.
|
|
22
|
+
- Current standards, thresholds and commands belong in the relevant contract or verification Context, not as permanent principles.
|
|
23
23
|
|
|
24
24
|
## Key Constraints
|
|
25
25
|
|
|
@@ -31,12 +31,12 @@
|
|
|
31
31
|
|
|
32
32
|
- Capture durable product goals, users, core flows, acceptance signals and non-goals.
|
|
33
33
|
|
|
34
|
-
## UX / Screen Brief
|
|
35
|
-
|
|
36
|
-
- Capture durable screen, flow, interaction, responsive and accessibility facts. Use `DESIGN.md` for visual identity and design tokens when needed.
|
|
37
|
-
- For web/front-end surfaces, record durable page responsibilities, core user judgments, persistent information boundaries and cross-page or cross-layer ownership when they guide future changes.
|
|
38
|
-
- Reference durable versioned design targets at their project-native path or URI and classify them as `exact-target`, `constraint` or `inspiration`; do not paste generated implementation screenshots, diffs or review logs into Context.
|
|
39
|
-
- When selected resources arrive through a validated `design-resource-handoff-v1`, keep only durable surface/control/target ownership and a route to its immutable Source here. Do not copy the handoff's condition/evidence/coverage index into Context; future work must open the handoff and affected exact/constraint resources and rerun shared preflight before fidelity implementation.
|
|
34
|
+
## UX / Screen Brief
|
|
35
|
+
|
|
36
|
+
- Capture durable screen, flow, interaction, responsive and accessibility facts. Use `DESIGN.md` for visual identity and design tokens when needed.
|
|
37
|
+
- For web/front-end surfaces, record durable page responsibilities, core user judgments, persistent information boundaries and cross-page or cross-layer ownership when they guide future changes.
|
|
38
|
+
- Reference durable versioned design targets at their project-native path or URI and classify them as `exact-target`, `constraint` or `inspiration`; do not paste generated implementation screenshots, diffs or review logs into Context.
|
|
39
|
+
- When selected resources arrive through a validated `design-resource-handoff-v1`, keep only durable surface/control/target ownership and a route to its immutable Source here. Do not copy the handoff's condition/evidence/coverage index into Context; future work must open the handoff and affected exact/constraint resources and rerun shared preflight before fidelity implementation.
|
|
40
40
|
|
|
41
41
|
## Verification Entry Points
|
|
42
42
|
|
|
@@ -11,8 +11,8 @@ Write project-specific facts only. Do not copy visual token values, binary targe
|
|
|
11
11
|
## Authority Boundary
|
|
12
12
|
|
|
13
13
|
- Product Surface Contract owns cross-surface responsibility, main/drilldown placement and shared invariants.
|
|
14
|
-
- This Screen Contract owns stable screen hierarchy, regions, state/navigation behavior
|
|
15
|
-
- `DESIGN.md` owns visual-system semantics, the authored token source/generation direction and
|
|
14
|
+
- This Screen Contract owns stable screen hierarchy, regions, state/navigation behavior, durable material-control semantics and canonical adoption records for one-screen/interaction-specific targets.
|
|
15
|
+
- `DESIGN.md` owns visual-system semantics, the authored token source/generation direction and canonical adoption records for project/system/component-family targets.
|
|
16
16
|
- Versioned authored design targets own their declared concrete composition for named viewport/mode/state/content conditions.
|
|
17
17
|
- Verification Context owns repeatable proof paths. Code is current implementation evidence, not silent design authority.
|
|
18
18
|
|
|
@@ -129,24 +129,24 @@ Describe composition or responsibility changes, not one-off screenshots.
|
|
|
129
129
|
- Cancellation, interruption and recovery:
|
|
130
130
|
- Cross-surface state/version consistency:
|
|
131
131
|
|
|
132
|
-
## Design Target References
|
|
133
|
-
|
|
134
|
-
Reference project-native targets; do not embed binary content.
|
|
132
|
+
## Design Target References
|
|
135
133
|
|
|
136
|
-
|
|
134
|
+
Reference project-native targets; do not embed binary content. Every adopted target has exactly one canonical adoption record. Use this Screen Contract as the canonical owner only for a one-screen/interaction-specific target. For a project/system/component-family target owned by `DESIGN.md`, fill only its stable ID, `DESIGN.md` anchor and this screen's local applicability; do not repeat the full record.
|
|
135
|
+
|
|
136
|
+
| Target ID | Canonical Owner / Anchor | Interpretation | Immutable Adopted Path / URI + Digest | Editable Upstream / Owner / Update Route | Declared Condition Coverage | Selection Basis | Local Applicability |
|
|
137
137
|
|---|---|---|---|---|---|---|---|
|
|
138
|
-
| `<stable-target-id>` | `exact-target` / `constraint` / `inspiration` | | | | | |
|
|
139
|
-
|
|
140
|
-
An `exact-target` authorizes fidelity comparison only for its declared conditions. A `constraint` governs only its named rule. `inspiration` does not authorize reproduction. For an adopted exact target/constraint, the immutable locator must be readable and the editable upstream/update route must be verified or explicitly marked as a manual/external boundary. Relevant work opens the resource rather than treating this row as consumption. Update upstream and register a new immutable version/digest; never overwrite the adopted baseline. An implementation screenshot cannot register itself as its own target.
|
|
141
|
-
|
|
142
|
-
### Selected Implementation Handoff
|
|
143
|
-
|
|
144
|
-
- Handoff Source Path:
|
|
145
|
-
- Handoff Scope Key:
|
|
146
|
-
- Affected Subject / Target Keys:
|
|
147
|
-
- Durable Owner / Update Boundary:
|
|
148
|
-
|
|
149
|
-
Fill this pointer only when selected implementation resources use a validated `design-resource-handoff-v1`. The handoff remains ordinary Source and owns its strict subject-by-eight-dimension condition/evidence/verification index; do not duplicate that changing index into Context. This Screen Contract owns durable screen/control meaning and makes the handoff/targets reachable. Consumers must rerun shared preflight and open affected exact/constraint resources; neither this pointer nor a successful digest proves implementation conformance.
|
|
138
|
+
| `<stable-target-id>` | `this Screen Contract#...` / `DESIGN.md#...` | `exact-target` / `constraint` / `inspiration` | | | | | |
|
|
139
|
+
|
|
140
|
+
The canonical record owns interpretation, selection basis, immutable locator/digest, declared condition coverage and editable upstream/update route. Leave those fields pointer-only when this Screen Contract is not the canonical owner. An `exact-target` authorizes fidelity comparison only for its declared conditions. A `constraint` governs only its named rule. `inspiration` does not authorize reproduction. For an adopted exact target/constraint, the immutable locator must be readable and the editable upstream/update route must be verified or explicitly marked as a manual/external boundary. Relevant work opens the resource rather than treating this row as consumption. Update upstream and register a new immutable version/digest in the canonical record; never overwrite the adopted baseline. An implementation screenshot cannot register itself as its own target.
|
|
141
|
+
|
|
142
|
+
### Selected Implementation Handoff
|
|
143
|
+
|
|
144
|
+
- Handoff Source Path:
|
|
145
|
+
- Handoff Scope Key:
|
|
146
|
+
- Affected Subject / Target Keys:
|
|
147
|
+
- Durable Owner / Update Boundary:
|
|
148
|
+
|
|
149
|
+
Fill this pointer only when selected implementation resources use a validated `design-resource-handoff-v1`. The handoff remains ordinary Source and owns its strict subject-by-eight-dimension condition/evidence/verification index; do not duplicate that changing index into Context. This Screen Contract owns durable screen/control meaning and makes the handoff/targets reachable. Consumers must rerun shared preflight and open affected exact/constraint resources; neither this pointer nor a successful digest proves implementation conformance.
|
|
150
150
|
|
|
151
151
|
## Verification
|
|
152
152
|
|
|
@@ -22,10 +22,10 @@ jobs:
|
|
|
22
22
|
harness:
|
|
23
23
|
runs-on: ubuntu-latest
|
|
24
24
|
steps:
|
|
25
|
-
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
|
|
25
|
+
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
|
|
26
26
|
with:
|
|
27
27
|
fetch-depth: 0
|
|
28
|
-
- uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
|
|
28
|
+
- uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
|
|
29
29
|
with:
|
|
30
30
|
node-version: "24"
|
|
31
31
|
- name: Prepare source workspace CLI
|