agent-project-sdlc 0.1.25 → 0.1.26

package/README.md

@@ -19,12 +19,13 @@ npx sdlc-harness init --adopt
 
 | Capability | Entry Point | Description |
 |---|---|---|
-| Project initialization | `npx sdlc-harness init` | Creates `AGENTS.md`, `<harnessRoot>/state/**`, workflow skills, managed templates/policies, `.docs/**` and a Makefile include. |
-| Existing project adoption | `npx sdlc-harness init --adopt` | Adds Harness non-destructively to an existing repository. |
-| Configurable Harness root | `--harness-folder`, `package.json#sdlcHarness.harnessFolderName`, `sdlc-harness.config.json` | Supports Codex `.codex`, Claude `.claude`, Cursor `.cursor`, Cline `.cline`, Roo `.roo`, Gemini `.gemini` or a custom folder. |
+| Project initialization | `npx sdlc-harness init` | Creates `AGENTS.md`, `<harnessRoot>/state/**`, workflow skills, managed templates/policies, `.docs/**` and a Makefile include; fresh lifecycle starts at `REQUIREMENT_GATHERING`. |
+| Existing project adoption | `npx sdlc-harness init --adopt` | Adds Harness non-destructively to an existing repository; adopt lifecycle starts at `SPRINTING`. |
+| Configurable Harness root | `--harness-folder`, `package.json#sdlcHarness.harnessFolderName`, `sdlc-harness.config.json` | Supports Codex `.codex`, Claude `.claude`, Cursor `.cursor`, Cline `.cline`, Roo `.roo`, Gemini `.gemini` or a custom folder; root resolution prefers package.json, then config file, then `.agent`. |
 | Managed file sync | `npx sdlc-harness sync` | Materializes package canonical assets and safely updates package-managed guidance sections inside user-owned Markdown files while preserving project state, docs and local overrides. |
 | Upgrade | `npx sdlc-harness upgrade` | Runs migrations and sync for already-adopted projects, including legacy seed guidance migration. |
 | Diagnostics | `npx sdlc-harness doctor` | Reports Harness root, package version, schema version and key managed paths. |
+| Workflow self-inspection | `npx sdlc-harness inspect-workflow` | Read-only check for workflow weight, fact-source drift, handoff clarity and recovery safety; metrics are labeled `measured`, `inferred`, `self_reported` or `unavailable`. |
 | Validators | `npx sdlc-harness validate-*`, `make validate-current`, `make validate-harness` | Checks product, UI/UX, architecture design slicing, development, review, test, release, RFC, active plan shape, prompt language contract and generated overview freshness. |
 | Harness Python tools | `tools/*.py` | Package-managed local workflow tools, including `transition.py`, Python validators and overview generation helpers. |
 | Lifecycle workflow | `<harnessRoot>/state/lifecycle.yaml`, `<harnessRoot>/state/plan.yaml`, `.docs/**` | Tracks REQUIREMENT_GATHERING, UI_UX_DESIGNING, ARCHITECTING, SPRINTING, REVIEWING, TESTING, RELEASING and RFC_RECALIBRATION facts. |
