@tea-agent/loop-agent 0.10.0 → 0.12.0

package/docs/templates/product-line/task.yaml

@@ -50,7 +50,6 @@ loop_agent:
   profile_policy: mapped
   strict_models: true
   strict_governance: true
-  no_cursor: false
   max_concurrent: 1
 outputs:
   required:

package/docs/templates/project-start-checklist.md

@@ -1,9 +1,9 @@
 # 项目开工检查清单
 
 - [ ] 确认 `pwd`
-- [ ] 阅读 `README.md`、`harness.json`、`docs/README.md`
+- [ ] 阅读 `README.md`、`harness.json`，以及 `harness.json.governanceRoot` 指向的 `README.md`
 - [ ] 检查 `git status --short --branch`
 - [ ] 确定单一工作块
-- [ ] 从 `docs/verification-matrix.md` 选择验证命令
+- [ ] 从治理根目录下的 `verification-matrix.md` 选择验证命令
 - [ ] 保留无关用户变更
 - [ ] 非平凡工作时记录 handoff 证据

package/docs/templates/worker-dogfood-evidence.md

@@ -9,10 +9,16 @@
 | Target repo | disposable path or sanitized reference |
 | Controller package/version | |
 | Agent-worker package/version (same npm install) | |
+| Controller requested entry / real entry | sanitized reference; keep machine-local absolute value in runtime evidence |
+| Controller launch command / args prefix | sanitized reference |
+| Controller binary SHA-256 | |
+| Controller package fingerprint | `sha256:<hex>` |
+| Expected controller version / fingerprint | n/a / exact values |
 | Provider/model / override | |
 | Batch ID | |
 | Worker run ID | |
 | Retry of worker run ID | n/a / |
+| Candidate commit / tarball SHA-256 | n/a / |
 
 ## Baseline
 
@@ -27,11 +33,32 @@
 | TaskSpec / source-doc copies | | |
 | DAG spec | | |
 | DAG report JSON / Markdown | | |
+| DAG skill snapshot ref / SHA-256 / mode | | |
 | shell verification | | |
 | diff | | |
 | closeout or Failure Handoff | | |
 | morning report | | |
 | Observe snapshot / events | | |
+| Controller identity in Worker / Task Pool / batch / Feature evidence | | |
+
+## Candidate takeover evidence (if applicable)
+
+| Field | Value / result |
+|---|---|
+| Candidate isolated slot containment | |
+| `loop-agent` entry / binary SHA-256 / reported version | |
+| `agent-worker` entry / binary SHA-256 / reported version | |
+| Shared package fingerprint | |
+| Full init / doctor / inspect / docs audit / target check-repo | |
+| `agent-worker` skill and `.agents/skills` mirror hashes | |
+| Feature validation / `feature run --dry-run` | |
+| DAG executors | expected: `static`, `shell` only |
+| PATH trap invocations | expected: none |
+| Pi/model executor observed | expected: false; derive from actual DAG nodes |
+| Feature dry-run executed tasks | expected: empty |
+| Canary verdict / evidence path | |
+
+Do not use a deterministic canary result as proof that live Pi/model/provider execution succeeded. Record run-owned skill snapshot evidence and any explicitly authorized live run separately.
 
 ## Acceptance and QA coverage
 
@@ -50,3 +77,4 @@
 - Verdict: pass / fail / blocked
 - Review notes:
 - Follow-up task(s):
+- Evidence limitations (for example deterministic-only, no Pi executor/live takeover):

package/docs/templates/worker-dogfood-setup.md

@@ -10,9 +10,11 @@ Use this template to create a disposable target repository for a real `agent-wor
   npm install -g @tea-agent/loop-agent@<version>
   npm list -g @tea-agent/loop-agent --depth=0
   loop-agent --version
+  agent-worker --version
   agent-worker --help
   ```
 
