project-tiny-context-harness 0.2.84 → 0.6.0

package/assets/README.zh-CN.md

@@ -1,196 +1,272 @@
-# Project Tiny Context Harness 中文快速说明
+# Project Tiny Context Harness
 
-[English README](README.md)
+Project Tiny Context Harness 是给 AI coding agents 用的轻量项目记忆层，也是一套由 npm 包管理的上下文与交付 Harness。它为仓库提供耐久项目记忆、轻量默认工作流，以及显式启用的 Single-Goal Rolling Delivery（单目标滚动交付）长程工作流；它不是 Agent 调度器，也不接管 Git 编排。
 
-Project Tiny Context Harness 是给 AI coding agents 用的轻量项目记忆层，也是 repo-native context contract。
+[English](README.md)
 
-它不是新的全流程 Tiny Context 框架，也不是任务管理器。它做一件小事：把新会话 agent 最容易丢掉、但又必须长期稳定保留的项目事实，以及 Context / 代码 / 验证证据之间的读取和变更优先级放进仓库里，让下一次聊天、交接、调试或换工具时不用从头重新发现。
+产品原则是：**保留项目记忆，丢掉流程仪式感**。公开推广与 README 以英文主入口为准，中文文档作为二级入口。
 
-一句话：
+## 为什么存在
 
-```text
-Keep the memory. Drop the ceremony.
-保留项目记忆，丢掉流程仪式感。
-同时保留 Context / 代码 / 验证证据之间的优先级契约。
-```
+编码 Agent 同时需要两类能力：跨会话仍然可靠的少量项目事实，以及长任务经历多轮修改或上下文压缩后仍可信的完成检查。
 
-## 它解决什么问题
+Tiny Context 将这些能力保持为窄边界：
 
-很多 agent 在一个对话里表现很好，但换到新对话后会重新问、重新猜或重新扫描：
+1. **Minimal Context**：`project_context/**` 保存产品归属、架构、契约和可重复验证等耐久事实。
+2. **Workflow Contract**：普通任务使用 Context-first 的轻量默认循环和平台内部计划，不要求计划文件。
+3. **Long-Task Workflow**：显式使用 `long-task-delivery-v2`、编译期 Claim Coverage、一次 Authority Lock 后的模型选择、滚动修复验证与 Live Final Gate。
 
-- 项目到底要解决什么问题
-- 哪些事情明确不做
-- 架构边界在哪里
-- 哪些文件是事实源
-- 改完以后应该跑什么验证
-- 上一次任务留下了哪些长期约束
-- Context、实现和验证证据冲突时谁优先
+它不会启动或切换模型，不会创建 Agent、分支或 worktree，不会 merge、push、创建 PR 或部署，也不会取代项目测试和人工产品验收。
 
-Project Tiny Context Harness 把这些内容压缩到几个 repo-native 文件里，并通过简单工作流约束 agent 先读 Context、判断是否 context-first、实现后做 drift check：
+## 快速开始
 
-- `AGENTS.md`
-- `project_context/context.toml`
-- `project_context/global.md`
-- `project_context/architecture.md`
-- `project_context/areas/**`
+```powershell
+npx --yes project-tiny-context-harness ty-context init
+# 已有项目文件的仓库：
+npx --yes project-tiny-context-harness ty-context init --adopt
 
-Fresh agent 先读这些文件，再开始改代码。
+npx --yes project-tiny-context-harness ty-context validate-context
+npx --yes project-tiny-context-harness ty-context doctor
+```
 
-## 和传统 Tiny Context 流程的区别
+更新 package-managed 表面：
 
-这个项目以前尝试过更重的阶段式 Tiny Context：阶段状态、任务流转、PRD / 技术方案 / 实现 / 评审 / 测试 / 发布产物和多个 gate。
+```powershell
+npx --yes project-tiny-context-harness ty-context upgrade
+npx --yes project-tiny-context-harness ty-context sync
+```
 
-后来放弃这个方向，原因很直接：
+`upgrade` 先执行安全迁移再同步；资产刷新不会推断或覆盖用户编写的 Context、Source、Delivery Contract 或历史文件。
 
-- 中小任务里，阶段流转和产物校验会显著拖慢执行。
-- 现代 coding agents 已经内化了很多普通软件工程循环：理解、设计、实现、测试、修复。
-- 真正值得保留下来的不是“每次任务都走完整流程”，而是“新 agent 能快速恢复项目长期事实”。
+默认 Profile 是 `core-portable` 与 `workflow-default`。显式启用长程能力：
 
-所以当前默认方向是 Minimal Context Harness：只维护高密度、长期有效、能帮助恢复上下文的项目事实。
+```powershell
+ty-context enable long-task
+```
 
-一个典型失败场景是 ABCD 模块链：A/B/C 是上游，D 是下游。现在做 D 的需求时发现能力缺口；如果没有 Context 和优先级约束，agent 很容易为了让 D 完成而去改上游 A/B，因为当前代码让这条路可行。但真正需要判断的是：D 是否有权改 A/B？缺口是不是属于 C 的契约？是否必须先声明 `Context Delta`，让项目意图变化被确认后再实现？代码能说明“现在怎么改得动”，不能说明“项目意图是否允许这样改”。Tiny Context 要补的就是这一层 repo 内长期事实和优先级契约。
+它会安装 `/source-plan-authoring`、`/long-task-workflow` 与完成 Hook，不安装模型 Worker、Agent runtime、调度器或 Git 编排资产。
 
-Tiny Context 有两个核心层。Minimal Context 是长期事实源层：说明哪些项目事实写在 `project_context/**` 或 `DESIGN.md`。流程契约 / Workflow Contract 是 agent 行为层：规定先读 Context，让 foundation / contract / decision-rationale / architecture 等原则和契约类 Context 优先解释当前代码便利路径，再判断 `Context Delta`、编译 Task Contract、必要时用 `plan.md` 承载可见执行面、按契约实现，最后做 Contract Conformance 和 Context drift check。
+## Minimal Context 与默认工作流
 