@@ -87,12 +88,28 @@ The generic rule is that any workflow promoting a draft task into a formal `TASK
 
 Phase routing is expressed as a lightweight explicit directed graph in `<harnessRoot>/pjsdlc_managed/policies/phase_contracts.yaml`: `phases` stores stable phase contracts, while `transitions` stores legal edges and small runtime effects such as setting or clearing `suspended_phase`. This makes normal advance, pre-development return, TESTING bugfix return, RFC interrupt/resume and BLOCKED resume rules consumable by both the transition helper and validators. It is intentionally not a heavy graph engine: no history graph, traversal framework, node/edge classes or visualizer are introduced; the goal is to reduce missed rules and drift.
 
-Migration cost is low for projects that use managed assets: run `npx sdlc-harness upgrade` to sync the new `phase_contracts.yaml`, `tools/transition.py`, `pjsdlc_uiux_design`, `UI_UX_DESIGN_TEMPLATE.md` and `validate-uiux`, or run `npx sdlc-harness sync` if only managed files need refreshing. `lifecycle.yaml` and `plan.yaml` do not need manual migration; old `allowed_next_phases` values are regenerated from the graph on the next transition. Projects with custom phase policies should convert node-local `next` / `returns` to top-level `transitions`, and add `REQUIREMENT_GATHERING -> UI_UX_DESIGNING -> ARCHITECTING`, `ARCHITECTING -> UI_UX_DESIGNING`, and the `TESTING -> UI_UX_DESIGNING` / `ARCHITECTING` / `SPRINTING` bugfix return edges when they want the new routing. If the new `validate-harness` reports missing `transitions`, run `upgrade` or `sync` before validating again.
+Migration cost is low for projects that use managed assets: run `npx sdlc-harness upgrade` to sync the new `phase_contracts.yaml`, `tools/transition.py`, `pjsdlc_uiux_design`, `UI_UX_DESIGN_TEMPLATE.md`, `validate-uiux` and configured-root Python/Makefile gate fixes, or run `npx sdlc-harness sync` if only managed files need refreshing. `lifecycle.yaml` and `plan.yaml` do not need manual migration; old `allowed_next_phases` values are regenerated from the graph on the next transition, and the fresh/adopt initial phase split only affects new `init` runs. Projects with custom phase policies should convert node-local `next` / `returns` to top-level `transitions`, and add `REQUIREMENT_GATHERING -> UI_UX_DESIGNING -> ARCHITECTING`, `ARCHITECTING -> UI_UX_DESIGNING`, and the `TESTING -> UI_UX_DESIGNING` / `ARCHITECTING` / `SPRINTING` bugfix return edges when they want the new routing. If the new `validate-harness` reports missing `transitions`, run `upgrade` or `sync` before validating again.
 
 Before development starts, `ARCHITECTING` can return to `REQUIREMENT_GATHERING` for PRD edits or to `UI_UX_DESIGNING` for missing screen contracts, interaction states, responsive/a11y acceptance or `DESIGN.md`. The manager uses `python3 tools/transition.py --to REQUIREMENT_GATHERING` or `python3 tools/transition.py --to UI_UX_DESIGNING`, completes one stage task, runs that stage gate, then returns to the downstream phase. Requirement, acceptance, experience-contract or product-boundary changes after `SPRINTING` use RFC recalibration; `SPRINTING`, `REVIEWING`, `TESTING` and `RELEASING` can enter the controlled interrupt with `python3 tools/transition.py --to RFC_RECALIBRATION`, then return to `SPRINTING` after `validate-rfc`.
 
 When TESTING finds a bug, first record `Bugfix Route` in `.docs/07_test/TEST_REPORT.md`, then let the manager choose the lightweight return. `bugfix_uiux_replan` uses `python3 tools/transition.py --to UI_UX_DESIGNING` when PRD is correct but UX contract, screen contract, handoff matrix or `DESIGN.md` is wrong. `bugfix_replan` uses `python3 tools/transition.py --to ARCHITECTING` when the technical plan, interface contract, task breakdown, Development Self-Test Contract or Module Key Test Graph must change. `bugfix_implementation_gap` uses `python3 tools/transition.py --to SPRINTING` only when the technical plan is still correct and implementation deviated from it. Requirement, acceptance or product-boundary changes still use RFC recalibration.
 
+## Workflow Self-Inspection
+
+Use `npx sdlc-harness inspect-workflow` when a user agent needs to check whether a repository is running the Harness workflow as intended, especially whether the workflow has become too heavy. The command is read-only: it does not write reports, run heavyweight tests, upload telemetry or invent precise token numbers.
+
+Each metric includes a `data_source`: `measured` for local files, fields or validator results the script actually read; `inferred` for proxies derived from size, duplication, missing fields or long handoff docs; `self_reported` for values explicitly supplied by the user or agent; and `unavailable` for data the local environment cannot know, such as true model token telemetry when the client did not provide it.
+
+Default workflow-weight thresholds are intentionally simple. `plan.yaml` over 200 lines is `WARN` and over 500 lines is `BLOCKED`; more than one open task is `BLOCKED`; current task `allowed_paths` over 12 is `WARN` and over 25 is `BLOCKED`; current task document refs over 5 is `WARN` and over 10 is `BLOCKED`; `working_notes` over 8 is `BLOCKED`; Development Self-Test Report size is `WARN` / `BLOCKED` above 80 / 120 lines for ordinary tasks and 120 / 180 lines for high-risk runtime tasks.
+
+When the agent or client has real recent-cost data, pass it explicitly:
+
+```sh
+npx sdlc-harness inspect-workflow --recent-minutes 18 --recent-turns 7 --estimated-tokens 12000
+```
+
+Use `--prompt` to print a self-inspection prompt for qualitative checks such as whether the current entry, task, next step, hard constraints and Review/Testing handoff are clear. Use `--json` when CI or another agent needs a machine-readable `decision`, `metrics` and `findings` report. `BLOCKED` exits non-zero; `WARN` remains a successful diagnostic exit.
+
 `validate-uiux` requires at least one non-overview `.docs/02_experience/**` deliverable. UX slices must cite PRD / requirement IDs or explicitly declare `Applicability: not_applicable`; visual UI slices require root `DESIGN.md` and fail on `@google/design.md` linter errors. Warnings are reported by the linter but are not treated as default blockers.
 
 `validate-design` treats semantic slicing as a hard gate. Generated `overview.md` files do not count as deliverables, development draft tasks in `plan.draft.yaml` must reference existing tech plan slices through `docs.tech_plan`, UI/frontend draft tasks must reference existing UX slices through `docs.uiux` and root `DESIGN.md` through `docs.design_system`, multiple development draft tasks need distinct primary tech plan slices, and explicit AI provider/copilot, external-system, or compliance/permission/audit themes require dedicated architecture slices. Draft tasks with runnable boundaries must also include `self_test_contract`, backed by a `Development Self-Test Contract` section in the tech plan; the contract must include `module_key_test_path` from local start or invocation to all self-test scenarios completion, covering every runnable entry promised by the current task/module and its internal key paths. Complex or high-risk paths may set `graph_required: true` and provide `module_key_test_graph` to express entries, checkpoints, scenarios, exits and evidence refs as a lightweight DAG.
@@ -125,6 +142,7 @@ npx sdlc-harness init --adopt
 npx sdlc-harness sync
 npx sdlc-harness upgrade
 npx sdlc-harness doctor
+npx sdlc-harness inspect-workflow
 npx sdlc-harness validate-plan
 npx sdlc-harness validate-uiux
 npx sdlc-harness validate-design

package/assets/docs/README.md

@@ -24,7 +24,7 @@ npm install -D agent-project-sdlc
 npx sdlc-harness init
 ```
 
-`init` 会先询问目标 Agent。直接回车选择默认 `Codex`，并把 Harness 配置写到 `.codex`。其它内置选项会写入对应目录，例如 `Claude Code -> .claude`、`Cursor -> .cursor`、`Cline -> .cline`、`Roo Code -> .roo`、`Gemini CLI -> .gemini`。选择 `Other` 时才会继续询问自定义文件夹名，此时直接回车默认 `.agent`。
+`init` 会先询问目标 Agent。直接回车选择默认 `Codex`，并把 Harness 配置写到 `.codex`。其它内置选项会写入对应目录，例如 `Claude Code -> .claude`、`Cursor -> .cursor`、`Cline -> .cline`、`Roo Code -> .roo`、`Gemini CLI -> .gemini`。选择 `Other` 时才会继续询问自定义文件夹名，此时直接回车默认 `.agent`。新项目 fresh init 从 `REQUIREMENT_GATHERING` 开始，避免绕过 PRD / UI/UX / architecture；已有项目使用 `--adopt` 时从 `SPRINTING` 接入，方便先对齐既有代码和 Harness 事实源。
 
 如果已经确定目录，可以跳过交互：
 
@@ -54,12 +54,13 @@ npx sdlc-harness init --adopt
 
 | 能力 | 入口 | 说明 |
 |---|---|---|
-| 新项目初始化 | `npx sdlc-harness init` | 选择目标 Agent，生成 Harness 根目录、状态文件、workflow skills、模板、策略、`.docs/**` 和 Makefile include |
-| 已有项目接入 | `npx sdlc-harness init --adopt` | 非破坏性接入已有仓库，不覆盖业务代码和已有项目事实源 |
-| 可配置 Harness 根目录 | `--harness-folder`、`package.json#sdlcHarness.harnessFolderName`、`sdlc-harness.config.json` | 支持 `.codex`、`.claude`、`.cursor`、`.cline`、`.roo`、`.gemini` 或自定义目录 |
+| 新项目初始化 | `npx sdlc-harness init` | 选择目标 Agent，生成 Harness 根目录、状态文件、workflow skills、模板、策略、`.docs/**` 和 Makefile include；fresh lifecycle 从 `REQUIREMENT_GATHERING` 开始 |
+| 已有项目接入 | `npx sdlc-harness init --adopt` | 非破坏性接入已有仓库，不覆盖业务代码和已有项目事实源；adopt lifecycle 从 `SPRINTING` 开始 |
+| 可配置 Harness 根目录 | `--harness-folder`、`package.json#sdlcHarness.harnessFolderName`、`sdlc-harness.config.json` | 支持 `.codex`、`.claude`、`.cursor`、`.cline`、`.roo`、`.gemini` 或自定义目录；解析优先级为 package.json、config file、默认 `.agent` |
 | 同步 managed workflow 文件 | `npx sdlc-harness sync` | 从包内 canonical assets 物化 `AGENTS.md` managed block、workflow skills、templates、policies、Makefile 片段、GitHub workflow，并安全更新 user-owned Markdown guidance sections |
 | 升级已接入项目 | `npx sdlc-harness upgrade` | 执行迁移并自动 `sync`，保留 state、docs、业务代码和本地 override，同时迁移旧 seed guidance |
 | 接入诊断 | `npx sdlc-harness doctor` | 检查 harness root、版本、schema、关键文件和 managed paths |
+| 工作流自查 | `npx sdlc-harness inspect-workflow` | 只读检查 workflow weight、事实源漂移、交接清晰度和 recovery safety；每个指标标注 `measured` / `inferred` / `self_reported` / `unavailable` |
 | 阶段 gate | `npx sdlc-harness validate-*`、`make validate-current`、`make validate-harness` | 校验需求、UI/UX、架构设计、开发、Review、测试、发布、RFC、Harness 骨架、提示词语言契约和 overview freshness |
 | 生命周期工作流 | `lifecycle.yaml`、`plan.yaml`、`.docs/**` | 固定 REQUIREMENT_GATHERING、UI_UX_DESIGNING、ARCHITECTING、SPRINTING、REVIEWING、TESTING、RELEASING、RFC_RECALIBRATION 等阶段事实链 |
 | 阶段小任务管控 | `plan.yaml`、`make validate-plan` | 每个阶段的 Agent 主任务都应拆成足够小的 `TASK-*` open task，并用 `phase` 标明所属阶段 |
@@ -108,12 +109,43 @@ Agent 会读取 `<harnessRoot>/state/lifecycle.yaml` 和 `<harnessRoot>/state/pl
 
 阶段关系由 `<harnessRoot>/pjsdlc_managed/policies/phase_contracts.yaml` 中的轻量显式有向图表达：`phases` 保存稳定阶段 contract，`transitions` 保存合法流转边和少量效果，例如设置或清理 `suspended_phase`。这样做是为了让正常推进、开发前返回、TESTING bugfix return、RFC interrupt/resume 和 BLOCKED resume 都被 transition helper 与 validator 读取，避免规则埋在长文档或工具硬编码里。它不是重型图引擎，不保存历史、不做复杂遍历、不引入 node/edge class 或可视化；目标只是降低遗漏和漂移。
 
-迁移成本较低：对使用 managed assets 的项目，运行 `npx sdlc-harness upgrade` 即可同步新的 `phase_contracts.yaml`、`tools/transition.py`、`pjsdlc_uiux_design`、`UI_UX_DESIGN_TEMPLATE.md` 和 `validate-uiux`；也可以运行 `npx sdlc-harness sync` 只刷新 managed 文件。`lifecycle.yaml` 和 `plan.yaml` 不需要手动迁移，旧的 `allowed_next_phases` 会在下一次 `transition.py` 执行后按图重新生成。只有维护了自定义 phase policy 的项目需要把阶段内的 `next` / `returns` 转成 top-level `transitions`，并加入 `REQUIREMENT_GATHERING -> UI_UX_DESIGNING -> ARCHITECTING`、`ARCHITECTING -> UI_UX_DESIGNING`、`TESTING -> UI_UX_DESIGNING` / `ARCHITECTING` / `SPRINTING` return edges；如果升级前直接运行新版 `validate-harness` 看到缺少 `transitions`，先执行 `upgrade` / `sync`。
+迁移成本较低：对使用 managed assets 的项目，运行 `npx sdlc-harness upgrade` 即可同步新的 `phase_contracts.yaml`、`tools/transition.py`、`pjsdlc_uiux_design`、`UI_UX_DESIGN_TEMPLATE.md`、`validate-uiux` 和 configured-root Python/Makefile gate 修复；也可以运行 `npx sdlc-harness sync` 只刷新 managed 文件。`lifecycle.yaml` 和 `plan.yaml` 不需要手动迁移，旧的 `allowed_next_phases` 会在下一次 `transition.py` 执行后按图重新生成；fresh/adopt 初始阶段只影响新执行的 `init`，不会重写已有 state。只有维护了自定义 phase policy 的项目需要把阶段内的 `next` / `returns` 转成 top-level `transitions`，并加入 `REQUIREMENT_GATHERING -> UI_UX_DESIGNING -> ARCHITECTING`、`ARCHITECTING -> UI_UX_DESIGNING`、`TESTING -> UI_UX_DESIGNING` / `ARCHITECTING` / `SPRINTING` return edges；如果升级前直接运行新版 `validate-harness` 看到缺少 `transitions`，先执行 `upgrade` / `sync`。
 
 在尚未进入开发前，`ARCHITECTING` 可以回到 `REQUIREMENT_GATHERING` 修改 PRD，也可以回到 `UI_UX_DESIGNING` 补 screen contracts、interaction states、responsive/a11y acceptance 或 `DESIGN.md`：Manager 使用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 或 `python3 tools/transition.py --to UI_UX_DESIGNING` 切回对应工作流，完成 task 和 gate 后再回到后续阶段。进入 `SPRINTING` 后的需求、验收标准、体验契约或产品边界变化走 RFC workflow；`SPRINTING`、`REVIEWING`、`TESTING` 和 `RELEASING` 都可以通过 `python3 tools/transition.py --to RFC_RECALIBRATION` 进入受控 RFC 中断，RFC 完成后回到 `SPRINTING` 重新完成开发自测和 handoff。
 
 TESTING 阶段发现 bug 时，先在 `.docs/07_test/TEST_REPORT.md` 记录 `Bugfix Route`，再由 Manager 选择轻量 return：`bugfix_uiux_replan` 走 `python3 tools/transition.py --to UI_UX_DESIGNING`，用于 PRD 正确但 UX contract、screen contract、handoff matrix 或 `DESIGN.md` 错误；`bugfix_replan` 走 `python3 tools/transition.py --to ARCHITECTING`，用于技术方案、接口契约、任务拆分、Development Self-Test Contract 或 Module Key Test Graph 需要改；`bugfix_implementation_gap` 走 `python3 tools/transition.py --to SPRINTING`，只用于技术方案正确但实现偏离的修复。需求、验收标准或产品边界变化仍走 RFC。
 
+### 工作流自查
+
+当你想知道“这个项目的 Harness 用法是否符合预期、是不是变得太重”时，运行：
+
+```sh
+npx sdlc-harness inspect-workflow
+```
+
+该命令只读检查本地事实源，不写报告、不跑重型测试、不上传 telemetry。输出状态是 `PASS`、`WARN` 或 `BLOCKED`；`BLOCKED` 会返回非零退出码。每条 metric 都会标注数据来源：
+
+- `measured`：脚本真实读到的文件、字段、validator 结果，例如 `plan.yaml` 行数、open task 数量、`allowed_paths` 数量。
+- `inferred`：脚本只能从体量、重复、字段缺失或长文档现象推断，例如当前交接上下文是否可能过重。
+- `self_reported`：用户或 Agent 显式传入的最近执行耗时、turns 或估算 token。
+- `unavailable`：当前环境没有真实 telemetry，命令不会伪造精确 token 或真实模型耗时。
+
+工作流重量的默认阈值是：`plan.yaml` 超过 200 行 `WARN`、超过 500 行 `BLOCKED`；open task 超过 1 个 `BLOCKED`；当前 task `allowed_paths` 超过 12 个 `WARN`、超过 25 个 `BLOCKED`；当前 task 关联文档超过 5 个 `WARN`、超过 10 个 `BLOCKED`；`working_notes` 超过 8 条 `BLOCKED`；`Development Self-Test Report` 普通任务超过 80 行 `WARN`、超过 120 行 `BLOCKED`，high-risk 任务使用 120 / 180 阈值。
+
+如果 Agent 或客户端知道最近一次 workflow 处理的实际成本，可以显式传入：
+
+```sh
+npx sdlc-harness inspect-workflow --recent-minutes 18 --recent-turns 7 --estimated-tokens 12000
+```
+
+也可以让 Agent 用提示词自查：
+
+```sh
+npx sdlc-harness inspect-workflow --prompt
+```
+
+`--prompt` 会要求 Agent 区分真实可测数据、推断数据、自报数据和不可测数据，并检查入口、当前任务、下一步、hard constraint promotion、交接卡边界和 Review / Testing 可消费性。`--json` 可用于 CI 或自动化读取。
+
 `validate-design` 会把架构阶段的语义切片作为硬 gate：`overview.md` 不计入 deliverables，`plan.draft.yaml` 中每个开发 draft task 必须通过 `docs.tech_plan` 指向存在的 tech plan slice；多个开发 draft task 默认需要不同 primary tech plan slice。PRD、tech plan 或 draft task 明确出现 AI provider / copilot、外部系统边界、合规 / 权限 / 审计等横切主题时，也需要对应的专门 architecture slice。可运行边界类 draft task 还必须带 `self_test_contract`，并在 tech plan 中有 `Development Self-Test Contract`；合同必须记录 `module_key_test_path`，说明从本地启动或调用入口开始，到完成全部自测 scenario 的模块关键测试路径，并覆盖本 task / 本模块承诺的所有可运行入口和内部关键路径。复杂或 high-risk 路径可设置 `graph_required: true` 并提供 `module_key_test_graph`，把入口、checkpoint、scenario、出口和 evidence refs 表达成轻量 DAG。
 
 SPRINTING 的 Definition of Done 包含模块级可运行交付边界：技术方案或 task 承诺的 API、CLI、server route、service、agent、runtime、adapter、worker、provider、配置契约和 fixture/live 边界必须在开发阶段实现或明确 `BLOCKED`。runtime/app/provider/live 类 task 必须在 `plan.yaml` 声明 `evidence_level.required`、`target_runtime_environment` 和 `self_test_contract`；`self_test_contract.required_gates` 必须同步出现在 task `required_gates`，`self_test_contract.module_key_test_path` 必须描述从本地启动或调用入口开始，到完成全部自测 scenario 的模块关键测试路径，并覆盖本 task / 本模块承诺的所有可运行入口和内部关键路径。复杂 task 的 `module_key_test_graph` 是 handoff path 的 canonical detail：它是 DAG 而不是树，因为多个 scenario 可能共享 setup、分支后汇合到同一 observable exit；它不是重型测试执行图，不保存 trace、debug log、operator log、runbook 正文或证据正文。`deployed_runtime` 不能用 `unit`、`local_runtime`、`external_provider_live`、provider smoke、fake adapter 或 localhost smoke 单独关闭，`business_handoff_ready` 还必须有 Testing Handoff Contract。当前 task 的 implementation doc 还必须写入 `Development Evidence` 和 `Development Self-Test Report`，其中自测报告记录 `Report Status: PASS | BLOCKED | IN_PROGRESS | STALE`、contract source、Module Application Entry、scenario results、executed gates、Module Key Test Path、必要时的 Module Key Test Graph、Observable Exit、Current Blocker、Testing Handoff Readiness 和 Evidence Index Refs；只有 `Report Status: PASS` 且所有 scenario 为 `PASS` 才能关闭 development task。`Development Self-Test Report` 只证明模块入口、核心路径、出口和最小证据指针，不承担 debug log、operator log、runbook、evidence dump 或探索流水职责；fallback / diagnostic 最多一句总结，详细内容进入 `.docs/09_runbooks/**` evidence index / appendix 或 git history；主报告不得使用 `Actual Evidence` 正文字段，普通报告目标不超过 80 行，high-risk 报告目标不超过 120 行。`Module Key Test Path` 必须记录实际入口、内部关键路径、关键边界、观察点和可观测完成证据。provider smoke、fixture smoke、fake adapter 或 one-shot smoke 只能证明局部链路，不能单独证明 application readiness。REVIEWING 会把缺少入口/出口、初始化、配置契约、目标运行环境、证据等级或开发自测证据作为阻断项；TESTING 只调用 Review 已确认 `PASS` 的既有入口做输入输出验证，复杂路径按 Module Key Test Graph 消费，不能新增 product runtime、bootstrap、provider adapter、deploy 或 package runtime script。
@@ -219,6 +251,13 @@ npx sdlc-harness sync
 npx sdlc-harness upgrade
 ```
 
+自查工作流重量和交接清晰度：
+
+```sh
+npx sdlc-harness inspect-workflow
+npx sdlc-harness inspect-workflow --prompt
+```
+
 运行当前阶段 gate：
 
 ```sh

package/assets/templates/UI_UX_DESIGN_TEMPLATE.md

@@ -64,4 +64,4 @@
 
 ### Out of Scope
 
-- 
+- TBD

package/assets/tools/harness_utils.py

@@ -12,6 +12,8 @@ from typing import Any
 
 
 ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_HARNESS_ROOT = ".agent"
+HARNESS_JSON_CONFIG_PATH = "sdlc-harness.config.json"
 
 TASK_STATUSES = {
     "pending",
@@ -70,7 +72,67 @@ def repo_path(relative: str | Path) -> Path:
     return ROOT / relative
 
 
+def normalize_harness_folder_name(value: str) -> str:
+    normalized = value.strip().replace("\\", "/").rstrip("/")
+    if not normalized or normalized in {".", ".."}:
+        raise HarnessError("harnessFolderName must be a non-empty relative directory")
+    if Path(normalized).is_absolute() or ".." in normalized.split("/"):
+        raise HarnessError("harnessFolderName must not be absolute or contain '..'")
+    return normalized
+
+
+def folder_name_from_object(value: Any) -> str | None:
+    if not isinstance(value, dict):
+        return None
+    folder_name = value.get("harnessFolderName") or value.get("harnessFloderName")
+    if isinstance(folder_name, str) and folder_name.strip():
+        return folder_name
+    return None
+
+
+def read_json_config(relative: str) -> Any:
+    path = repo_path(relative)
+    if not path.exists():
+        return None
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def harness_root() -> str:
+    package_json = read_json_config("package.json")
+    package_config = package_json.get("sdlcHarness") if isinstance(package_json, dict) else None
+    package_value = folder_name_from_object(package_config)
+    if package_value:
+        return normalize_harness_folder_name(package_value)
+
+    explicit_config = read_json_config(HARNESS_JSON_CONFIG_PATH)
+    explicit_value = folder_name_from_object(explicit_config)
+    if explicit_value:
+        return normalize_harness_folder_name(explicit_value)
+
+    return DEFAULT_HARNESS_ROOT
+
+
+def harness_path(*segments: str) -> str:
+    return (Path(harness_root()).joinpath(*segments)).as_posix()
+
+
+def resolve_harness_relative(relative: str | Path) -> str:
+    value = str(relative).replace("\\", "/")
+    root = harness_root()
+    if value == "<harnessRoot>":
+        return root
+    if value.startswith("<harnessRoot>/"):
+        return f"{root}/{value.removeprefix('<harnessRoot>/')}"
+    if root != ".codex":
+        if value == ".codex":
+            return root
+        if value.startswith(".codex/"):
+            return f"{root}/{value.removeprefix('.codex/')}"
+    return value
+
+
 def read_text(relative: str | Path) -> str:
+    relative = resolve_harness_relative(relative)
     path = repo_path(relative)
     if not path.exists():
         raise HarnessError(f"Missing required file: {relative}")
@@ -78,6 +140,7 @@ def read_text(relative: str | Path) -> str:
 
 
 def load_yaml(relative: str | Path) -> Any:
+    relative = resolve_harness_relative(relative)
     path = repo_path(relative)
     if not path.exists():
         raise HarnessError(f"Missing required YAML file: {relative}")
@@ -114,6 +177,7 @@ def parse_yaml_text(text: str) -> Any:
 
 
 def dump_yaml(data: Any, relative: str | Path) -> None:
+    relative = resolve_harness_relative(relative)
     path = repo_path(relative)
     path.write_text(to_simple_yaml(data).rstrip() + "\n", encoding="utf-8")
 
@@ -330,7 +394,8 @@ def require(condition: Any, message: str) -> None:
 
 def require_paths(paths: list[str]) -> None:
     for relative in paths:
-        require(repo_path(relative).exists(), f"Missing required path: {relative}")
+        resolved = resolve_harness_relative(relative)
+        require(repo_path(resolved).exists(), f"Missing required path: {resolved}")
 
 
 def combined_text(paths: list[Path]) -> str:
@@ -844,13 +909,13 @@ def is_testing_runtime_boundary_change(path: str) -> bool:
 
 
 def load_lifecycle() -> dict[str, Any]:
-    data = load_yaml(".codex/state/lifecycle.yaml")
+    data = load_yaml(harness_path("state", "lifecycle.yaml"))
     require(isinstance(data, dict), "lifecycle.yaml must be a mapping")
     return data
 
 
 def load_phase_contract_data() -> dict[str, Any]:
-    data = load_yaml(".codex/pjsdlc_managed/policies/phase_contracts.yaml")
+    data = load_yaml(harness_path("pjsdlc_managed", "policies", "phase_contracts.yaml"))
     require(isinstance(data, dict) and isinstance(data.get("phases"), dict), "phase_contracts.yaml must contain phases")
     return data
 
@@ -1021,11 +1086,12 @@ def phase_transition_contract_errors(contract_data: dict[str, Any], require_tran
     return errors
 
 
-def load_plan(path: str = ".codex/state/plan.yaml") -> dict[str, Any]:
-    data = load_yaml(path)
-    require(isinstance(data, dict), f"{path} must be a mapping")
+def load_plan(path: str | None = None) -> dict[str, Any]:
+    plan_path = path or harness_path("state", "plan.yaml")
+    data = load_yaml(plan_path)
+    require(isinstance(data, dict), f"{resolve_harness_relative(plan_path)} must be a mapping")
     tasks = data.get("tasks", [])
-    require(isinstance(tasks, list), f"{path} must contain a tasks list")
+    require(isinstance(tasks, list), f"{resolve_harness_relative(plan_path)} must contain a tasks list")
     return data
 
 
@@ -1247,28 +1313,34 @@ def validate_parallel_worker_path_lock(data: dict[str, Any], worker: dict[str, A
             require(not glob_patterns_overlap(owned, forbidden), f"{prefix}.owned_paths must not overlap forbidden paths: {owned} vs {forbidden}")
 
 
-def glob_prefix(pattern: str) -> str:
-    normalized = pattern.replace("\\", "/").replace("<harnessRoot>", ".codex")
+def normalize_harness_pattern(pattern: str, root: str | None = None) -> str:
+    actual_root = root or harness_root()
+    return pattern.replace("\\", "/").replace("<harnessRoot>", actual_root)
+
+
+def glob_prefix(pattern: str, root: str | None = None) -> str:
+    normalized = normalize_harness_pattern(pattern, root)
     wildcard_positions = [pos for pos in (normalized.find("*"), normalized.find("["), normalized.find("?")) if pos >= 0]
     if wildcard_positions:
         normalized = normalized[: min(wildcard_positions)]
     return normalized.rstrip("/")
 
 
-def glob_patterns_overlap(left: str, right: str) -> bool:
-    left_clean = left.replace("\\", "/").replace("<harnessRoot>", ".codex")
-    right_clean = right.replace("\\", "/").replace("<harnessRoot>", ".codex")
+def glob_patterns_overlap(left: str, right: str, root: str | None = None) -> bool:
+    left_clean = normalize_harness_pattern(left, root)
+    right_clean = normalize_harness_pattern(right, root)
     if fnmatch.fnmatch(left_clean, right_clean) or fnmatch.fnmatch(right_clean, left_clean):
         return True
-    left_prefix = glob_prefix(left_clean)
-    right_prefix = glob_prefix(right_clean)
+    left_prefix = glob_prefix(left_clean, root)
+    right_prefix = glob_prefix(right_clean, root)
     if not left_prefix or not right_prefix:
         return left_prefix == right_prefix
     return left_prefix.startswith(right_prefix + "/") or right_prefix.startswith(left_prefix + "/") or left_prefix == right_prefix
 
 
-def expand_harness_root(patterns: list[str], root: str = ".codex") -> list[str]:
-    return [str(pattern).replace("<harnessRoot>", root) for pattern in patterns]
+def expand_harness_root(patterns: list[str], root: str | None = None) -> list[str]:
+    actual_root = root or harness_root()
+    return [str(pattern).replace("<harnessRoot>", actual_root) for pattern in patterns]
 
 
 def task_by_id(plan_data: dict[str, Any], task_id: str) -> dict[str, Any] | None:

package/assets/tools/transition.py

@@ -2,6 +2,7 @@
 from harness_utils import (
     dump_yaml,
     find_phase_transition,
+    harness_path,
     load_lifecycle,
     load_phase_contract_data,
     make_arg_parser,
@@ -51,7 +52,7 @@ def main() -> None:
         str(lifecycle.get("suspended_phase") or ""),
     )
 
-    dump_yaml(lifecycle, ".codex/state/lifecycle.yaml")
+    dump_yaml(lifecycle, harness_path("state", "lifecycle.yaml"))
     print(f"Transitioned {current} -> {target}")
     if args.reason:
         print(f"Note: {args.reason}")

package/assets/tools/validate_allowed_paths.py

@@ -18,7 +18,7 @@ def main() -> None:
     tasks = [task for task in data.get("tasks", []) if isinstance(task, dict)]
     open_tasks = [task for task in tasks if task.get("status") in OPEN_TASK_STATUSES]
 
-    policies = load_yaml(".codex/pjsdlc_managed/policies/allowed_paths.yaml")
+    policies = load_yaml("<harnessRoot>/pjsdlc_managed/policies/allowed_paths.yaml")
     lifecycle = load_lifecycle()
     current_phase = lifecycle.get("current_phase") or "SPRINTING"
     phase_policy = ((policies.get("phases") or {}).get(current_phase) or {})
@@ -29,7 +29,7 @@ def main() -> None:
         task = task_by_id(data, current_task_id) if current_task_id else None
         require(task, "current_task_id must point to the task being validated")
         require(task.get("status") in OPEN_TASK_STATUSES, "current_task_id must point to an open task for path validation")
-        allowed = list(task.get("allowed_paths") or []) + list(always_allow)
+        allowed = expand_harness_root(list(task.get("allowed_paths") or [])) + list(always_allow)
     else:
         print("Allowed paths skipped: no open task")
         return

package/assets/tools/validate_design.py

@@ -75,7 +75,7 @@ def main() -> None:
 
 
 def validate_draft_task_tech_plan_refs(tech_plan_docs: list, experience_docs: list) -> list[dict]:
-    draft = load_plan(".codex/state/plan.draft.yaml")
+    draft = load_plan("<harnessRoot>/state/plan.draft.yaml")
     require("current_phase" not in draft, "plan.draft.yaml must not define current_phase; lifecycle.yaml is the single source for current_phase")
     require("current_task_id" not in draft, "plan.draft.yaml must not define current_task_id because drafts are not active task state")
     tasks = draft.get("tasks", [])

package/assets/tools/validate_dev_state.py

@@ -3,7 +3,7 @@ from harness_utils import load_plan, require, run_main
 
 
 def main() -> None:
-    draft = load_plan(".codex/state/plan.draft.yaml")
+    draft = load_plan("<harnessRoot>/state/plan.draft.yaml")
     require("current_phase" not in draft, "plan.draft.yaml must not define current_phase; lifecycle.yaml is the single source for current_phase")
     require("current_task_id" not in draft, "plan.draft.yaml must not define current_task_id because drafts are not active task state")
     tasks = [task for task in draft.get("tasks", []) if isinstance(task, dict)]

package/assets/tools/validate_harness.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 from harness_utils import (
+    harness_path,
     load_lifecycle,
     load_phase_contract_data,
     load_phase_contracts,
@@ -13,19 +14,20 @@ from harness_utils import (
 
 
 def main() -> None:
+    root = harness_path()
     required_files = [
         "AGENTS.md",
         "Makefile",
         ".docs/INDEX.md",
-        ".codex/state/lifecycle.yaml",
-        ".codex/state/plan.yaml",
-        ".codex/state/plan.draft.yaml",
-        ".codex/state/memory.md",
-        ".codex/pjsdlc_managed/templates/PLAN_TEMPLATE.yaml",
-        ".codex/pjsdlc_managed/policies/phase_contracts.yaml",
-        ".codex/pjsdlc_managed/policies/gates.yaml",
-        ".codex/pjsdlc_managed/policies/allowed_paths.yaml",
-        ".codex/pjsdlc_managed/policies/risk_matrix.yaml",
+        harness_path("state", "lifecycle.yaml"),
+        harness_path("state", "plan.yaml"),
+        harness_path("state", "plan.draft.yaml"),
+        harness_path("state", "memory.md"),
+        harness_path("pjsdlc_managed", "templates", "PLAN_TEMPLATE.yaml"),
+        harness_path("pjsdlc_managed", "policies", "phase_contracts.yaml"),
+        harness_path("pjsdlc_managed", "policies", "gates.yaml"),
+        harness_path("pjsdlc_managed", "policies", "allowed_paths.yaml"),
+        harness_path("pjsdlc_managed", "policies", "risk_matrix.yaml"),
         "tools/build_doc_overviews.py",
         "tools/validate_plan.py",
     ]
@@ -42,7 +44,7 @@ def main() -> None:
         ".docs/08_release",
         ".docs/09_runbooks",
         ".docs/rfc",
-        ".codex/skills",
+        harness_path("skills"),
         "tools",
     ]
     require_paths(required_files + required_dirs)
@@ -50,9 +52,9 @@ def main() -> None:
     lifecycle = load_lifecycle()
     phase_contract_data = load_phase_contract_data()
     phases = load_phase_contracts()
-    load_yaml(".codex/pjsdlc_managed/policies/gates.yaml")
-    load_yaml(".codex/pjsdlc_managed/policies/allowed_paths.yaml")
-    load_yaml(".codex/pjsdlc_managed/policies/risk_matrix.yaml")
+    load_yaml(harness_path("pjsdlc_managed", "policies", "gates.yaml"))
+    load_yaml(harness_path("pjsdlc_managed", "policies", "allowed_paths.yaml"))
+    load_yaml(harness_path("pjsdlc_managed", "policies", "risk_matrix.yaml"))
 
     current_phase = lifecycle.get("current_phase")
     require(current_phase in phases, f"Lifecycle current_phase is not declared: {current_phase}")
@@ -62,7 +64,7 @@ def main() -> None:
     for phase_name, contract in phases.items():
         skill = contract.get("skill")
         require(skill, f"{phase_name} missing skill")
-        skill_file = repo_path(f".codex/skills/{skill}/SKILL.md")
+        skill_file = repo_path(f"{root}/skills/{skill}/SKILL.md")
         require(skill_file.exists(), f"Missing skill file for {phase_name}: {skill_file.relative_to(repo_path('.'))}")
         require("inputs" in contract, f"{phase_name} missing inputs")
         require("outputs" in contract, f"{phase_name} missing outputs")

package/assets/tools/validate_plan_draft.py

@@ -3,7 +3,7 @@ from harness_utils import load_plan, require, run_main, validate_task_shape
 
 
 def main() -> None:
-    data = load_plan(".codex/state/plan.draft.yaml")
+    data = load_plan("<harnessRoot>/state/plan.draft.yaml")
     require("current_phase" not in data, "plan.draft.yaml must not define current_phase; lifecycle.yaml is the single source for current_phase")
     require("current_task_id" not in data, "plan.draft.yaml must not define current_task_id because drafts are not active task state")
     tasks = data.get("tasks", [])

package/assets/tools/validate_prompt_language.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 
 from pathlib import Path
 
-from harness_utils import ROOT, HarnessError, load_yaml, require, run_main
+from harness_utils import ROOT, HarnessError, harness_path, load_yaml, require, run_main
 
 
 SKILL_REQUIRED_SECTIONS = ["## 目的", "## 角色提示词", "## 输入", "## 规则", "## 完成检查"]
@@ -45,14 +45,6 @@ MACHINE_IDENTIFIERS = [
     "pending_revision",
 ]
 
-REQUIRED_AGENTS_TERMS = [
-    "Skill Language Contract",
-    "中文解释 + 英文精确标识符",
-    ".codex/state/lifecycle.yaml",
-    ".codex/state/plan.yaml",
-    "make validate-current",
-]
-
 YAML_KEYWORDS = {
     "lifecycle": [
         "project_name",
@@ -78,15 +70,23 @@ def text(path: Path) -> str:
 
 def validate_agents() -> None:
     content = text(ROOT / "AGENTS.md")
-    for term in REQUIRED_AGENTS_TERMS:
+    required_agents_terms = [
+        "Skill Language Contract",
+        "中文解释 + 英文精确标识符",
+        harness_path("state", "lifecycle.yaml"),
+        harness_path("state", "plan.yaml"),
+        "make validate-current",
+    ]
+    for term in required_agents_terms:
         require(term in content, f"AGENTS.md missing skill language contract term: {term}")
     for identifier in MACHINE_IDENTIFIERS:
         require(identifier in content, f"AGENTS.md should preserve machine identifier: {identifier}")
 
 
 def validate_skills() -> None:
-    skill_files = sorted((ROOT / ".codex/skills").glob("*/SKILL.md"))
-    require(skill_files, "No workflow skill files found under .codex/skills/")
+    skill_root = ROOT / harness_path("skills")
+    skill_files = sorted(skill_root.glob("*/SKILL.md"))
+    require(skill_files, f"No workflow skill files found under {skill_root.relative_to(ROOT)}/")
 
     for path in skill_files:
         content = text(path)