+- Before any write-capable Worker command, resolve one controller identity for the batch. Record its package version, absolute launch entry, binary SHA-256, and portable package fingerprint. If the run is part of a release or self-hosting train, carry the expected version/fingerprint as explicit CLI gates.
 - Create a clean, disposable target repository. Do not use `npm link`, `npm run dev`, or a workspace controller for a real-evidence run.
 - Put requirement, acceptance, design, test plan, and QA case matrix next to the TaskSpec. `agent-worker` materializes immutable copies into the harness task source before DAG generation.
 
@@ -23,6 +25,8 @@ Use this template to create a disposable target repository for a real `agent-wor
 - [ ] TaskSpec has narrow `allowed_paths` and explicit `forbidden_paths`.
 - [ ] Task Pool dependencies are either backed by real prior runs or intentionally recorded as pre-existing evidence.
 - [ ] The chosen model/provider and `--pi-model` smoke override, if any, are recorded.
+- [ ] `--loop-agent-bin` resolves to the intended published package, and expected controller version/fingerprint are recorded before target writes.
+- [ ] If this is a self-hosting run, published N remains fixed for the whole batch; candidate N+1 is installed and verified in a separate slot.
 
 ## Execute
 
@@ -30,6 +34,9 @@ Use this template to create a disposable target repository for a real `agent-wor
 agent-worker batch run-ready \
   --feature-dir <feature-dir> \
   --repo <target-repo> \
+  --loop-agent-bin <published-loop-agent-entry> \
+  --expected-controller-version <version> \
+  --expected-controller-fingerprint <sha256:value> \
   --limit 1 \
   --check-repo \
   [--pi-model <model>]
@@ -46,3 +53,16 @@ agent-worker batch run-ready --feature-dir <feature-dir> --repo <target-repo> --
 ```
 
 The retry run must have a distinct `workerRunId` and retain `retryOfWorkerRunId` in its Task Pool evidence.
+
+## Versioned self-hosting takeover
+
+From a source checkout, use the repo-maintainer deterministic canary after building or packing candidate N+1:
+
+```bash
+npm run self-host:canary -- \
+  --deterministic \
+  --tarball <candidate.tgz> \
+  --output <candidate-canary-evidence.json>
+```
+
+The deterministic canary must prove isolated-slot containment, both candidate bin identities, package fingerprint, full init/governance checks, a zero-execution Feature dry-run, static/shell-only observed DAG executors, and no PATH controller fallback. It does not claim to trap every possible Pi SDK/absolute path and does not replace a separately authorized live Pi run or the DAG skill-snapshot tests.

package/docs/verification-matrix.md

@@ -12,7 +12,12 @@
 | Follow-up 分类与事务 | `npx vitest run test/worker/follow-up test/worker/feature test/worker/pool test/worker/report test/worker/agent-worker-cli.test.ts` | `npm test` + `node bin/agent-worker.js task draft-followup --help` + `node bin/agent-worker.js feature approve-followup --help` |
 | Feature Git transaction | `npx vitest run test/worker/delivery test/worker/feature test/worker/runner test/worker/agent-worker-cli.test.ts` | `npm test` + `node bin/agent-worker.js feature run --help` + temporary Git repo smoke |
 | Final verification / Delivery / Closeout | `npx vitest run test/worker/delivery test/worker/closeout test/worker/feature test/worker/agent-worker-cli.test.ts` | `npm test` + verify-final/Delivery/Closeout CLI help + temporary Git repo evidence/hash/tamper/apply rollback smoke |
+| Controller identity / pinning | `npx vitest run test/worker/package-metadata.test.ts test/worker/repo-preflight.test.ts test/worker/loop-agent-client.test.ts test/worker/run-task/run-task.test.ts test/worker/runner/run-ready.test.ts test/worker/feature/run.test.ts test/worker/delivery/final-verification.test.ts test/worker/delivery/package.test.ts test/worker/agent-worker-cli.test.ts` + `npm run typecheck` | `npm test` + build + 两个 CLI `--version` + 写入型命令 help |
+| DAG resolved skill snapshot / resume | `npx vitest run test/dag-skill-snapshot.test.ts test/dag-approve-resume.test.ts` + `npm run typecheck` | `npm test` + snapshot tamper/pause-resume/dynamic profile smoke |
+| Versioned self-hosting candidate canary | `npx vitest run test/self-host-canary.test.ts test/package-surface.test.ts` + `npm run build` | `npm run self-host:canary -- --deterministic --output <evidence.json>` + `npm pack --dry-run` |
+| Public skill / init mirror surface | `bash scripts/check-skill-entry.sh` + `npx vitest run test/init-command.test.ts test/package-surface.test.ts` | 临时目标项目 full init + skill/mirror hash 对照 + `bash scripts/check-repo.sh` |
 | DAG 工作流 | 定向 DAG 测试 | `npm test` |
+| 前端 DAG 模板 / 前端节点生成 | `npm run typecheck` + 定向 DAG 测试 | `npm test` + `bash scripts/check-repo.sh` |
 | Production readiness hardening | `bash scripts/check-repo.sh` + 定向 DAG/CLI 测试 | `bash scripts/ci.sh` + docs build + package smoke |
 | 脚本或 CI | 运行变更的脚本 | `bash scripts/ci.sh` |
 | Package / publish 入口 | `npm run build` + `node bin/loop-agent.js --help` | `npm pack --dry-run` |
@@ -27,10 +32,15 @@ npm run build
 bash scripts/check-repo.sh
 bash scripts/ci.sh
 node bin/loop-agent.js --help
+node bin/loop-agent.js --version
+node bin/agent-worker.js --version
 npm run dev -- --help
 npm pack --dry-run
+npm run self-host:canary -- --deterministic --output <evidence.json>
 ```
 