-对于长程任务，Harness 提供两个显式调用的长程任务 Skill。普通长程任务用 `/normal-long-task`：它把方案和验收输入临时放到 `tmp/ty-context/plan-acceptance/**`，生成或复用完整验收清单，并可输出普通目标模式文本。如果外部规划模型参与，推荐仍然只给两份产物：`《开发方案》` 作为执行方向和 plan traceability source，`《验收清单和测试用例》` 作为 Codex target-mode acceptance input packet。第一份应包含可逐项追踪的 plan item、预期落点 surface、full scope 与 sampled/optional 边界；第二份应包含 AC、required evidence、测试命令、真实产品路径 / core path、证据分层、无效证据、状态机、local audit 和 blocker。Source Pack 只是临时上传材料，不是 durable Context。如果方案里已经有明确、具体的“验收清单”，`/normal-long-task` 会直接复用那份清单并单独写入完整验收清单文件；两份输入包走 strict mode，如果两份内容无法完整解析出 required fields，或第二份缺少 required evidence、verification method、fail condition、状态机、无效证据规则等必要字段，Skill 会停止并列出缺失项，不生成完整验收清单或目标模式文本。
+默认读取顺序是：
 
-Composite Long-Task Workflow Skill 用 `/composite-long-task-workflow`。如果下一步明确要 Superpowers-backed 目标模式执行，推荐在三份输入都存在后调用：`Product / Architecture Source`（产品/架构原始意图源）、`Technical Realization Plan`（具体技术实现方案）和 `Acceptance Checklist`（验收清单）。它不做复杂度分流；调用它表示上游已经决定使用 composite long-task execution。它不要求先跑 `/normal-long-task`，但也不会把产品方案现场翻译成技术方案；如果只有产品/架构方案和验收清单，Skill 会用 Missing Fields Report 停止并报告缺少 `Technical Realization Plan`。两份输入兼容只限第一份明确包含产品/架构源和技术实现方案两个章节。`Technical Realization Plan` 必须已经满足 Superpowers-ready Markdown implementation plan 的必填字段；满足时它跳过方案生成，直接绑定 Superpowers 执行，不满足时直接中断并报告缺失字段，不生成 prompt。它输出 `workflow-protocol.md`、`execution-binding.md` 和可直接用于 Codex Goal mode 的薄 `goal-objective.txt`，不是把完整 workflow 塞进 4000 字 Goal：Goal 只保留持续完成契约，完整可执行流程放在 protocol snapshot 和 task-specific binding。预期运行效果是显式融合而不是让 agent 自行发挥：先 Tiny Context 流程契约，再三份输入权威，再编译 task-state，再进入 Superpowers implementation slice，每个 slice 更新 canonical state/evidence，derive 出阅读视图，经过 slice/epoch gate，最后 final-gate 计算完成。这个 workflow 是面向 Superpowers execution 的 Tiny Context 适配层，对齐官方 Superpowers skills，但不是上游维护的 schema；它不是 Tiny Context 流程契约本身、不是业务事实源、不是普通 prompt generator、也不是 Superpowers fork。它可以在 Superpowers 外层增加 Tiny Context 的权威、对图纸和验收门禁，但不能重新定义、重复或分叉 Superpowers 执行机制。如果未来改动让 Tiny Context 新增步骤和官方 Superpowers 职责冲突、重复或覆盖，应停止修改并提示边界冲突，不要静默合并两套流程。它不生成技术方案或验收清单、不执行计划、不证明完成，也不会把临时 state、derived views 或 verdict 注册成 `project_context/**`。三输入是上游权威，state / derived views / validator / auditor 不能改写它们。`task-state.json` 是唯一执行状态源，`events.ndjson` 追加记录状态变更，`derived/**` 只生成 local audit、plan-conformance matrix、final acceptance verdict、progress ledger、evidence index、context alignment、final summary 和 final card 等阅读视图。完整验收行按外部审计证据处理：proof chain 来自验收清单，fresh evidence 必须通过 `task-state.evidence[]` 满足每个 required layer，存在 material drift、缺 required layer 或未批准 sibling substitution 时不能标 `complete`。Goal mode 表述必须区分 `audit_task_complete`、`acceptance_target_status`、computed `product_goal_complete` 和 resolver-owned `completion_output_status`：实现/执行目标只在 `ty-context composite-long-task final-gate` 计算出 `product_goal_complete=true` 且 `completion_output_status=accept` 时完成；只读审计目标可在 `audit_task_complete` 时结束，但 verdict 不是 accepted/complete 时，回复写 `Audit workflow completed; acceptance target not complete.`，不能用未限定的 `Goal achieved` 或 `update_goal(status="complete")` 表示用户验收目标已完成。
+```text
+project_context/global.md
+project_context/architecture.md
+project_context/context.toml
+default area root
+manifest/trigger 命中的少量 area/role Context
+```
 
-Machine-verifiable proof layer（如 UI/browser、runtime、API/schema、data artifact、integration、test）不能靠截图、final card、validator pass、matrix/verdict 行或 prose evidence 完成；必须有 `assertion_result.status=passed`、命令和 assertion exit code 为 0、target AC/layer 匹配、positive/negative assertions 通过、reviewable artifacts，且没有 failed/stale `negative_evidence_scan`。UI Path AC 不能用 component screenshot、storybook、viewmodel、mock/unit、diagnostic page 或 API-only evidence 替代 owner page/browser 主路径；`未验证`、`不可用`、`暂不可用`、`页面无明显变化` 等 owner-surface forbidden state 会使 AC/layer 失效。
+只有近乎所有任务都需要的恢复事实才使用 `read_policy = "default"`；专业架构、契约、部署和历史细节应由任务触发按需读取。
 