@@ -101,8 +101,8 @@ def validate_skills() -> None:
 
 
 def validate_skill_template() -> None:
-    path = ROOT / ".codex/pjsdlc_managed/templates/SKILL_TEMPLATE.md"
-    require(path.exists(), "Missing .codex/pjsdlc_managed/templates/SKILL_TEMPLATE.md")
+    path = ROOT / harness_path("pjsdlc_managed", "templates", "SKILL_TEMPLATE.md")
+    require(path.exists(), f"Missing {path.relative_to(ROOT)}")
     content = text(path)
     for section in SKILL_REQUIRED_SECTIONS:
         require(section in content, f"SKILL_TEMPLATE.md missing Chinese section: {section}")
@@ -111,9 +111,9 @@ def validate_skill_template() -> None:
 
 
 def validate_yaml_keys() -> None:
-    lifecycle = load_yaml(".codex/state/lifecycle.yaml")
-    tasks = load_yaml(".codex/state/plan.yaml")
-    phase_contracts = load_yaml(".codex/pjsdlc_managed/policies/phase_contracts.yaml")
+    lifecycle = load_yaml(harness_path("state", "lifecycle.yaml"))
+    tasks = load_yaml(harness_path("state", "plan.yaml"))
+    phase_contracts = load_yaml(harness_path("pjsdlc_managed", "policies", "phase_contracts.yaml"))
 
     for key in YAML_KEYWORDS["lifecycle"]:
         require(key in lifecycle, f"lifecycle.yaml key was removed or translated: {key}")