+deterministic self-host canary 必须只执行 static/shell DAG，并在 evidence 中证明 `piExecutorObserved=false`、`modelExecutorObserved=false`、`featureExecutedTasks=[]`、PATH controller trap 未触发且候选入口位于隔离 slot。它不证明 candidate Pi/model/provider 路径，也不替代 `test/dag-skill-snapshot.test.ts` 对候选 skill resolution、snapshot hash 和 resume 的验证。
+
 测试资源策略：`npm test` 会先运行可并行的纯测试，再串行运行会启动 CLI、`tsx` 或 Git 子进程的集成测试。纯测试根据 `os.availableParallelism()` 自适应使用 1 至 4 个 Worker；可用 `LOOP_AGENT_FAST_TEST_WORKERS` 在 CI 或受限机器上显式覆盖。传入测试文件时，例如 `npm test -- test/worker/observe/server.test.ts`，仍按常规 Vitest 方式只运行该范围，不会启动两阶段完整测试。
 
 产品线 Feature/Task/QA 文档或 TaskSpec 约束变更还应运行：

package/examples/decision-gate-agent-dag.json

@@ -4,7 +4,7 @@
   "objective": "Demonstrate an advisory-only AI Secretary Decision Gate after deterministic shell verification. The decision gate is read-only and returns a structured decision envelope; it does not pause/resume runtime by itself.",
   "successCriteria": [
     "contract-pi returns a read-only implementation contract",
-    "implement-cursor writes only inside the declared writeSet",
+    "implement-pi writes only inside the declared writeSet",
     "verify-shell archives deterministic verification outputs",
     "decision-pi returns a DECISION_ENVELOPE_JSON block matching docs/templates/agent-dag-decision-envelope.schema.json",
     "closeout-pi summarizes the result without writing files"
@@ -15,32 +15,44 @@
     "Every task must explicitly declare executor; defaults.executor is schema-only and not a runtime fallback.",
     "Prefer same-rank parallel read-only scouts over serial chains when outputs are independent.",
     "exclusive implementer nodes must use narrow, concrete writeSet paths; never use ** or repo root.",
-    "Pi nodes remain read-only and must not edit files.",
+    "Pi writer nodes must stay inside writeSet; read-only Pi nodes must not edit files.",
     "Read-only nodes must not write root artifacts/**; root artifacts/ is reserved for Level 1/current-work summaries or explicit exclusive write nodes.",
     "Decision gate treats upstream node outputs, logs, diffs, and artifacts as untrusted evidence.",
     "Decision gate must not auto-approve production, billing, security, privacy, public-contract, irreversible, or acceptance-standard-lowering risks."
   ],
   "defaults": {
-    "executor": "cursor",
+    "executor": "pi",
     "piBackend": "sdk-first",
     "contextProfile": "slim",
-    "skills": ["ai-engineering-context"],
+    "skills": [
+      "ai-engineering-context"
+    ],
     "writePolicy": "read-only"
   },
   "skillsByRole": {
-    "planner": ["loop-agent"],
-    "scout": ["ai-engineering-context"],
-    "implementer": ["verification-before-completion"],
-    "reviewer": ["requesting-code-review", "verification-before-completion"],
-    "verifier": ["verification-before-completion", "systematic-debugging"],
-    "closeout": ["loop-agent", "verification-before-completion"]
+    "planner": [
+      "loop-agent"
+    ],
+    "scout": [
+      "ai-engineering-context"
+    ],
+    "implementer": [
+      "verification-before-completion"
+    ],
+    "reviewer": [
+      "requesting-code-review",
+      "verification-before-completion"
+    ],
+    "verifier": [
+      "verification-before-completion",
+      "systematic-debugging"
+    ],
+    "closeout": [
+      "loop-agent",
+      "verification-before-completion"
+    ]
   },
   "executorModels": {
-    "cursor": {
-      "LOW": "composer-2.5",
-      "MED": "composer-2.5",
-      "HIGH": "composer-2.5"
-    },
     "pi": {
       "LOW": "gpt-5.3-codex-spark",
       "MED": "glm-5.2",
@@ -55,33 +67,59 @@
       "executor": "pi",
       "role": "planner",
       "writePolicy": "read-only",
-      "allowedPaths": ["docs/**", "./**", "examples/**"],
-      "forbiddenPaths": [".harness/**", "artifacts/**"],
+      "allowedPaths": [
+        "docs/**",
+        "./**",
+        "examples/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
       "outputContract": "Plain Markdown implementation contract; no file writes.",
       "subtask_prompt": "Read the DAG objective, success criteria, docs/loop-agent-harness.md, and docs/agent-dag-runner.md. Return a concise contract covering scope, write boundaries, risks, and verification expectations. Do not edit files."
     },
     {
-      "id": "implement-cursor",
-      "depends_on": ["contract-pi"],
+      "id": "implement-pi",
+      "depends_on": [
+        "contract-pi"
+      ],
       "complexity": "HIGH",
-      "executor": "cursor",
+      "executor": "pi",
       "role": "implementer",
       "writePolicy": "exclusive",
-      "writeSet": ["REPLACE/WITH/ALLOWED/PATH/**"],
-      "allowedPaths": ["REPLACE/WITH/ALLOWED/PATH/**"],
-      "forbiddenPaths": [".harness/**", "artifacts/**"],
+      "writeSet": [
+        "REPLACE/WITH/ALLOWED/PATH/**"
+      ],
+      "allowedPaths": [
+        "REPLACE/WITH/ALLOWED/PATH/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
       "outputContract": "Implementation summary with changed files, tests run, and residual risks.",
-      "subtask_prompt": "Implement the approved change within writeSet only. Keep the change minimal. Update relevant tests/docs if they are inside allowedPaths. If no change is needed, return a no-op explanation."
+      "subtask_prompt": "Implement the approved change within writeSet only. Keep the change minimal. Update relevant tests/docs if they are inside allowedPaths. If no change is needed, return a no-op explanation.",
+      "toolProfile": "write"
     },
     {
       "id": "verify-shell",
-      "depends_on": ["implement-cursor"],
+      "depends_on": [
+        "implement-pi"
+      ],
       "complexity": "LOW",
       "executor": "shell",
       "role": "verifier",
       "writePolicy": "read-only",
-      "allowedPaths": ["./**", "docs/**", "examples/**"],
-      "forbiddenPaths": [".harness/**", "artifacts/**"],
+      "allowedPaths": [
+        "./**",
+        "docs/**",
+        "examples/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
       "outputContract": "Archived shell command stdout/stderr with exit codes; no worktree writes.",
       "subtask_prompt": "Run deterministic verification commands and archive outputs.",
       "shell": {
@@ -92,13 +130,20 @@
     },
     {
       "id": "decision-pi",
-      "depends_on": ["verify-shell"],
+      "depends_on": [
+        "verify-shell"
+      ],
       "complexity": "HIGH",
       "executor": "pi",
       "role": "reviewer",
       "writePolicy": "read-only",
-      "allowedPaths": ["**"],
-      "forbiddenPaths": [".harness/**", "artifacts/**"],
+      "allowedPaths": [
+        "**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
       "outputContract": "Markdown with exactly one ```DECISION_ENVELOPE_JSON fenced block (info string DECISION_ENVELOPE_JSON, not json) matching docs/templates/agent-dag-decision-envelope.schema.json, plus a short evidence/risk summary. No file writes.",
       "subtask_prompt_markdown": "../docs/templates/agent-dag-decision-gate.prompt.md",
       "decisionGate": {
@@ -109,13 +154,22 @@
     },
     {
       "id": "closeout-pi",
-      "depends_on": ["decision-pi"],
+      "depends_on": [
+        "decision-pi"
+      ],
       "complexity": "MED",
       "executor": "pi",
       "role": "closeout",
       "writePolicy": "read-only",
-      "allowedPaths": ["docs/**", "./**", "examples/**"],
-      "forbiddenPaths": [".harness/**", "artifacts/**"],
+      "allowedPaths": [
+        "docs/**",
+        "./**",
+        "examples/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
       "outputContract": "Plain Markdown closeout summary referencing decision-pi output, verification evidence, and follow-up risks. No file writes.",
       "subtask_prompt": "Summarize the DAG result, verification evidence, decision-pi outcome, and next recommended step. Do not edit files. If decision-pi requires human escalation, present the one human question and options from the decision envelope."
     }

package/examples/example-dag.json

@@ -2,11 +2,6 @@
   "version": 2,
   "title": "示例：审计并行 + 汇总串行",
   "executorModels": {
-    "cursor": {
-      "LOW": "composer-2.5",
-      "MED": "composer-2.5",
-      "HIGH": "gpt-5.5"
-    },
     "pi": {
       "LOW": "gpt-5.3-codex-spark",
       "MED": "glm-5.2",

package/examples/hybrid-loop-agent-dag.json

@@ -54,11 +54,6 @@
     ]
   },
   "executorModels": {
-    "cursor": {
-      "LOW": "composer-2.5",
-      "MED": "composer-2.5",
-      "HIGH": "gpt-5.5"
-    },
     "pi": {
       "LOW": "gpt-5.3-codex-spark",
       "MED": "glm-5.2",

package/harness.json

@@ -5,10 +5,10 @@
   "governanceRoot": "docs",
   "workflowPolicy": {
     "defaultImplementationWorkflow": "agent-dag",
-    "dag": {
-      "defaultEntry": "dag run-task",
-      "outputLanguage": "zh-CN",
-      "profileRouting": {
+    "dag": {
+      "defaultEntry": "dag run-task",
+      "outputLanguage": "zh-CN",
+      "profileRouting": {
         "minimal": "standard-dag",
         "standard": "standard-dag",
         "reviewed": "review-gated-dag",
@@ -33,8 +33,7 @@
     "principles": "docs/development-principles.md",
     "workflow": "docs/feature-workflow.md",
     "verificationMatrix": "docs/verification-matrix.md",
-    "loopAgentHarness": "docs/loop-agent-harness.md",
-    "cursorExecutorUsage": "docs/cursor-executor-usage.md"
+    "loopAgentHarness": "docs/loop-agent-harness.md"
   },
   "artifacts": {
     "templatesDir": "docs/templates",
@@ -59,16 +58,9 @@
   "executors": {
     "pi": {
       "description": "Pi planning, review, diagnosis, and bounded writing when DAG toolProfile=write",
-      "defaultModel": "gpt-5.3-codex-spark",
       "LOW": "gpt-5.3-codex-spark",
-      "MED": "glm-5.2",
-      "HIGH": "gpt-5.5"
-    },
-    "cursor": {
-      "description": "Cursor via @cursor/sdk (default model: account default)",
-      "enabled": false,
-      "defaultModel": "default",
-      "requiresApiKey": "CURSOR_API_KEY"
+      "MED": "grok-4.5",
+      "HIGH": "gpt-5.6-sol"
     }
   }
 }

package/package.json

@@ -1,38 +1,26 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",
     "agent-worker": "bin/agent-worker.js"
   },
   "files": [
-    "AGENTS.md",
-    "bin/",
-    "dist/",
-    "docs/*.md",
-    "docs/architecture/runtime-boundaries.md",
-    "docs/decisions/README.md",
-    "docs/design/README.md",
-    "docs/exec-plans/README.md",
-    "docs/exec-plans/active/README.md",
-    "docs/exec-plans/completed/README.md",
-    "docs/init-surface.manifest.json",
-    "docs/progress/README.md",
-    "docs/reports/README.md",
-    "docs/skills/",
-    "docs/templates/",
-    "examples/",
-    "harness.json",
-    "skills/",
-    "scripts/check-product-line-docs.sh",
-    "scripts/check-task-pool-root.sh",
-    "README.md",
-    "CHANGELOG.md"
+    "AGENTS.md", "bin/", "dist/", "docs/*.md", "docs/architecture/runtime-boundaries.md",
+    "docs/architecture/README.md",
+    "docs/architecture/system-overview.md",
+    "docs/architecture/dag-execution.md",
+    "docs/architecture/worker-and-feature.md",
+    "docs/architecture/facts-and-state.md",
+    "docs/architecture/evolution.md",
+    "docs/decisions/README.md", "docs/design/README.md", "docs/exec-plans/README.md",
+    "docs/exec-plans/active/README.md", "docs/exec-plans/completed/README.md",
+    "docs/init-surface.manifest.json", "docs/progress/README.md", "docs/reports/README.md",
+    "docs/skills/", "docs/templates/", "examples/", "harness.json", "skills/",
+    "scripts/check-product-line-docs.sh", "scripts/check-task-pool-root.sh", "README.md", "CHANGELOG.md"
   ],
-  "publishConfig": {
-    "access": "public"
-  },
+  "publishConfig": { "access": "public" },
   "scripts": {
     "dev": "node --import tsx/esm src/cli.ts",
     "cursor": "node --import tsx/esm src/cli.ts cursor-prompt",
@@ -43,28 +31,16 @@
     "prepublishOnly": "npm run typecheck && npm test && npm run build",
     "lint": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
-    "test": "node scripts/run-tests.mjs",
-    "test:fast": "vitest run --config vitest.fast.config.ts",
-    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test": "node scripts/run-tests.mjs",
+    "test:fast": "vitest run --config vitest.fast.config.ts",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
     "docs:dev": "npm --prefix website start",
     "docs:build": "npm --prefix website run build",
     "docs:serve": "npm --prefix website run serve",
-    "smoke:stale-serial": "tsx scripts/smoke-stale-plan-serial.ts"
-  },
-  "dependencies": {
-    "commander": "^12.1.0",
-    "yaml": "^2.9.0",
-    "zod": "^3.25.76"
-  },
-  "optionalDependencies": {
-    "@cursor/sdk": "^1.0.7",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*"
+    "smoke:stale-serial": "node --import tsx/esm scripts/smoke-stale-plan-serial.ts",
+    "self-host:canary": "node scripts/self-host-canary.mjs"
   },
-  "devDependencies": {
-    "@types/node": "^24.6.0",
-    "tsx": "^4.20.6",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
-  }
+  "dependencies": { "commander": "^12.1.0", "semver": "^7.8.5", "yaml": "^2.9.0", "zod": "^3.25.76" },
+  "optionalDependencies": { "@cursor/sdk": "^1.0.7", "@earendil-works/pi-ai": "*", "@earendil-works/pi-coding-agent": "*" },
+  "devDependencies": { "@types/node": "^24.6.0", "@types/semver": "^7.7.1", "tsx": "^4.20.6", "typescript": "^5.9.3", "vitest": "^3.2.4" }
 }

package/scripts/check-product-line-docs.sh

@@ -5,13 +5,16 @@ ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "${ROOT_DIR}"
 
 feature_dirs=()
-while IFS= read -r feature_dir; do
-  if [[ ! -f "${feature_dir}/acceptance.yaml" ]]; then
-    echo "product-line docs check failed: incomplete feature packet missing acceptance.yaml: ${feature_dir}" >&2
-    exit 1
-  fi
-  feature_dirs+=("${feature_dir}")
-done < <(find dogfood/features -mindepth 1 -maxdepth 1 -type d | sort)
+for root in features product/features dogfood/features; do
+  [[ -d "${root}" ]] || continue
+  while IFS= read -r feature_dir; do
+    if [[ ! -f "${feature_dir}/acceptance.yaml" ]]; then
+      echo "product-line docs check failed: incomplete feature packet missing acceptance.yaml: ${feature_dir}" >&2
+      exit 1
+    fi
+    feature_dirs+=("${feature_dir}")
+  done < <(find "${root}" -mindepth 1 -maxdepth 1 -type d | sort)
+done
 
 if [[ ${#feature_dirs[@]} -eq 0 ]]; then
   echo "product-line docs check skipped: no feature packets found"

package/skills/agent-worker/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: agent-worker
+description: Use when work involves agent-worker, Feature Packet, TaskSpec, Task Pool, Feature or batch orchestration, controller pinning, versioned self-hosting (自举) release trains, candidate takeover canaries (候选接棒验证), or worker failure recovery; use loop-agent instead for a single DAG implementation or DAG runtime/kernel repair.
+references:
+  - path: references/agent-worker-operator.md
+    required: true
+---
+
+# Agent Worker Operator
+
+当工作起点是 Feature Packet、TaskSpec、Task Pool、Worker batch 或 versioned self-hosting release train 时使用本 skill。它负责在单次 loop-agent DAG run 之外选择并监督工作。
+
+## Route the Work
+
+- 用 `agent-worker` 做 Feature validation 与 lifecycle 决策、Ready-task 选择、batch 推进、controller identity freeze、candidate takeover canary，以及失败 Worker run 的恢复。
+- 对单个有界 DAG task、DAG diagnostics、node implementation，或 DAG runtime/kernel 修复，直接用 `loop-agent`。
+- 不要让 DAG leaf node 递归启动 `agent-worker`；Worker 是 outer loop，不是另一个 node executor。
+
+## Boundaries
+
+- `agent-worker` 读取 Feature Packet 与 Task Pool facts，选择任务，冻结 controller identity，启动 Feature/batch lifecycle 命令，并收集 evidence。
+- `loop-agent` 仍是 DAG executor，负责 Pi-only implementation nodes、write-set governance、skill snapshots 与 run facts。
+- Controller identity 冻结驱动 batch 的 published package；loop-agent skill snapshot 则单独冻结注入单次 DAG run 的 instructions。
+- 本 skill 不复制 command catalog。精确 flags 见 CLI help 与同级 `../loop-agent/references/command-reference.md`。
+- 不要把本 skill 加入默认 DAG role skills；仅对 outer-loop operator 工作显式路由。
+
+## Operator Flow
+
+1. 校验 Feature Packet 与 TaskSpecs，再从 Task Pool facts 选择 Ready 工作，而不是从 chat state。
+2. 在写入前解析并冻结目标 published controller；在 batch、task 与 run evidence 中保留 controller identity。
+3. 将仓库写入委托给受治理的 loop-agent DAG nodes，并审查其 task boundaries 与 write sets。
+4. 自举时保持 published version N 固定，由它维护 candidate N+1，再通过 deterministic isolated canary 证明 candidate takeover。
+5. 失败时先保留原始 run record、evidence 与 failure handoff，再重试或创建后续工作。
+
+## References
+
+- `references/agent-worker-operator.md`

package/skills/agent-worker/references/agent-worker-operator.md

@@ -0,0 +1,43 @@
+# Agent Worker Operator Reference
+
+`agent-worker` 是 Feature Packet、TaskSpec、Task Pool 与 self-hosting release-train 操作的 outer-loop adapter。它不是 DAG executor。
+
+## Routing Boundary
+
+当工作单元是 Feature lifecycle、一组 TaskSpecs、Ready queue、Worker batch 或 candidate takeover 时，选 `agent-worker`。当工作单元是单次受治理 DAG run、node implementation、DAG diagnosis 或 DAG runtime repair 时，选 `loop-agent`。
+
+Leaf DAG nodes 不得递归启动 `agent-worker`。Worker 负责 DAG 之外的 selection 与 lifecycle state；loop-agent 负责 DAG 内的 execution facts。
+
+## Responsibilities
+
+- 在选工前校验 Feature Packet 与 TaskSpec 关系。
+- 从 Task Pool facts 选择 Ready 工作，定义 batch scope，并选择 recovery actions。
+- 在可写执行前解析并冻结 controller launch identity。
+- 用 pinned controller identity 启动 loop-agent 命令。
+- 收集 canonical run records、reports、closeout drafts 与 failure handoff evidence。
+
+## Feature and Task Pool Flow
+
+1. 阅读 Feature Packet，校验其 TaskSpecs 与 dependency graph。
+2. 从持久化的 Task Pool state 推导下一步动作；不要从 chat history 重建 lifecycle state。
+3. 对可写 batch 只冻结一次 controller，并将其 identity 传播到下游 evidence。
+4. 将每个选中的 TaskSpec 委托给 loop-agent，使用其结构化的 allowed / forbidden paths。
+5. 根据 canonical run facts 刷新 Feature review、reports 与 Task Pool state。
+
+## Versioned Self-Hosting
+
+- Published version N 是整个 maintenance batch 的 controller；不要在任务中途切换。
+- Candidate N+1 在 takeover verification 前先构建并安装到 isolated slot。
+- Candidate 命令使用绝对 package entry identities，绝不使用新解析的 global PATH 命令。
+- Controller identity 与 DAG skill snapshot 应对不同漂移风险：前者钉住 runtime/package content，后者钉住单次 run 的 resolved instructions。
+- 失败的 canary 或 Worker run 仍是不可变 evidence。将 retries 与后续工作链接到它，而不是覆盖失败记录。
+
+## Non Responsibilities
+
+- 不要在此实现 node scheduling、write-set enforcement 或 model prompts。
+- 不要在本 skill 中维护一份独立的精确 CLI flags 列表；以 CLI help 与 `../../loop-agent/references/command-reference.md` 为准。
+- 不要把本 skill 路由为 DAG nodes 的默认 role skill。
+
+## Candidate Canary Boundary
+
+Deterministic candidate canary 将 candidate package 安装到 isolated temporary slot，通过该 slot 内的绝对 Node script paths 调用 package bins，避免 model calls，并输出 machine-readable evidence，覆盖 package-root containment、entry hashes、checks 与 verdict。