-三份输入还必须承载 capability-first delivery 边界。Product / Architecture Source 声明 `delivery_scope`、`full_population_required`、哪些 representative samples 能验证 claim、哪些不能验证、以及 `out_of_scope_backlog`。每个 Technical Realization Plan item 声明 delivery scope、capability target、representative samples、full-population boundary 和 non-required population。每个 Acceptance Checklist item 声明 acceptance scope、`ac_validates`、`ac_does_not_validate`、sample boundary 和 full-population requirement。source / plan / checklist 在 system capability build、representative sample validation、full population operation 之间冲突时，`scope_conflict_requires_decision` 阻塞完成。sample evidence 或 framework-only implementation 不能证明 all-provider、all-interface、all-platform 或 full-population 完成，除非 AC 明确批准；未显式要求 full population 时，generated views 必须报告 `not_in_scope`。
+### 双路由 Context 发现
 
-`ty-context composite-long-task compile` 对这三份输入使用严格的 heading-based grammar。Product / Architecture Source 是一个文档级对象，只读固定字段。Technical Realization Plan 里的 PI 只有写成 `## PI-001: ...` 这类 Markdown heading 才是正式定义；Acceptance Checklist 里的 AC 也只有 `## AC-001: ...` 这类 heading 才是正式定义。heading section 内字段必须使用固定 `key: value`、缩进列表或 `key: |` 多行块。正文、表格、mapping preview、`related_acs` / `related_plan_items` 和普通列表里出现的 `PI-001` / `AC-001` 都只是引用；旧式 `- PI-001: ...` 或 `- AC-001: ...` 后面跟字段的写法会在 compile 阶段带文件和行号报错。
+在判断 `Context Delta` 前，Agent 不再只依赖 `triggers`、`read_when` 与 `read_policy`：
 
-Strict V2 输入还要求 canonical Product / PI / AC 字段组。Product Source 必须包含 `scope_fit_decision`、`selected_scope_fit_slice`、`owner_boundary`、`primary_capability_path`、`non_completing_outcomes`、`assertion_policy` 等 Scope Fit / owner 字段；PI 必须包含 owner、trigger、state transition、observable result 和 assertion support 字段；AC 必须包含 `assertion_command`、`assertion_artifacts`、`positive_assertions`、`negative_assertions`、`machine_blocking`、`invalid_completion_signals` 和 `assertion_result_required`。未知字段、重复字段、表格字段和缺失 canonical 字段都会 compile fail。Canonical proof layers 是 `code`、`api_schema`、`worker_runtime`、`data_artifact`、`integration`、`ui_browser`、`security_redaction`、`all_provider_all_runner`、`cleanup_stale_scan` 和 `test`；`runtime` / `browser` / `api` / `data` / `security` 只是 legacy alias，会编译到 canonical 名称，且 `code` 不能单独完成 machine-backed AC。Evidence index 同时生成 `derived/evidence-index.md` 和 `derived/evidence-index.json`。
+1. 先根据 `context.toml` 的 area、role、trigger 和 graph 收集候选；
+2. 再从任务中提取少量高信号词，例如明确的 area/module 名、API、Schema、state、security、verification、deployment 词，对 `project_context/**` 做一次 bounded text search；
+3. 合并两路候选，只读取真正相关的 Context；
+4. 再判断 `Context Delta: none|required`。
 
-对于非平凡 slice，生成的 composite workflow prompt 要求使用结构化 `slice-delta.json`。executor 通过 `ty-context composite-long-task apply-slice-delta <workdir> <slice-delta.json>` 应用 delta，然后运行 `ty-context composite-long-task derive` 和 `ty-context composite-long-task slice-gate`。每个 delta 记录 touched plan items / ACs、code changes、closed / remaining proof layers、blockers、cleanup assertions、`progress_value`，以及带有 `proves`、`does_not_prove`、freshness、redaction 和 reviewability 的 canonical evidence records。默认 slice 策略是把同一 AC、runtime 场景、proof 环境或验证路径下的 2-4 个强相关 missing layers 合并处理；单 gap slice 只留给 blocker、contradiction 或小型 metadata cleanup。prompt 还会要求先分类 missing layer、复用 DB/API/Browser 环境时使用唯一 proof prefix 和 cleanup assertion，并在生成 derived artifacts 后做 stale/overclaim scan。
+这次搜索只补充语义判断，不会把所有关键词命中都当成 Authority，也不会创建向量/持久索引、缓存、Registry、search state 或第二权威。它仍可能漏掉完全不同的同义词或间接依赖，因此高风险任务还需要 Architecture Context Hit 与收尾 Conformance。
 
-当 slice 声称关闭 machine-verifiable layer 时，`slice-delta.json` 的 evidence record 还应包含 `command_exit_code`、`assertion_result`，UI/browser 等需要时还应包含 `negative_evidence_scan`；derived matrix/verdict 只展示 assertion status 和 blocker，不能替代 assertion 执行。
+`ty-context doctor` 会报告确定性的默认 Context 文件/字节规模、单文件与总量软预算超限，以及字节完全相同的默认文件。这些只是维护提示，不是新验证 Gate 或运行时状态。
 
-严格完成判定只看 current attempt，并且统一经过 Trusted Evidence Kernel，再经过 completion-output resolver；final-gate、`validate-superpowers-state`、state-backed `validate-plan-acceptance` 和 derived completion views 使用同一个 kernel result。`compile` 从每个 machine-blocking AC 的 `assertion_command`、`assertion_artifacts`、proof layers、required tests、positive/negative assertions、invalid completion signals 和 final evidence expectation 生成 required command specs；`start-attempt --mode product_task|harness_task` 创建当前执行身份；`run-assertion` 记录 assertion command run；`record-evidence` 把 artifact 注册成 canonical EvidenceRecordV2；`final-gate` 只从当前记录重算。EvidenceRecordV2 必须包含 attempt/source/product/plan/checklist hash、git head、worktree fingerprint、command spec/run id、command line / exit code、artifact path/SHA/mtime、target AC ids、target PI ids、target proof layers、assertion status / exit code、positive assertions、negative assertions、invalid completion signals、negative evidence scan 和 required test ids。legacy v1 evidence、历史 `events.ndjson` complete 事件、旧 `derived/**` complete 视图、matrix/verdict/evidence-index/final-summary 行、validator pass、final card、auditor prose、AC summary-only proof、未注册临时 JSON 和手写 status 文件都不能完成 machine-blocking AC，也不能把 generated final answer 升级为 `accept`；更新的 failed command、Playwright/JUnit/test result 失败、owner DOM forbidden state、source/worktree drift、当前 task-state false/partial 或 derived/state mismatch 会让同 AC/layer 的旧 passed evidence 失效。
+Context 负责耐久的意图和边界，代码负责当前实现，测试/CI/浏览器或运行时证据/人工负责行为与产品验收。
 