package/dist/commands/index.js

@@ -1,4 +1,5 @@
 import { doctor } from "./doctor.js";
+import { inspectWorkflow } from "./inspect-workflow.js";
 import { init } from "./init.js";
 import { packageSource } from "./package-source.js";
 import { sync } from "./sync.js";
@@ -10,6 +11,7 @@ export const commands = {
     sync,
     upgrade,
     doctor,
+    "inspect-workflow": inspectWorkflow,
     validate,
     "validate-harness": (args) => validate(["validate-harness", ...args]),
     "validate-current": (args) => validate(["validate-current", ...args]),
@@ -31,6 +33,7 @@ export function help() {
   sync                 Materialize canonical assets into the workspace
   upgrade              Run migrations and then sync
   doctor               Diagnose project configuration and drift
+  inspect-workflow     Lightly inspect workflow weight, fact-source drift, and handoff clarity
   validate <gate>      Run a Harness validation gate
   validate-*           Run a named gate directly, including validate-plan/uiux/design/dev/review/test/release/rfc
   package <subcommand> Maintain package canonical source`);

package/dist/commands/inspect-workflow.d.ts

@@ -0,0 +1 @@
+export declare function inspectWorkflow(args: string[]): Promise<void>;

package/dist/commands/inspect-workflow.js

@@ -0,0 +1,71 @@
+import { renderWorkflowInspection, renderWorkflowInspectionPrompt, runWorkflowInspection } from "../lib/workflow-inspector.js";
+export async function inspectWorkflow(args) {
+    const options = {};
+    let json = false;
+    let prompt = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--json") {
+            json = true;
+        }
+        else if (arg === "--prompt") {
+            prompt = true;
+        }
+        else if (arg === "--recent-minutes") {
+            options.recentMinutes = parsePositiveNumber(requireValue(args, ++index, arg), arg);
+        }
+        else if (arg === "--recent-turns") {
+            options.recentTurns = parsePositiveNumber(requireValue(args, ++index, arg), arg);
+        }
+        else if (arg === "--estimated-tokens") {
+            options.estimatedTokens = parsePositiveNumber(requireValue(args, ++index, arg), arg);
+        }
+        else if (arg === "--help" || arg === "-h") {
+            printHelp();
+            return;
+        }
+        else {
+            throw new Error(`unknown inspect-workflow argument: ${arg}`);
+        }
+    }
+    const report = await runWorkflowInspection(process.cwd(), options);
+    if (json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        process.stdout.write(renderWorkflowInspection(report));
+        if (prompt) {
+            console.log("");
+            console.log(renderWorkflowInspectionPrompt(report));
+        }
+    }
+    if (report.decision === "BLOCKED") {
+        process.exitCode = 1;
+    }
+}
+function printHelp() {
+    console.log(`sdlc-harness inspect-workflow
+
+Lightly inspect whether a user repository is running the Harness workflow as intended.
+
+Options:
+  --json                     Emit a machine-readable report
+  --prompt                   Print an Agent self-inspection prompt after the measured report
+  --recent-minutes <n>       Self-reported recent workflow orientation time
+  --recent-turns <n>         Self-reported recent workflow conversation turns
+  --estimated-tokens <n>     Self-reported recent workflow token estimate`);
+}
+function requireValue(args, index, flag) {
+    const value = args[index];
+    if (!value || value.startsWith("--")) {
+        throw new Error(`${flag} requires a value`);
+    }
+    return value;
+}
+function parsePositiveNumber(value, flag) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`${flag} must be a non-negative number`);
+    }
+    return parsed;
+}

package/dist/lib/harness-root.js

@@ -2,17 +2,17 @@ import path from "node:path";
 import { DEFAULT_HARNESS_ROOT, HARNESS_JSON_CONFIG_PATH } from "./paths.js";
 import { pathExists, readText } from "./fs.js";
 export async function readHarnessRootConfig(projectRoot) {
-    const explicitConfig = await readJsonConfig(path.join(projectRoot, HARNESS_JSON_CONFIG_PATH));
-    const explicitValue = folderNameFromObject(explicitConfig);
-    if (explicitValue) {
-        return { harnessFolderName: normalizeHarnessFolderName(explicitValue), source: HARNESS_JSON_CONFIG_PATH };
-    }
     const packageJson = await readJsonConfig(path.join(projectRoot, "package.json"));
     const packageConfig = packageJson && typeof packageJson === "object" ? packageJson.sdlcHarness : undefined;
     const packageValue = folderNameFromObject(packageConfig);
     if (packageValue) {
         return { harnessFolderName: normalizeHarnessFolderName(packageValue), source: "package.json#sdlcHarness" };
     }
+    const explicitConfig = await readJsonConfig(path.join(projectRoot, HARNESS_JSON_CONFIG_PATH));
+    const explicitValue = folderNameFromObject(explicitConfig);
+    if (explicitValue) {
+        return { harnessFolderName: normalizeHarnessFolderName(explicitValue), source: HARNESS_JSON_CONFIG_PATH };
+    }
     return { harnessFolderName: DEFAULT_HARNESS_ROOT, source: "default" };
 }
 export async function harnessRoot(projectRoot) {

package/dist/lib/init.js

@@ -32,7 +32,7 @@ export async function runInit(projectRoot, options) {
     else {
         report.push(`kept existing ${configPath}`);
     }
-    await createProjectState(projectRoot, root, report);
+    await createProjectState(projectRoot, root, options.adopt, report);
     await createDocs(projectRoot, report);
     const syncReport = await runSync(projectRoot);
     report.push(`sync changed=${syncReport.changed.length} skipped=${syncReport.skipped.length} blocked=${syncReport.blocked.length}`);
@@ -48,13 +48,16 @@ async function projectHasExistingFiles(projectRoot) {
     }
     return false;
 }
-async function createProjectState(projectRoot, root, report) {
+async function createProjectState(projectRoot, root, adopt, report) {
     const stateRoot = path.join(projectRoot, root, "state");
     await ensureDir(stateRoot);
+    const lifecycle = adopt
+        ? `project_name: "Project"\nversion: "v0.1"\ncurrent_phase: "SPRINTING"\nactive_role: "developer"\nactive_skill: "pjsdlc_dev_sprint"\ncurrent_milestone: "MVP"\nblocked_reason: ""\nsuspended_phase: ""\nallowed_next_phases:\n  - "REVIEWING"\n  - "RFC_RECALIBRATION"\n  - "BLOCKED"\n`
+        : `project_name: "Project"\nversion: "v0.1"\ncurrent_phase: "REQUIREMENT_GATHERING"\nactive_role: "product_manager"\nactive_skill: "pjsdlc_pm_prd"\ncurrent_milestone: "MVP"\nblocked_reason: ""\nsuspended_phase: ""\nallowed_next_phases:\n  - "UI_UX_DESIGNING"\n  - "BLOCKED"\n`;
     const files = [
         [
             harnessPath(root, "state", "lifecycle.yaml"),
-            `project_name: "Project"\nversion: "v0.1"\ncurrent_phase: "SPRINTING"\nactive_role: "developer"\nactive_skill: "pjsdlc_dev_sprint"\ncurrent_milestone: "MVP"\nblocked_reason: ""\nsuspended_phase: ""\nallowed_next_phases:\n  - "REVIEWING"\n  - "RFC_RECALIBRATION"\n  - "BLOCKED"\n`
+            lifecycle
         ],
         [harnessPath(root, "state", "plan.yaml"), `current_task_id: ""\nnext_task_sequence: 1\ntasks: []\n`],
         [harnessPath(root, "state", "plan.draft.yaml"), `next_task_sequence: 1\ntasks: []\n`],

package/dist/lib/validators.js

@@ -1056,7 +1056,7 @@ async function validatePlanState(projectRoot, allowOpen) {
     if ("current_phase" in tasksData) {
         errors.push("plan.yaml must not define current_phase; lifecycle.yaml is the single source for current_phase");
     }
-    validateParallelExecutionContract(tasksData, currentPhase, errors);
+    validateParallelExecutionContract(tasksData, currentPhase, errors, root);
     const tasks = Array.isArray(tasksData.tasks) ? tasksData.tasks : [];
     const nextTaskSequence = tasksData.next_task_sequence;
     if (!Number.isInteger(nextTaskSequence) || Number(nextTaskSequence) <= 0) {
@@ -1606,7 +1606,7 @@ async function validateSelfTestContractTechPlanBinding(projectRoot, task, normal
     }
     return errors;
 }
-function validateParallelExecutionContract(plan, currentPhase, errors) {
+function validateParallelExecutionContract(plan, currentPhase, errors, root) {
     const contract = plan.parallel_execution;
     if (contract === undefined || contract === null)
         return;
@@ -1691,8 +1691,8 @@ function validateParallelExecutionContract(plan, currentPhase, errors) {
                 if (!Array.isArray(worker.owned_paths) || worker.owned_paths.length === 0) {
                     errors.push(`${prefix}.owned_paths must not be empty when writes_repo is true`);
                 }
-                validateParallelWorkerPathLock(plan, worker, index, errors);
-                for (const owned of stringArray(worker.owned_paths).map(normalizeParallelPattern)) {
+                validateParallelWorkerPathLock(plan, worker, index, errors, root);
+                for (const owned of stringArray(worker.owned_paths).map((pattern) => normalizeParallelPattern(pattern, root))) {
                     writeOwnedPaths.push({ index, path: owned });
                 }
             }
@@ -1701,7 +1701,7 @@ function validateParallelExecutionContract(plan, currentPhase, errors) {
             for (let right = left + 1; right < writeOwnedPaths.length; right += 1) {
                 const leftOwned = writeOwnedPaths[left];
                 const rightOwned = writeOwnedPaths[right];
-                if (globPatternsOverlap(leftOwned.path, rightOwned.path)) {
+                if (globPatternsOverlap(leftOwned.path, rightOwned.path, root)) {
                     errors.push(`parallel_execution write worker owned_paths must not overlap: workers[${leftOwned.index}] ${leftOwned.path} vs workers[${rightOwned.index}] ${rightOwned.path}`);
                 }
             }
@@ -1734,20 +1734,20 @@ function parallelRuntimeProvider(contract, errors) {
     }
     return String(runtime.provider ?? "");
 }
-function validateParallelWorkerPathLock(plan, worker, index, errors) {
+function validateParallelWorkerPathLock(plan, worker, index, errors, root) {
     const currentTask = currentPlanTask(plan);
     if (!currentTask)
         return;
-    const taskAllowed = stringArray(currentTask.allowed_paths).map(normalizeParallelPattern);
-    const workerOwned = stringArray(worker.owned_paths).map(normalizeParallelPattern);
-    const workerForbidden = stringArray(worker.forbidden_paths).map(normalizeParallelPattern);
-    const protectedPatterns = PARALLEL_PROTECTED_WRITE_PATTERNS.map(normalizeParallelPattern);
+    const taskAllowed = stringArray(currentTask.allowed_paths).map((pattern) => normalizeParallelPattern(pattern, root));
+    const workerOwned = stringArray(worker.owned_paths).map((pattern) => normalizeParallelPattern(pattern, root));
+    const workerForbidden = stringArray(worker.forbidden_paths).map((pattern) => normalizeParallelPattern(pattern, root));
+    const protectedPatterns = PARALLEL_PROTECTED_WRITE_PATTERNS.map((pattern) => normalizeParallelPattern(pattern, root));
     for (const owned of workerOwned) {
         if (!matchesAny(owned, taskAllowed)) {
             errors.push(`parallel_execution.workers[${index}].owned_paths must be within current task allowed_paths: ${owned}`);
         }
         for (const forbidden of [...workerForbidden, ...protectedPatterns]) {
-            if (globPatternsOverlap(owned, forbidden)) {
+            if (globPatternsOverlap(owned, forbidden, root)) {
                 errors.push(`parallel_execution.workers[${index}].owned_paths must not overlap forbidden paths: ${owned} vs ${forbidden}`);
             }
         }
@@ -1761,22 +1761,22 @@ function currentPlanTask(plan) {
 function stringArray(value) {
     return Array.isArray(value) ? value.map((item) => String(item)) : [];
 }
-function normalizeParallelPattern(pattern) {
-    return pattern.replace(/\\/g, "/").replaceAll("<harnessRoot>", ".codex");
+function normalizeParallelPattern(pattern, root) {
+    return pattern.replace(/\\/g, "/").replaceAll("<harnessRoot>", root);
 }
-function globPrefix(pattern) {
-    const normalized = normalizeParallelPattern(pattern);
+function globPrefix(pattern, root) {
+    const normalized = normalizeParallelPattern(pattern, root);
     const positions = ["*", "[", "?"].map((token) => normalized.indexOf(token)).filter((index) => index >= 0);
     const prefix = positions.length > 0 ? normalized.slice(0, Math.min(...positions)) : normalized;
     return prefix.replace(/\/+$/, "");
 }
-function globPatternsOverlap(left, right) {
-    const leftClean = normalizeParallelPattern(left);
-    const rightClean = normalizeParallelPattern(right);
+function globPatternsOverlap(left, right, root) {
+    const leftClean = normalizeParallelPattern(left, root);
+    const rightClean = normalizeParallelPattern(right, root);
     if (matchesGlob(leftClean, rightClean) || matchesGlob(rightClean, leftClean))
         return true;
-    const leftPrefix = globPrefix(leftClean);
-    const rightPrefix = globPrefix(rightClean);
+    const leftPrefix = globPrefix(leftClean, root);
+    const rightPrefix = globPrefix(rightClean, root);
     if (!leftPrefix || !rightPrefix)
         return leftPrefix === rightPrefix;
     return leftPrefix === rightPrefix || leftPrefix.startsWith(`${rightPrefix}/`) || rightPrefix.startsWith(`${leftPrefix}/`);
@@ -1784,6 +1784,7 @@ function globPatternsOverlap(left, right) {
 async function validateChangedPaths(projectRoot, plan, allowOpen) {
     if (!allowOpen)
         return [];
+    const root = await harnessRoot(projectRoot);
     const currentTaskId = String(plan.current_task_id ?? "");
     if (!currentTaskId)
         return [];
@@ -1793,7 +1794,7 @@ async function validateChangedPaths(projectRoot, plan, allowOpen) {
         return [`current_task_id does not match a task: ${currentTaskId}`];
     if (!Array.isArray(task.allowed_paths))
         return [`${currentTaskId} must define allowed_paths`];
-    const patterns = task.allowed_paths.map((pattern) => String(pattern).replace("<harnessRoot>", ".codex"));
+    const patterns = task.allowed_paths.map((pattern) => String(pattern).replace("<harnessRoot>", root));
     const changed = await changedFiles(projectRoot);
     const blocked = changed.filter((file) => !matchesAny(file, patterns));
     return blocked.length > 0 ? [`Changed files outside current task allowed_paths: ${blocked.join(", ")}`] : [];

package/dist/lib/workflow-inspector.d.ts

@@ -0,0 +1,35 @@
+export type InspectionDecision = "PASS" | "WARN" | "BLOCKED";
+export type InspectionDataSource = "measured" | "inferred" | "self_reported" | "unavailable";
+export interface WorkflowInspectionOptions {
+    recentMinutes?: number;
+    recentTurns?: number;
+    estimatedTokens?: number;
+}
+export interface WorkflowInspectionMetric {
+    id: string;
+    label: string;
+    value: string | number | boolean | null;
+    level: InspectionDecision;
+    data_source: InspectionDataSource;
+    details: string;
+}
+export interface WorkflowInspectionFinding {
+    severity: InspectionDecision;
+    code: string;
+    message: string;
+    recommendation: string;
+    data_source: InspectionDataSource;
+}
+export interface WorkflowInspectionReport {
+    decision: InspectionDecision;
+    harness_root: string;
+    harness_root_source: string;
+    current_phase: string;
+    current_task_id: string;
+    inspected_at: string;
+    metrics: WorkflowInspectionMetric[];
+    findings: WorkflowInspectionFinding[];
+}
+export declare function runWorkflowInspection(projectRoot: string, options?: WorkflowInspectionOptions): Promise<WorkflowInspectionReport>;
+export declare function renderWorkflowInspection(report: WorkflowInspectionReport): string;
+export declare function renderWorkflowInspectionPrompt(report: WorkflowInspectionReport): string;

package/dist/lib/workflow-inspector.js

@@ -0,0 +1,340 @@
+import path from "node:path";
+import { harnessPath, readHarnessRootConfig } from "./harness-root.js";
+import { pathExists, readText } from "./fs.js";
+import { parseYaml } from "./yaml.js";
+import { runValidator } from "./validators.js";
+const OPEN_TASK_STATUSES = new Set(["pending", "in_progress", "blocked", "pending_revision"]);
+const HIGH_RISK_EVIDENCE_LEVELS = new Set(["external_provider_live", "deployed_runtime", "business_handoff_ready"]);
+const HIGH_RISK_TARGETS = new Set(["cloud_vm", "managed_service", "browser", "worker"]);
+export async function runWorkflowInspection(projectRoot, options = {}) {
+    const rootConfig = await readHarnessRootConfig(projectRoot);
+    const root = rootConfig.harnessFolderName;
+    const inspectedAt = new Date().toISOString();
+    const metrics = [];
+    const findings = [];
+    const lifecyclePath = path.join(projectRoot, harnessPath(root, "state", "lifecycle.yaml"));
+    const planPath = path.join(projectRoot, harnessPath(root, "state", "plan.yaml"));
+    const lifecycle = await readYamlObject(lifecyclePath);
+    const plan = await readYamlObject(planPath);
+    const currentPhase = String(lifecycle?.current_phase ?? "");
+    const currentTaskId = String(plan?.current_task_id ?? "");
+    const tasks = arrayOfRecords(plan?.tasks);
+    const openTasks = tasks.filter((task) => OPEN_TASK_STATUSES.has(String(task.status ?? "")));
+    const currentTask = currentTaskId ? tasks.find((task) => String(task.id ?? "") === currentTaskId) : undefined;
+    const inferredTask = currentTask ?? (openTasks.length === 1 ? openTasks[0] : undefined);
+    const planText = await readIfExists(planPath);
+    addMetric(metrics, findings, "workflow_weight.plan_lines", "plan.yaml line count", planText ? countLines(planText) : null, levelByThreshold(planText ? countLines(planText) : 0, 200, 500), "measured", "Active plan should stay short enough for an Agent to recover current work without reading historical execution flow.", "Keep only current/future task contracts in plan.yaml; move completed history to implementation docs, git or external release records.");
+    addMetric(metrics, findings, "workflow_weight.open_tasks", "open task count", openTasks.length, openTasks.length <= 1 ? "PASS" : "BLOCKED", "measured", "The Harness expects one active stage task at a time; multiple open tasks make recovery and allowed_paths ambiguous.", "Split sequentially or choose one current task, then remove or defer the other open task contracts.");
+    const docRefs = inferredTask ? collectTaskDocRefs(inferredTask) : [];
+    addMetric(metrics, findings, "workflow_weight.current_task_doc_refs", "current task document refs", inferredTask ? docRefs.length : null, levelByThreshold(docRefs.length, 5, 10), inferredTask ? "measured" : "unavailable", inferredTask
+        ? "Too many task-scoped docs usually means the Agent must hydrate too much context before acting."
+        : "No current/open task is selected, so task-scoped document weight is not measurable.", "Narrow the current task result_docs / implementation_doc / docs refs to the smallest handoff surface.");
+    const allowedPaths = inferredTask ? asStringList(inferredTask.allowed_paths) : [];
+    addMetric(metrics, findings, "workflow_weight.allowed_paths", "current task allowed_paths", inferredTask ? allowedPaths.length : null, levelByThreshold(allowedPaths.length, 12, 25), inferredTask ? "measured" : "unavailable", inferredTask
+        ? "Wide allowed_paths increase blast radius and make it harder to tell whether work stayed inside the task contract."
+        : "No current/open task is selected, so allowed_paths weight is not measurable.", "Split the task or replace broad globs with the concrete files/directories needed for this step.");
+    const workingNotesCount = inferredTask ? countWorkingNotes(inferredTask.working_notes) : null;
+    addMetric(metrics, findings, "workflow_weight.working_notes", "current task working_notes", workingNotesCount, workingNotesCount === null ? "PASS" : workingNotesCount <= 8 ? "PASS" : "BLOCKED", inferredTask ? "measured" : "unavailable", inferredTask
+        ? "working_notes is recovery-first scratch state; more than eight items usually means historical flow is leaking into active context."
+        : "No current/open task is selected, so working_notes weight is not measurable.", "Collapse notes to resume state, next step, blocker, last passed gate and do-not-retry facts; move history elsewhere.");
+    await addSelfTestReportMetric(projectRoot, inferredTask, metrics, findings);
+    await addLargestDocMetric(projectRoot, docRefs, metrics, findings);
+    await addValidatorMetric(projectRoot, "validate-harness", metrics, findings);
+    await addValidatorMetric(projectRoot, "validate-plan", metrics, findings);
+    await addTestingReadinessMetric(projectRoot, currentPhase, metrics, findings);
+    addLifecycleMetric(lifecycle, plan, currentPhase, currentTaskId, currentTask, openTasks, metrics, findings);
+    addRecoveryMetric(plan, inferredTask, metrics, findings);
+    addManualMetrics(options, metrics, findings);
+    const decision = combineDecision(metrics.map((metric) => metric.level));
+    return {
+        decision,
+        harness_root: root,
+        harness_root_source: rootConfig.source,
+        current_phase: currentPhase || "UNKNOWN",
+        current_task_id: currentTaskId,
+        inspected_at: inspectedAt,
+        metrics,
+        findings
+    };
+}
+export function renderWorkflowInspection(report) {
+    const lines = [
+        `Workflow inspection: ${report.decision}`,
+        `harness root: ${report.harness_root} (${report.harness_root_source})`,
+        `current phase: ${report.current_phase}`,
+        `current task: ${report.current_task_id || "(none)"}`,
+        "",
+        "Metrics:",
+        ...report.metrics.map((metric) => {
+            const value = metric.value === null ? "unknown" : String(metric.value);
+            return `- ${metric.level} ${metric.id}: ${value} [${metric.data_source}] - ${metric.details}`;
+        })
+    ];
+    if (report.findings.length > 0) {
+        lines.push("", "Findings:");
+        for (const finding of report.findings) {
+            lines.push(`- ${finding.severity} ${finding.code}: ${finding.message}`);
+            lines.push(`  next: ${finding.recommendation}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function renderWorkflowInspectionPrompt(report) {
+    return [
+        "# Workflow Self-Inspection Prompt",
+        "",
+        "你是用户仓库里的 Harness workflow self-inspection agent。请结合上面的 measured / inferred 指标和你最近一次真实执行经历，判断工作流是否符合预期。",
+        "",
+        "必须区分数据来源：",
+        "- measured: 脚本真实读到的文件、字段、validator 结果或命令耗时。",
+        "- inferred: 脚本只能从体量、字段缺失、重复或过长现象推断。",
+        "- self_reported: 你根据最近一次执行过程填写的耗时、turns、估算 token 和反复回读情况。",
+        "- unavailable: 当前环境没有 telemetry，不能伪造精确 token 或真实执行耗时。",
+        "",
+        "请回答：",
+        "1. 当前 workflow 从哪里进、当前任务是什么、下一步是什么？如果不能在 2 分钟内回答，记为 WARN。",
+        "2. 最近一次只是为了理解 workflow / 找事实源花了多少分钟、多少轮对话、估算多少 tokens？>15 分钟或 >10k tokens 记 WARN；>30 分钟或 >20k tokens 记 BLOCKED 候选。",
+        "3. 是否有会改变下一步动作的判断只埋在 notes/evidence/appendix/long doc 中，而没有 promoted 到 hard constraint、do_not_retry 或短 runbook 顶部？",
+        "4. 当前 Development Self-Test Report / TEST_CASES / TEST_REPORT 是否像可执行交接卡，而不是 debug log、operator log、evidence dump 或历史流水？",
+        "5. Review / Testing 是否能直接消费入口、核心路径、checkpoint、observable exit 和 evidence refs，而不用重新发明 runtime？",
+        "",
+        "输出格式：",
+        "- Decision: PASS | WARN | BLOCKED",
+        "- Data gaps: 列出 unavailable 或只能 self_reported 的指标",
+        "- Findings: 每条注明 measured / inferred / self_reported / unavailable",
+        "- Next action: 最小修复动作，不要扩展工作流体量",
+        "",
+        `Current script decision: ${report.decision}`,
+        `Current phase: ${report.current_phase}`,
+        `Current task: ${report.current_task_id || "(none)"}`
+    ].join("\n");
+}
+async function addValidatorMetric(projectRoot, gate, metrics, findings) {
+    try {
+        const report = await runValidator(projectRoot, gate);
+        addMetric(metrics, findings, `fact_source_alignment.${gate}`, gate, report.errors.length, report.errors.length === 0 ? "PASS" : "BLOCKED", "measured", report.errors.length === 0 ? `${gate} reported no errors.` : report.errors.join("; "), `Run npx sdlc-harness ${gate} and fix the reported source-of-truth drift.`);
+    }
+    catch (error) {
+        addMetric(metrics, findings, `fact_source_alignment.${gate}`, gate, null, "BLOCKED", "measured", error instanceof Error ? error.message : String(error), `Restore files required by ${gate}, then rerun inspect-workflow.`);
+    }
+}
+async function addTestingReadinessMetric(projectRoot, currentPhase, metrics, findings) {
+    const reportPath = path.join(projectRoot, ".docs/07_test/TEST_REPORT.md");
+    const casesPath = path.join(projectRoot, ".docs/07_test/TEST_CASES.md");
+    const shouldValidate = currentPhase === "TESTING" || (await pathExists(reportPath)) || (await pathExists(casesPath));
+    if (!shouldValidate) {
+        addMetric(metrics, findings, "testing_readiness.validate-test", "validate-test readiness", null, "PASS", "unavailable", "No TESTING fact source exists yet; validate-test readiness is not evaluated for this phase.", "Create TEST_CASES.md / TEST_REPORT.md only when TESTING has executable entry/exit facts.");
+        return;
+    }
+    try {
+        const report = await runValidator(projectRoot, "validate-test");
+        const level = report.errors.length === 0 ? "PASS" : currentPhase === "TESTING" ? "BLOCKED" : "WARN";
+        addMetric(metrics, findings, "testing_readiness.validate-test", "validate-test readiness", report.errors.length, level, "measured", report.errors.length === 0 ? "TESTING fact sources are structurally consumable." : report.errors.join("; "), "Keep TEST_CASES as reusable test design and TEST_REPORT as execution evidence; fix missing or drifting TC references.");
+    }
+    catch (error) {
+        addMetric(metrics, findings, "testing_readiness.validate-test", "validate-test readiness", null, currentPhase === "TESTING" ? "BLOCKED" : "WARN", "measured", error instanceof Error ? error.message : String(error), "Restore TESTING fact sources or remove stale partial test files until TESTING is in scope.");
+    }
+}
+function addLifecycleMetric(lifecycle, plan, currentPhase, currentTaskId, currentTask, openTasks, metrics, findings) {
+    let level = "PASS";
+    const problems = [];
+    if (!currentPhase) {
+        level = "BLOCKED";
+        problems.push("lifecycle.yaml does not define current_phase");
+    }
+    if (plan && "current_phase" in plan) {
+        level = "BLOCKED";
+        problems.push("plan.yaml duplicates current_phase");
+    }
+    if (currentTaskId && !currentTask) {
+        level = "BLOCKED";
+        problems.push("current_task_id does not match any task");
+    }
+    if (!currentTaskId && openTasks.length === 1 && currentPhase !== "COMPLETED") {
+        level = maxLevel(level, "WARN");
+        problems.push("one open task exists but current_task_id is empty");
+    }
+    const allowedNext = Array.isArray(lifecycle?.allowed_next_phases) ? lifecycle?.allowed_next_phases.length : 0;
+    if (allowedNext === 0 && !["COMPLETED", "UNKNOWN"].includes(currentPhase || "UNKNOWN")) {
+        level = maxLevel(level, "WARN");
+        problems.push("allowed_next_phases is empty");
+    }
+    addMetric(metrics, findings, "handoff_clarity.lifecycle", "lifecycle and current task clarity", problems.length, level, "measured", problems.length === 0 ? "Lifecycle and current task pointers are coherent." : problems.join("; "), "Keep current_phase only in lifecycle.yaml, current task only in plan.yaml, and regenerate allowed_next_phases through transition.py.");
+}
+function addRecoveryMetric(plan, currentTask, metrics, findings) {
+    if (!currentTask || !isHighRiskTask(currentTask)) {
+        addMetric(metrics, findings, "recovery_safety.resume_capsule", "high-risk resume capsule", null, "PASS", currentTask ? "inferred" : "unavailable", currentTask ? "Current task is not classified as high-risk by evidence_level or target_runtime_environment." : "No current/open task is selected.", "When a task becomes live/runtime/high-risk, add resume_capsule with canonical path, next step, blocker, do-not-retry and recovery refs.");
+        return;
+    }
+    const capsule = isRecord(plan?.resume_capsule) ? plan?.resume_capsule : undefined;
+    const problems = [];
+    if (!capsule)
+        problems.push("resume_capsule missing");
+    if (capsule && asStringList(capsule.do_not_retry).length === 0)
+        problems.push("do_not_retry missing");
+    if (capsule && asStringList(capsule.recovery_refs).length === 0)
+        problems.push("recovery_refs missing");
+    addMetric(metrics, findings, "recovery_safety.resume_capsule", "high-risk resume capsule", problems.length, problems.length === 0 ? "PASS" : "BLOCKED", "measured", problems.length === 0 ? "High-risk task has resume-first recovery state." : problems.join("; "), "Record resume_capsule before continuing high-risk runtime/live work.");
+}
+function addManualMetrics(options, metrics, findings) {
+    addManualMetric(metrics, findings, "self_reported.recent_minutes", "recent workflow minutes", options.recentMinutes, 15, 30);
+    addManualMetric(metrics, findings, "self_reported.recent_turns", "recent workflow turns", options.recentTurns, 6, 10);
+    addManualMetric(metrics, findings, "self_reported.estimated_tokens", "estimated workflow tokens", options.estimatedTokens, 10000, 20000);
+    if (options.estimatedTokens === undefined) {
+        addMetric(metrics, findings, "workflow_weight.actual_tokens", "actual model tokens", null, "PASS", "unavailable", "No local token telemetry was provided; inspect-workflow will not invent a precise token number.", "Pass --estimated-tokens when the Agent/client has a reliable estimate, or answer the --prompt self-check.");
+    }
+}
+function addManualMetric(metrics, findings, id, label, value, warnThreshold, blockThreshold) {
+    if (value === undefined)
+        return;
+    addMetric(metrics, findings, id, label, value, levelByThreshold(value, warnThreshold, blockThreshold), "self_reported", `${label} was supplied by the user/Agent, not measured from local files.`, "If this is WARN/BLOCKED, reduce workflow context weight before continuing.");
+}
+async function addSelfTestReportMetric(projectRoot, currentTask, metrics, findings) {
+    const implementationDoc = typeof currentTask?.implementation_doc === "string" ? currentTask.implementation_doc.trim() : "";
+    if (!implementationDoc) {
+        addMetric(metrics, findings, "workflow_weight.self_test_report_lines", "Development Self-Test Report lines", null, "PASS", "unavailable", "No current implementation_doc is selected, so self-test report size is not measurable.", "When SPRINTING is active, keep the report as a short handoff card.");
+        return;
+    }
+    const fullPath = path.join(projectRoot, implementationDoc);
+    const text = await readIfExists(fullPath);
+    if (!text) {
+        addMetric(metrics, findings, "workflow_weight.self_test_report_lines", "Development Self-Test Report lines", null, "BLOCKED", "measured", `implementation_doc is missing: ${implementationDoc}`, "Create or point to the current task implementation doc.");
+        return;
+    }
+    const section = markdownSection(text, ["development self-test report", "开发自测报告"]);
+    if (!section) {
+        addMetric(metrics, findings, "workflow_weight.self_test_report_lines", "Development Self-Test Report lines", null, "PASS", "unavailable", "No Development Self-Test Report section is present in the current implementation doc.", "Add the report when the current task has a self_test_contract.");
+        return;
+    }
+    const lines = countLines(section);
+    const highRisk = isHighRiskTask(currentTask);
+    const level = levelByThreshold(lines, highRisk ? 120 : 80, highRisk ? 180 : 120);
+    addMetric(metrics, findings, "workflow_weight.self_test_report_lines", "Development Self-Test Report lines", lines, level, "measured", highRisk ? "High-risk report line count uses 120/180 thresholds." : "Ordinary report line count uses 80/120 thresholds.", "Move debug/operator/evidence/exploration detail to runbook, evidence index or appendix; keep the report as a handoff card.");
+}
+async function addLargestDocMetric(projectRoot, docRefs, metrics, findings) {
+    let largest = 0;
+    let largestRef = "";
+    for (const ref of docRefs) {
+        const text = await readIfExists(path.join(projectRoot, ref));
+        if (!text)
+            continue;
+        const lines = countLines(text);
+        if (lines > largest) {
+            largest = lines;
+            largestRef = ref;
+        }
+    }
+    addMetric(metrics, findings, "drift_risk.largest_current_doc_lines", "largest current task doc lines", largestRef ? largest : null, largest > 700 ? "WARN" : largest > 300 ? "WARN" : "PASS", largestRef ? "inferred" : "unavailable", largestRef ? `${largestRef} is the largest current task doc.` : "No current task document refs were available.", "If a current handoff doc keeps growing, split durable decisions into ADRs, runtime steps into runbooks, and evidence bodies into evidence indexes.");
+}
+function addMetric(metrics, findings, id, label, value, level, dataSource, details, recommendation) {
+    metrics.push({ id, label, value, level, data_source: dataSource, details });
+    if (level !== "PASS") {
+        findings.push({
+            severity: level,
+            code: id,
+            message: details,
+            recommendation,
+            data_source: dataSource
+        });
+    }
+}
+async function readYamlObject(filePath) {
+    if (!(await pathExists(filePath)))
+        return undefined;
+    const parsed = parseYaml(await readText(filePath));
+    return isRecord(parsed) ? parsed : undefined;
+}
+async function readIfExists(filePath) {
+    return (await pathExists(filePath)) ? readText(filePath) : undefined;
+}
+function levelByThreshold(value, warnThreshold, blockThreshold) {
+    if (value > blockThreshold)
+        return "BLOCKED";
+    if (value > warnThreshold)
+        return "WARN";
+    return "PASS";
+}
+function combineDecision(levels) {
+    if (levels.includes("BLOCKED"))
+        return "BLOCKED";
+    if (levels.includes("WARN"))
+        return "WARN";
+    return "PASS";
+}
+function maxLevel(left, right) {
+    return combineDecision([left, right]);
+}
+function countLines(text) {
+    if (!text)
+        return 0;
+    return text.split(/\r?\n/).length;
+}
+function countWorkingNotes(value) {
+    if (Array.isArray(value))
+        return value.length;
+    if (typeof value === "string" && value.trim())
+        return 1;
+    return 0;
+}
+function collectTaskDocRefs(task) {
+    const refs = new Set();
+    for (const ref of asStringList(task.implementation_doc))
+        refs.add(normalizeDocRef(ref));
+    for (const ref of asStringList(task.result_docs))
+        refs.add(normalizeDocRef(ref));
+    if (isRecord(task.docs)) {
+        for (const value of Object.values(task.docs)) {
+            for (const ref of asStringList(value))
+                refs.add(normalizeDocRef(ref));
+        }
+    }
+    return [...refs].filter(Boolean);
+}
+function normalizeDocRef(ref) {
+    return ref.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function arrayOfRecords(value) {
+    return Array.isArray(value) ? value.filter(isRecord) : [];
+}
+function asStringList(value) {
+    if (Array.isArray(value))
+        return value.map((item) => String(item).trim()).filter(Boolean);
+    if (typeof value === "string" && value.trim())
+        return [value.trim()];
+    return [];
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isHighRiskTask(task) {
+    const evidence = isRecord(task.evidence_level) ? String(task.evidence_level.required ?? "") : "";
+    const target = isRecord(task.target_runtime_environment) ? String(task.target_runtime_environment.kind ?? "") : "";
+    return HIGH_RISK_EVIDENCE_LEVELS.has(evidence) || HIGH_RISK_TARGETS.has(target);
+}
+function markdownSection(text, headerTerms) {
+    const lines = text.split(/\r?\n/);
+    let start = -1;
+    let level = 0;
+    for (let index = 0; index < lines.length; index += 1) {
+        const match = lines[index].match(/^(#{1,6})\s+(.+)$/);
+        if (!match)
+            continue;
+        const title = match[2].toLowerCase();
+        if (headerTerms.some((term) => title.includes(term.toLowerCase()))) {
+            start = index;
+            level = match[1].length;
+            break;
+        }
+    }
+    if (start === -1)
+        return undefined;
+    let end = lines.length;
+    for (let index = start + 1; index < lines.length; index += 1) {
+        const match = lines[index].match(/^(#{1,6})\s+/);
+        if (match && match[1].length <= level) {
+            end = index;
+            break;
+        }
+    }
+    return lines.slice(start, end).join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-project-sdlc",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "CLI and canonical assets for the AI SDLC Harness workflow.",
   "type": "module",
   "bin": {