-final-gate 在 kernel 和 output resolver 内部固定执行：load 三输入、重算 source hashes、load task-state、resolve current attempt、load required command specs、load command-run records、load registered EvidenceRecords、discard stale evidence、scan unregistered assertion JSON、contradiction scan、AC-010 bootstrap prevention、under-specified AC checks、Harness Drift Lock、protected baseline guard、validate scope conflicts、重算每个 AC、重算每个 PI、重算 `acceptance_target_status`、重算 `product_goal_complete`、resolve `completion_output_status`、regenerate `derived/**`、append event。machine-blocking AC 缺 assertion command/artifacts/assertions/invalid signals，UI proof 缺 browser/e2e/smoke/trace，final evidence 只指向 generated view，test cases 只有人工查看，或无法产出 `assertion_result` 时，AC 是 `under_specified`，PI blocked，`product_goal_complete=false`。AC-010 / final-gate summary 不能反向证明其它 AC：如果 summary AC passed 但其它 required AC missing / failed / stale，则 summary AC invalidated，reason 是 `final_gate_cannot_bootstrap_from_summary_only`。
+普通任务：
 
-Harness Drift Lock 把产品证明和验收工具链证明拆开。`product_task` 修改 Playwright spec、测试、assertion generator、AC010 helper、evidence writer、final-gate、validator、derive、task-state reducer、composite workflow Skill/protocol 或相关 Makefile/package test target 时，直接输出 `harness_drift_detected`、`acceptance_target_status=blocked`、`product_goal_complete=false`，并使用文案“本轮修改了验收工具链或测试本身，不能用被修改后的验收证明同一轮产品完成。请拆成独立 harness_task。”`harness_task` 可以修改 harness，但必须有 stale evidence、historical complete、derived contradiction、AC010 summary-only、target mismatch、API-only-for-UI、negative evidence after pass、source hash mismatch、dirty worktree mismatch、missing assertion_result、test weakening、scope leakage、missing UI/browser owner-surface proof、missing negative semantic proof 和 happy path fixtures；它只证明 harness 修对，不证明产品任务完成。`protected-harness-baseline.json` 保护 final-gate、validator、derive、evidence registration、assertion schema、fixture expected outcomes、workflow protocol、Skill markdown 和 test runner scripts；product task 改 baseline blocked，harness task 改 baseline 必须写 reason 并跑 fixtures。HFC-003 是持久 false-completion regression suite：35 个提交的 mini workdir 加一个 runner 覆盖 Trusted Evidence Kernel、completion-output resolver、generated-output scanner、选定 CLI smoke path 和 happy path，并作为 harness 改动的 package release blocker。
+1. 读取 core/default Context，收集 manifest 候选；
+2. 在 `project_context/**` 做一次 bounded Context search；
+3. 决定 `Context Delta: none|required`；
+4. 耐久语义改变时先更新 owner Context；
+5. 使用平台内部计划；
+6. 实现并运行项目验证；
+7. 执行 Contract Conformance 与 Context drift 检查。
 
-生成的 composite workflow prompt 使用 Slice Gate / Epoch Gate / Final Gate 分层节奏，而不是每个 slice 后都跑完整 final gate。Progress Accounting 在 state 和 generated `derived/progress-ledger.*` 中记录 AC acceptance completion、engineering implementation progress、runtime/proof progress、system capability progress、representative sample progress、real object coverage、full population operation progress、artifact budget 和 workflow overhead。每个 slice 需要声明 artifact budget、proof-layer milestone 状态和 cleanup expectation。workflow overhead backpressure 要求 executor 批处理共享的 provider/browser/runtime/security epoch proof environment，清理 stale artifact，并选择 Next 3-5 high-value clusters 来优先关闭最多阻塞 AC / proof-layer gap。
+默认工作流不要求 `plan.md`、matrix、verdict、evidence ledger、持久检索索引或第二份执行计划。任务时长、文件数和复杂度不会自动激活长程状态。
 
-重要使用提示：Minimal Context 有意把 Context 读取顺序、Context / 代码优先级和漂移检查保持为 agent 级软约束，而不是机器强制 edit-order gate。这个取舍适合短任务，但长任务、大上下文、多次交接或多轮验证时预期会漂移。单靠 Superpowers 在这类压力下仍可能漂移：它能增强执行纪律，但本身不负责保留上游 source authority、防止 scope shrinkage、证明完整符合 Technical Realization Plan，或按 Acceptance Checklist 逐 AC 强制证据成立。普通 checklist 准备需要 `/normal-long-task`；已有产品/架构原始意图源、具体技术实现方案和验收清单且需要 Superpowers-backed execution 时，可直接用 `/composite-long-task-workflow`。`Product Context Delta` 判断产品逻辑、页面职责、信息架构和验收语义是否需要写入 Context；`Technical Context Delta` 判断 API/schema、模块边界、runtime/state、验证/部署路径和稳定技术取舍是否需要写入 Context。`task-state.json` 是唯一执行状态源，`events.ndjson` 追加记录状态变化，`derived/**` 是生成阅读视图，`task-state.evidence[]` 是 canonical evidence ledger；local audit 只是 generated progress/recovery view，不能裁判完成；审计流程完成也不等于被验收目标完成。使用目标模式执行方案时，目标结束条件对齐 computed `product_goal_complete=true`；只读审计目标才可把 `audit_task_complete` 当元任务结束。validators、auditor、Superpowers verification 和 generated views 仍是有用的执行检查，但不能覆盖 Trusted Evidence Kernel，也不能成为 product proof。`validate-plan-contract`、`validate-superpowers-state` 和 `validate-plan-acceptance` 只检查临时 artifact/state 自洽、引用存在、弱证据 complete 行、缺 required proof layer、material/critical drift、sibling substitution 和已声明的 surface/architecture binding 一致性，不证明产品质量。有 subagent 能力时，composite workflow prompt 会把 subagent 作为只读 auditor 加在主 agent 自证和 validator 之后；auditor 用固定 auditor checklist 找 gap，不是 proof source。Superpowers review 和 verification 仍然有价值，但不能覆盖 Tiny Context gates；通过 Superpowers review 不等于证明 plan conformance 或 checklist acceptance。
+每次交接只报告一个 Context 结果：
 
-最终顺序中的 final-gate 还包含 AC Evidence Assertion Gate 和 Negative Evidence Scan Gate；`validate-superpowers-state` / state-backed `validate-plan-acceptance` 会拒绝缺少或失败的 assertion-backed machine proof、negative evidence contradiction、target AC/layer 不匹配和 stale assertion evidence。它们仍只验证 assertion report 与 proof layer 的绑定、freshness、reviewability、redaction、negative contradiction 和 state/derived consistency，不执行项目测试本身，也不证明产品质量。
+```text
+Context: updated <文件/原因>
+# 或
+Context: no durable fact change
+```
 
-错误融合防线：不得把 `workflow-protocol.md` 注册进 `project_context/context.toml`，不得把它当业务 Context，不得让 `derived/**` 反向改写 Product / Plan / Checklist，不得把 local audit 或 Superpowers review 当质量证明，不得把 sample evidence 当 full population proof，不得在 Source-to-Context Coverage 或 Context-to-Implementation Binding 仍有 unresolved required gap 时声称完整对齐，不得手写 `product_goal_complete`，final-gate 未通过前不得把实现 Goal 标成 complete。
+### 架构与模块质量
 
-额外的 machine-proof 防线：不得把 screenshot-only、final card、validator pass、matrix/verdict 行、prose evidence、component/storybook/viewmodel/mock/unit/diagnostic page 或 API-only path 当成 UI/browser/runtime/integration/test AC 的完成证明。
+技术架构能力属于 Minimal Context。高风险工作在平台内部计划中使用 `Architecture Context Hit`、`Decision Rationale Hit: existing|required|none` 和 `Modularity Check: none|required|exception`，不创建 Task Contract 或固定 `plan.md`。
 
-## 当前最佳实践
+只有新长期模块/能力、公共 API/Schema/data/persistence、source of truth/state ownership、dependency direction、跨 area、migration/security/recovery 或可复用抽象才触发架构 Gate；小修复不支付这项成本。Gate 要明确 owner、唯一事实源、依赖方向、接口/状态生命周期、失败/恢复/兼容、禁止绕过路径和项目自己的可执行架构检查。
 
-短程任务直接使用流程契约和 Context 层：
+Harness 只路由仓库原生 lint/AST/dependency/contract check，不实现跨语言通用架构分析器。`check-modularity` 的语句数/分支风险会定位到最高风险函数和行号。
 
-```text
-流程契约 + project_context/** -> 实现 -> 验证 -> drift check
-```
+### 视觉交付指导
 
-长程任务先外化目标，再进入实现：
+对设计系统、重设计、高保真实现或 visual polish，`context_uiux_design` 在任务内部维护一个风险比例化的 Visual Coverage Set，覆盖生产 surface/component、viewport、theme/mode、state、content stress 与 accessibility/motion 条件。它只是内部计划，不是必需 matrix 或新权威。耐久 surface/interaction 事实仍属于 `project_context/**`，耐久视觉语义与理由属于 `DESIGN.md`；项目只声明一个精确 token 手工事实源和一个生成方向。`context_development_engineer` 把这些意图绑定到生产组件/真实 route，只报告真正渲染和检查过的组合，静态 kit 或 mock 不能替代产品 UI 证据。
 
-```text
-Web GPT 或其他外部规划模型产出长任务源输入
--> /normal-long-task 生成完整验收清单和可选普通目标模式文本
--> 需要 Superpowers-backed 多组合长程任务工作流时，/composite-long-task-workflow 消费 Product / Architecture Source + Technical Realization Plan + Acceptance Checklist
--> Superpowers 得出具体落地执行片段
--> 执行中维护 plan-conformance-matrix，最后生成 final-acceptance-verdict
--> 每个执行片段都回到流程契约 + project_context/**
-```
+显式 Long-Task 仍通过现有 Requirement、Control、Assertion、`ui_browser`、verification input 与 `external_confirmation` 表达视觉要求。影响验收的截图 baseline 是冻结的 verifier input，生成截图/diff 只是 review artifact，主观设计或新 baseline 批准保持外部确认。这项指导不新增视觉 Schema、risk level、lifecycle state、Gate 或必需 artifact，也不修改默认 Workflow Contract。
 
-这里的 Superpowers 指具体的 [obra/Superpowers](https://github.com/obra/superpowers) 插件/开源工作流，不是泛化的执行规划替代品。`/composite-long-task-workflow` 接受输入包后会冻结 `workflow-protocol.md`、写入 `execution-binding.md` 并生成薄 `goal-objective.txt`；有 subagent 支持时优先用 `superpowers:subagent-driven-development`，否则用 `superpowers:executing-plans`；涉及行为变更时用 `superpowers:test-driven-development`；完成声明前先 derive all views，再用 `superpowers:verification-before-completion`、`ty-context validate-superpowers-state <dir>`、`ty-context validate-plan-acceptance <dir>` 和 read-only auditor 检查，最后由 `ty-context composite-long-task final-gate <dir>` 计算 `product_goal_complete`。
+### 可选 Source Plan Authoring
 
-原因是漂移控制。流程契约 + Context 层是软约束，短任务里通常能让 agent 按预期执行；长程任务里，Context 仍然能记录符合预期的事实，但 Context 到代码 的实现步骤会随着上下文窗口变大、多次交接、subagent 拆分和多轮验证而漂移。单靠 Superpowers 也仍可能在复杂长程执行压力下漂移：它增强执行纪律，但不天然保留 source authority、防止 scope shrinkage、证明完整符合 Technical Realization Plan，或按 Acceptance Checklist 逐 AC 强制证据成立。产品/架构原始意图源、具体技术实现方案、验收清单、显式长程任务 Skill 调用、目标模式文本、canonical task state、generated derived views 和可选 Superpowers 执行层，把“产品/技术 Context 有没有先对齐”“有没有按图纸实现”和“有没有按验收证据完成”都外化成可恢复、可审计的临时执行标准，同时不恢复阶段式 gate。
+只有用户明确要求初版方案、源方案、方案源稿、Source Plan，或要求审计/重构这类后续实现与 Contract Authoring 的输入时，才使用 `/source-plan-authoring`。
 
-对于高风险产品方案、架构方案、技术方案或验收方案输入，流程契约应先在 `plan.md` 或等价临时计划面里可见化，再进入实现。这个计划面把 Source-to-Context Coverage 和 Context-to-Implementation Binding 分开：前者把每条长期 source 约束映射到 existing Context hit、Context action、owning Context 和 coverage status；后者把 Context fact 映射到 implementation obligation、expected surfaces、implemented paths、forbidden shortcuts、verification path 和 binding status。Source coverage 仍有 `under_scoped` 或未处理的 `new_context_required` 时不能声称按方案完整实现；binding 仍有 `partial`、`missing`、`blocked`、`needs_user_decision` 或 `contradicted_by_current_state` 时不能声称按 Context 完整落地。
+它输出一份自包含 Markdown Source Plan：
 
-small code task 不应该套完整 `plan.md` / trace 表。这里的 small 按语义风险判断，不按代码行数判断：现有 Context 已足够，且不改变 durable product、architecture、API/schema/data、runtime/state/recovery、verification/deployment、security/redaction 或 surface ownership 事实，才算 small。一个一行 schema 改动也可能不是 small；大范围机械样式清理反而可能仍是 small。
+- 保留直接要求及其限定条件；
+- 必要推导必须标记并写明 `Derived From`；
+- 无来源的新产品选择进入 `DEC`/`decision_required`；
+- Outcome 只按可独立判断的可观察结果拆分；
+- 重要 Source 项使用稳定语义 Key 与显式 Anchor；
+- 强制技术义务使用 `OBL`，非强制实现建议使用 `HINT`；
+- 每个已决定的 `CTRL` 分别记录 Location、User task、Trigger、Input、Loading、Empty、Success、Failure 与 Feedback；
+- 明确“不算完成”的 Source 含义使用 `NCOMP`；
+- 每个 `RISK` 明确 Fact、单个 Affected Outcome、Basis 与 Consequence，无法确定时进入 `DEC`；Fact 精确使用 Runtime 的十个名称：`public_api_or_schema_change`、`persistent_data_change`、`data_migration`、`security_boundary_change`、`permission_boundary_change`、`irreversible_external_effect`、`critical_user_path`、`full_population_operation`、`multi_repository_change`、`weak_observability`；
+- 每个 AC 只代表一个 Given/When/Then 可观察场景，显式列出对应 `REQ`/`CTRL`/`OBL`/`NCOMP` Key，且不能首次偷渡新需求。
 
-## 适合谁
+它不更新项目 Context，不绑定真实仓库 owner/path/runner，不生成 Delivery Contract YAML，不执行实现，不创建工作流状态，也不声明完成。`HINT` 不是 Material Source Item；Source Plan Skill 不输出 `ty-source-item` Marker，Marker 由后续 repository-aware Long-Task Authoring 插入。Source Plan 是 Source，不是 Contract Draft。推荐结构只是 Authoring Fast Path；普通 prose/Source Plan 或普通文本方案仍可直接作为 Long-Task Source。
 
-适合：
+## Single-Goal Rolling Delivery
 
-- 经常用 Codex、Claude Code、Cursor、Gemini CLI、OpenCode 等 agent 改代码的项目。
-- 经常开新 chat，agent 反复重新理解项目的项目。
-- 想保留项目意图、边界和验证路径，但不想引入完整流程文档链的维护者。
-- 多 agent / 多工具协作时，需要一个工具无关的 repo 内事实源。
+只有用户显式调用 `/long-task-workflow`，或当前 worktree 已有 active long task 时才使用。它固定为：
 
-不适合：
+- 一个平台原生、持续的 Goal；
+- 一个用户选定的仓库/worktree；
+- 一次完整选定交付、一个 Contract、一个 Final Gate；
+- Outcome 依赖只表示验收就绪关系，不表示 Worker 调度；
+- 第一次 Authority Lock 后、正式实现前有一次用户模型选择；
+- 当前 Goal 内部滚动展开实现 Frontier；
+- targeted verify 只用于修复，永远不能 accepted；
+- Final Gate 在一个当前快照上重跑全部 Check；
+- Stop Hook 在结果 stale 时阻止完成。
 
-- 替代测试、CI、review 或人工验收。
-- 自动执行完整 Tiny Context。
-- 做代码语义索引或外部文档检索。
-- 给每个任务强制生成 PRD、技术方案、测试报告和发布文档。
+Long-Task Contract Authoring 会尽量保留 Source 中已有的稳定 Key 与 Anchor。保持产品含义的结构分解和有真实证据的仓库绑定可以继续；新增业务规则、默认值、恢复行为、权限或范围必须进入 `decision_required`，不能静默加入。缺少推荐 Source Plan 结构不构成阻塞，但激活前必须完成只插入标记、不改写原文的 Material Source Item 枚举。
 
-## 快速试用
+第一次正式 Compile 成功前，`delivery-contract.yaml` 是同一份非权威 Contract Draft。`/long-task-workflow` 可以跨多轮仓库/Context 读取和 Preflight 修复持续修改它，不要求一次响应生成完整 Contract。不存在单独 Contract Draft Skill、Draft Receipt 或 Authoring State。
 
-npm 新包名还在等待发布。如果 `project-tiny-context-harness@latest` 尚未可用，可以先用源码 smoke 路径：
+第一次成功 Compile 创建 Authority Lock，并返回：
 
-```sh
-git clone https://github.com/Seven128/project-tiny-context-harness.git
-cd project-tiny-context-harness
-npm ci
-npm run smoke:quickstart
+```json
+{
+  "execution_model_checkpoint": {
+    "required": true,
+    "phase": "post_authority_lock_pre_implementation",
+    "options": ["continue_current_model", "switch_model_then_resume"]
+  }
+}
 ```
 
-发布完成后，普通项目使用：
+Agent 此时在实现前只暂停一次，请用户选择：继续当前模型，或切换模型后恢复同一 active Long-Task。如果用户已明确给出本任务的模型策略，则视为已完成选择。后续 `compile --revise` 返回 `required: false`，不会重复暂停。Harness 不会自动切换模型，也不持久化 acknowledgement、model route 或 checkpoint state；模型选择不是验收证据。
 
-```sh
-npm install -D project-tiny-context-harness@latest
-npx --yes --package project-tiny-context-harness@latest ty-context init
-make validate-context
-```
+Long-Task Skill 采用渐进读取：主 `SKILL.md` 只保留目标、硬边界和阶段路由，Contract Authoring、Evidence Design 与 Authority Lifecycle 细节只在对应阶段读取一层 reference。这只是指令组织，不产生第二权威。
+
+Draft Outcome 只是 Authority Lock 前的 Outcome。Outcome 按可独立观察、判断和定向验证的结果拆分，使当前 Goal 能缩小 dependency-ready 工作集、定向验证、定位失败、恢复 finding 并精确失效旧局部结果。`depends_on` 只表示 acceptance readiness，Rolling Frontier 只是临时工作状态；Outcome 不是 Worker、scheduler task、queue 或并行单元。Outcome 拆分执行和诊断，不拆分完成权威，因此最终仍必须在当前最终快照运行一次完整 Final Gate。
 
-生成的核心结构类似：
+平台负责物理 Goal/会话生命周期。新会话通过 `resume` 恢复语义状态；Tiny Context 不会重建此前的物理 Turn。
+
+### CLI
 
 ```text
-AGENTS.md
-project_context/
-  context.toml
-  global.md
-  architecture.md
-  areas/main.md
-  areas/main/verification.md
+ty-context long-task init <workdir>
+ty-context long-task preflight <workdir>
+ty-context long-task compile <workdir>
+ty-context long-task compile <workdir> --revise
+ty-context long-task approve-authority-revision <workdir> --revision <sha>
+ty-context long-task explain <workdir>
+ty-context long-task verify <workdir> [--outcome <key>] [--check <key>]
+ty-context long-task status <workdir>
+ty-context long-task resume <workdir>
+ty-context long-task doctor <workdir>
+ty-context long-task final-gate <workdir>
+ty-context long-task stop-check <workdir> [--message <text>]
+ty-context long-task close <workdir>
+ty-context long-task abandon <workdir> [--force-corrupt-state]
 ```
 
-## 一个简单的使用方式
+- `init` 创建单文件 inline Outcome 的 Compact Contract 模板。
+- `preflight` 应用 Compact 默认值并一次输出 Source/REQ/CTRL/OBL/AC、Context、风险、路径/Binding、Runner/Input 与 Proof 诊断；它完全只读，不创建 Authority Lock、marker、cache、progress、Receipt、pending revision、状态锁，也不运行项目 Check。
+- `compile` 生成 Global 与 Outcome Result/Requirement/Control-field/Non-completing/Technical Claim，拒绝未覆盖 Claim，并让第一次正式成功 Compile 成为 Authority Lock。第一次结果附带 `execution_model_checkpoint.required: true`，后续 Compile 返回 `false`；该字段不进入 Authority state。
+- `verify` 在重查 active task/revision/compiled/worktree identity 后写 scoped Progress；targeted verify 始终只是修复证据。
+- `status` 输出 `unverified`、`progress_passing`、`progress_failing`、`progress_stale` 或 `blocked_external`，并报告 fresh `final_workflow_status` 与完整 `external_confirmations`。
+- `resume` 完全只读，恢复 task/contract identity、风险、相关 Context、Git 状态、ready Outcome、findings 和 next safe action。
+- `final-gate` 在完整 Check 后再次验证 active identity；并发 revision 不能产生 accepted。
+- `stop-check` 与 `close` 自己运行 Live Final Gate，并只用 accepted identity 做 CAS clear。`status: closed` 只表示机器 Authority 已清理，不表示完整外部交付完成。
+- `abandon --force-corrupt-state` 仅用于损坏/mismatch/legacy-unrecoverable 状态或遗留锁，只删除确定性 active state 与 `<workdir>/.ty-context/**`。
 
-在新 agent 会话里先发：
+### Delivery Contract
 
-```text
-Read AGENTS.md and project_context/** first. Summarize the project goal, non-goals, architecture boundaries, validation entry points and next safe action before proposing code changes.
-```
+`long-task-delivery-v2` 在同一个文件中保持 Product Authority、Technical Boundary Authority 与 Acceptance Authority。Compact YAML 只省略确定性默认值，规范化后的 Contract、Authority Hash 与 Compiled Identity 和完整展开形式一致。
+
+Contract 顶层包含：
+
+- `task`：完整目标、Source 路径、相关 Context 与 snapshot 模式；
+- `risk`：`auto | standard | strict` 与明确 risk facts；
+- `global`：非目标、owner boundary、技术约束、禁止路径/捷径和全局 Check；
+- `outcomes`：可独立判断并可定向验证的结果、依赖、REQ、产品/控件状态与位置、稳定技术义务和命名 AC。
+
+Runner 支持 `package_script`、`project_binary`、`node_oracle`、`playwright_test`。Proof surface 支持 `ui_browser`、`runtime_behavior`、`api_contract`、`data_state`、`security_boundary`、`population_coverage`、`implementation_structure`。
+
+### 一个 Contract 与 Source Claim
+
+用户选定的一次完整交付始终只有一个 Contract 和一个 Final Gate。Outcome 只按“可独立判断、可定向验证”的结果拆分；模型输出长度、YAML/文件长度、前后端层、模块数量、并行偏好或 Agent 容量都不是拆分依据。
 
-如果 agent 能快速说清楚项目目标、非目标、边界和验证入口，而不是重新扫描整个仓库猜测方向，这个 Harness 就发挥作用了。
+V2 强制至少一个真实 `source_path` 与一个 `source_claim`，且每个声明的 Source 文件至少包含一个 Material Item。Authoring 阶段必须在原始 Markdown 中仅插入不渲染的 `ty-source-item:start/end` 标记，不得改写 Item 原文。Marker key 与 Source Claim key 必须集合完全相等且全局唯一。
 
-## Benchmark 说明
+类型化 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`。
 
-不要把旧阶段式 Tiny Context 的 benchmark 数字当成当前 Minimal Context Harness 的性能证明。
+`context.toml` 中仅用于未来读取的 `triggers`、`read_when`、`read_policy`、default selection 与未选节点不再进入当前 delivery Authority；当前已选 area ownership、role/dependency 与 Context 内容仍受保护。最终 Git tree 变化后仍必须重新运行 Live Final Gate。
 
-当前公开卖点是产品设计和 smoke 证据：它能安装一个小的项目记忆面，并用 `validate-context` 检查恢复事实是否存在。真正的效率结论需要重新设计 fresh baseline 和 Minimal Context Harness 的对照实验。
+## 确定性风险分级
 
-## 反馈
+- **L0**：局部、可逆、可直接测试的任务走默认工作流。
+- **L1 standard**：多个可观察 Outcome 或需要跨会话恢复，且有可靠可执行验证。
+- **L2 strict**：使用同一套 Long-Task 和 Outcome 结构，但对公共 API/schema、持久数据、迁移、安全/权限边界、不可逆外部影响、全量 population，或可观察性弱的关键主路径增加更严格的 proof；不支持多仓库交付。
 
-现在最有价值的反馈不是“能不能多加流程”，而是：
+用户可以主动升级为 strict。显式 `standard` 低于计算出的最低级别会以 `risk_level_below_required` 失败。Strict 所需 negative、counterfactual、population、security、environment、rollback/recovery proof 由 Compiler 按风险强制。
 
-- 你的 agent 经常忘掉什么项目事实？
-- 哪些事实应该长期留在仓库里？
-- `project_context/**` 是否太多、太少或不够好读？
-- 新 chat 是否更快恢复了项目意图？
+## Evidence 与完成权威
+
+最终接受来自当前可执行证据，不来自 Agent 文本。Evidence Adapter 由 Runner 派生：只有 `playwright_test → playwright_json_v1` 可以证明 `ui_browser`，其余 Runner 均为 `structured_json_v2`，只能证明非浏览器 Surface。
+
+每个 Outcome 至少有一个非 Result 原子 Claim，且 `required_proof_surfaces` 必须 all-of 全覆盖。Claim-bearing Assertion 使用显式 Expected 比较；`truthy/falsy` 禁止，`exists` 仅允许证明 `implementation_structure` Obligation。
+
+Targeted verify、Progress、status、Receipt 与 compiled cache 都不是完成权威。Final Gate 要求 clean candidate commit，从 Source 重新 Compile，在同一 Git-tree snapshot 上运行全部 Global/Outcome Check，并在结束时再次校验 active identity。只有它可以生成 `machine_accepted` 或 `machine_accepted_external_pending`；后者仍必须明确列出外部确认项。
+
+## 开发与验证
+
+```powershell
+npm install
+npm run format:check
+npm run typecheck --workspace project-tiny-context-harness
+npm run build --workspace project-tiny-context-harness
+node --test --test-concurrency=1 tests/ty-context/source-plan-authoring-skill.test.mjs tests/ty-context/sync-init-doctor.test.mjs tests/ty-context/workflow-contract-routing.test.mjs tests/ty-context/long-task-model-choice-checkpoint.test.mjs
+npm run test:delivery-contract --workspace project-tiny-context-harness
+npm run test:long-task-workflow --workspace project-tiny-context-harness
+npm run test:long-task-performance --workspace project-tiny-context-harness
+npm test
+npm run smoke:quickstart
+npm run preview:pack
+npm run launch:check
+node packages/ty-context/dist/cli.js package check-source
+make validate-harness
+```
 
-可以在 GitHub issue 里反馈：
+模块化门禁是 `ty-context check-modularity`；例外必须包含 `owner`、`introduced_at`、`reason`、`tracking_issue` 和 `expiry_condition`。
 
-- [Adoption reports](https://github.com/Seven128/project-tiny-context-harness/issues/4)
-- [Demo starter issue](https://github.com/Seven128/project-tiny-context-harness/issues/5)
-- [Sample walkthrough starter issue](https://github.com/Seven128/project-tiny-context-harness/issues/6)
+## 诚实限制
 
-## 语言策略
+- Harness 不创建或恢复平台物理 Goal/会话。
+- 它不能证明用户从未遗漏未声明需求。
+- bounded Context keyword search 仍可能漏掉同义词或间接依赖，只能补充语义判断。
+- Harness 不能切换 host 选择的模型，只能在第一次 Authority Lock 后要求一次用户选择。
+- 核心长程执行不提供并行 mutation runtime。
+- 它不观测平台 token 或模型调用数。
+- Network policy 会约束传给 runner 的代理环境，但不是操作系统 sandbox。
+- 同用户/管理员文件篡改、系统级 Hook 绕过不在安全边界内。
+- Git/PR/CI、部署与人工产品确认仍由外部系统负责。
 
-本项目的默认 README、npm copy 和公开 launch 文案保持英文优先，方便 GitHub、Hacker News、Reddit、Product Hunt 和 curated lists 上的开发者快速判断项目价值。
+## License
 
-中文文档作为二级入口保留，用来服务中文用户和维护者，但不会替代英文主入口。
+MIT