@tea-agent/loop-agent 0.13.0-beta.0 → 0.14.0

package/skills/browser-tools/package.json

@@ -0,0 +1,19 @@
+{
+	"name": "browser-tools",
+	"version": "1.0.0",
+	"type": "module",
+	"description": "Minimal CDP tools for collaborative site exploration",
+	"author": "Mario Zechner",
+	"license": "MIT",
+	"dependencies": {
+		"@mozilla/readability": "^0.6.0",
+		"cheerio": "^1.1.2",
+		"jsdom": "^27.0.1",
+		"puppeteer": "^24.31.0",
+		"puppeteer-core": "^23.11.1",
+		"puppeteer-extra": "^3.3.6",
+		"puppeteer-extra-plugin-stealth": "^2.11.2",
+		"turndown": "^7.2.2",
+		"turndown-plugin-gfm": "^1.0.2"
+	}
+}

package/skills/frontend-implementation/SKILL.md

@@ -5,7 +5,9 @@ description: >-
 references:
   - path: references/node-contracts.md
     required: true
-    maxChars: 4800
+    # Compact contract index must stay under skill total budget (~10k with body + other refs).
+    # Headroom above current ~4k file; do not raise alone without checking totalMaxChars.
+    maxChars: 6000
   - path: references/design-spec.md
     required: true
     maxChars: 3000

package/skills/frontend-implementation/references/node-contracts.md

@@ -1,76 +1,27 @@
 # Frontend Node Contracts
 
-All pre-write nodes are read-only. Preserve IDs, source labels, commands, language,
-and required headings.
+Pre-write nodes are read-only. Preserve IDs, labels, commands, language, required headings.
 
-## `frontend-contract-pi`
+## Core nodes
 
-Read all inputs and define `Scope`, `Non-goals`, `Acceptance Criteria`, `UI States`,
-`Target Runtime Environment`, `Risks`, and `Verification Expectations`. Never turn a
-guess into a requirement.
+- **`frontend-contract-pi`**: `Scope`, `Non-goals`, `Acceptance Criteria`, `UI States`, `Target Runtime Environment`, `Risks`, `Verification Expectations`. No guessed requirements.
+- **`frontend-scout-pi`**: routes, components, tokens, data/API/Mock, scripts, tests, assets. Fact vs inference vs gap. Knowledge base first; else search+read `<repoRoot>/openSpec/**` before repo fallback. Output stack, routes, components, styling, conventions, state/data, test entry points, reuse, risks.
+- **`frontend-mock-assess-pi` + gate**: first non-empty line  
+  `MOCK_STRATEGY: native|browser-intercept|request-adapter|not-needed|blocked`  
+  Prefer native Mock; browser intercept only with existing e2e; request-adapter only for reversible local preview. `not-needed` needs positive no-remote/stable-backend evidence; invalid when `frontendMock.policy=required`. `blocked` for missing/conflicting contracts, unsafe paths/deps, unread specs, production-default-on, unverifiable entrypoints. Output Mock Decision, API/spec/service evidence, backend readiness, selection evidence, endpoint/fixture matrix, activation, targets, production safety, verification plan, real-integration gap, blocking issues. Never invent fields, store secrets, comment real requests, import test mocks into production, or treat Mock as real integration. Gate uses `first-non-empty` only; never authorizes writes. Unsafe required contracts → no writer.
+- **`frontend-plan-pi` + design loop**: AC → steps, in-bound files, UI states, reuse, deps, activation/rollback, frozen verify entrypoints, real-integration gap. First gate: `VERDICT: pass|request-revision`. Pass may emit `PASS_NO_REVISION_NEEDED`; else full corrected plan without invented evidence. Final review rechecks plan/findings/revision/assessment/Mock safety. Only final `VERDICT: pass` authorizes writes; failure → replan/rerun (not dev-fix).
+- **`frontend-implement-pi`**: sole exclusive writer. Stay in `writeSet`; real requests default-on; Mock reversible, dev/test-only, production-off. Atomic handler/intercept/adapter with consumer+tests. Stop on forbidden paths or guesses. Output changed files, behavior, UI states, styling notes, verification attempted, residual risks. Optional mock-verify when frozen; static+behavior always; behavior must prove page consumption.
 
-## `frontend-scout-pi`
+## Contract / trace / stages (M1–M2)
 
-Inspect routes, components, styles/tokens, data/API/Mock seams, scripts, tests, and
-assets. Separate fact, inference, and gap. Query the knowledge base; otherwise search
-and read `<repoRoot>/openSpec/**` before repository fallback. Output `Frontend Stack`,
-`Routes`, `Components`, `Styling System`, `Existing Design Conventions`, `State / Data
-Flow`, `Test Entry Points`, `Reuse Opportunities`, and `Risks`.
+- Contract shell: `jsonArtifactGate` → `contracts/frontend-implementation-contract.json` from revision (one fenced JSON or pure JSON); schemaId `frontend-implementation-contract-v1`. Final design + implement depend on it; `MOCK_STRATEGY: blocked` not implementable.
+- Trace shell: `frontend-verification-trace-gate` binds contract `verificationTargets` to static/behavior records (`commandLabels`, file exists, optional symbol). Assess `MOCK_STRATEGY:` must match `mockApi.strategy` when present. Writes `contracts/frontend-verification-trace.json`. Browser/visual always `not-run`.
+- Implement stages: (1) contract confirm (2) tests sync (3) component/UI (4) API/Mock (5) frozen checks (6) diff cleanup. Summary: Contract Ref, Changed Files, Requirements, UI States, Tests, Verification Attempts, Deviations, Residual Risks.
 
-## `frontend-mock-assess-pi` and contract gate
+## Repair (M3)
 
-Consume contract, scout, generation-time capability seed, and frozen verification
-entrypoints. First non-empty line:
+static/behavior/trace may `nonZeroExitPolicy: record`. Assess → `contracts/frontend-repair-assessment.json`. Repair-contract fail-closed on non-repairable (contract/path/dependency/credential/deploy/spec-unclear) or writeSet expansion. `frontend-repair-pi`: same writeSet as implement; no re-spec; max 1 attempt. Reverify/retrace fail policy; review/closeout use post-repair evidence.
 
-`MOCK_STRATEGY: native|browser-intercept|request-adapter|not-needed|blocked`
+## Risk & capability (M4–M6)
 
-Prefer a proven native service. Use browser interception only with an existing
-browser/e2e harness, or a request adapter/DI seam for reversible local preview.
-`not-needed` requires positive no-remote/stable-real-backend evidence and applicable
-behavior verification; it is invalid when `frontendMock.policy=required` resolved to
-a required decision. Select `blocked` for missing/conflicting contracts, unsafe or
-unauthorized paths/dependencies, unread/conflicting specs, production-default-on
-behavior, or frozen entrypoints that cannot verify the selected mechanism.
-
-Output `Mock Decision`, `API Contract Evidence`, `Specification Evidence`, `Service
-Evidence`, `Backend Readiness`, `Selection Evidence`, `Endpoint / Fixture Matrix`,
-`Activation`, `Target Files`, `Production Safety`, `Verification Plan`, `Real
-Integration Gap`, and `Blocking Issues`. Trace methods, paths, fields, statuses, UI
-states, fixtures, and consumers to API/schema evidence. Never invent fields, store
-secrets/real user data, comment real requests, import test mocks from production, or
-claim Mock evidence is real integration.
-
-`frontend-mock-contract-gate-shell` accepts only allowed non-blocked strategy lines
-using `first-non-empty`; it never authorizes writes. A generation-time unsafe or
-incomplete explicitly-required contract produces contract/scout/assessment/gate only,
-with no writer.
-
-## `frontend-plan-pi` and design loop
-
-Plan directly consumes contract, scout, assessment, and gate. Map criteria to
-ordered steps, in-bound files, UI states, interactions, reuse, dependencies,
-activation/rollback, fixed verification entrypoints, and the real-integration gap.
-Output `Implementation Steps`, `Target Files`, `UI State Handling`, `Styling /
-Component Strategy`, `Interaction Notes`, `Mock / API Strategy`, `Dependency Policy`,
-`Verification Plan`, `Real Integration Gap`, and `Residual Risks`.
-
-The first design gate accepts `VERDICT: pass` or `VERDICT: request-revision` for
-read-only revision. On pass, `frontend-plan-revision-pi` outputs
-`PASS_NO_REVISION_NEEDED`; otherwise it returns a complete corrected plan without
-manufacturing evidence. Final design review directly rechecks the original plan,
-first findings, revision, assessment, and all Mock safety boundaries. Only the final
-`VERDICT: pass` gate authorizes writes; failure routes to replan/rerun, not dev-fix.
-
-## `frontend-implement-pi`
-
-This is the sole exclusive writer. Consume the approved plan, final review/gate, and
-assessment. Implement only inside `writeSet`; keep the real request default and Mock
-activation reversible, dev/test-only, and production-off. Native handler/fixture,
-browser interception, or request adapter changes stay atomic with their UI consumer
-and tests. Stop on forbidden paths or guesses. Output `Changed Files`, `Implemented
-Behavior`, `UI States Covered`, `Styling / Component Notes`, `Verification Attempted`,
-and `Residual Risks`.
-
-When trusted Mock-specific commands were frozen at generation, a read-only
-`frontend-mock-verify-shell` runs after the writer. Static and behavior verification
-always run; behavior must prove page consumption, not merely handler unit tests.
+Deterministic risk (no model); high-risk beats small; supervised never small. Small may drop first design gate + plan-revision; contract shell retargets to `frontend-plan-pi`. Capability seed injects adapters; openSpec/task sources outrank. A11y: static/component tools only when present; Browser a11y always not-run.

package/skills/frontend-verification/SKILL.md

@@ -4,7 +4,7 @@ description: Use to assess frontend evidence and produce closeout.
 references:
   - path: references/verification-checklist.md
     required: true
-    maxChars: 2800
+    maxChars: 3000
 ---
 
 # Frontend Verification

package/skills/grill-with-docs/SKILL.md

@@ -26,7 +26,7 @@ Most repos have a single context:
 ```
 /
 ├── CONTEXT.md
-├── docs/
+├── ai_workspace/loop-agent/
 │   └── adr/
 │       ├── 0001-event-sourced-orders.md
 │       └── 0002-postgres-for-write-model.md
@@ -38,18 +38,18 @@ If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The ma
 ```
 /
 ├── CONTEXT-MAP.md
-├── docs/
+├── ai_workspace/loop-agent/
 │   └── adr/                          ← system-wide decisions
 ├── src/
 │   ├── ordering/
 │   │   ├── CONTEXT.md
-│   │   └── docs/adr/                 ← context-specific decisions
+│   │   └── ai_workspace/loop-agent/adr/                 ← context-specific decisions
 │   └── billing/
 │       ├── CONTEXT.md
-│       └── docs/adr/
+│       └── ai_workspace/loop-agent/adr/
 ```
 
-Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `ai_workspace/loop-agent/adr/` exists, create it when the first ADR is needed.
 
 ## During the session
 

package/skills/grill-with-docs/adr-format.md

@@ -1,8 +1,8 @@
 # ADR Format
 
-ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+ADRs live in `ai_workspace/loop-agent/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
 
-Create the `docs/adr/` directory lazily — only when the first ADR is needed.
+Create the `ai_workspace/loop-agent/adr/` directory lazily — only when the first ADR is needed.
 
 ## Template
 
@@ -24,7 +24,7 @@ Only include these when they add genuine value. Most ADRs won't need them.
 
 ## Numbering
 
-Scan `docs/adr/` for the highest existing number and increment by one.
+Scan `ai_workspace/loop-agent/adr/` for the highest existing number and increment by one.
 
 ## When to offer an ADR
 

package/skills/init-capability-evolution/SKILL.md

@@ -14,12 +14,12 @@ description: 用于 loop-agent 本仓库的初始化能力演化审查，判断
 - 新能力是否应该进入目标项目。
 - 新增/修改的 skill 是否应随 npm 包和 `init --profile full` 投影。
 - 目标项目的 `AGENTS.md`、README managed block、治理 docs、scripts 或 templates 是否需要更新。
-- `package.json files` 与 `docs/init-surface.manifest.json` 是否仍覆盖真实发布范围。
+- `package.json files` 与 `ai_workspace/loop-agent/init-surface.manifest.json` 是否仍覆盖真实发布范围。
 - 是否需要目标项目 smoke、init doctor、docs audit 或 package dry-run 证据。
 
 ## Trigger Tiers
 
-按 `docs/init-surface.manifest.json` 的 `evolutionReview.tiers` 判断成本：
+按 `ai_workspace/loop-agent/init-surface.manifest.json` 的 `evolutionReview.tiers` 判断成本：
 
 - `advisory`：只记录提示，不阻塞。
 - `surface-check`：运行 `bash scripts/check-init-surface.sh`；通过即可。
@@ -32,11 +32,11 @@ description: 用于 loop-agent 本仓库的初始化能力演化审查，判断
 审查时逐条回答：
 
 1. 本次变更会改变目标项目执行 `loop-agent init --profile full --merge` 后得到的文件、规则或能力吗？
-2. 是否新增、删除或重命名了 `skills/**`，并且目标项目需要 repo-local 可审计副本？
+2. 是否新增、删除或重命名了 `.agents/skills/**`，并且目标项目需要 repo-local 可审计副本？
 3. 是否改变了默认 DAG role skills、skill resolution、strict skill audit 或 task prompt 注入？
 4. 是否新增通用治理模板、script matrix、production readiness 或 operator recovery 文档，需要目标项目初始化后可见？
 5. `package.json files` 是否包含所有 npm 运行和初始化所需静态资料？
-6. `docs/init-surface.manifest.json` 是否更新了 package / init / exclude / trigger contract？
+6. `ai_workspace/loop-agent/init-surface.manifest.json` 是否更新了 package / init / exclude / trigger contract？
 7. 旧目标项目是否只需 advisory、需要手工复制新增文件，还是需要未来 `init audit/update` 迁移能力？
 
 ## Output
@@ -44,7 +44,7 @@ description: 用于 loop-agent 本仓库的初始化能力演化审查，判断
 轻量审查可以只在 handoff 中说明。高影响审查应写入：
 
 ```text
-docs/reports/YYYY-MM-DD-init-evolution-review.md
+ai_workspace/loop-agent/reports/YYYY-MM-DD-init-evolution-review.md
 ```
 
 报告保持短小，包含：

package/skills/loop-agent/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: loop-agent
 description: >-
-  Use when implementing features, processing PRDs or requirements, running structured loop-agent workflows, creating harness tasks, using Agent DAG, run-dag, pi-prompt planning/review, cursor-prompt one-shot sidecar intervention, or converging website/governance docs after user-visible changes in loop-agent. Triggers: loop-agent, workflow, structured development, harness task, Agent DAG, docs converge, Converge Docs, 文档收敛, 结构化开发, 工作流, 需求实现, PRD 实现.
+  Use when implementing features, processing PRDs or requirements, running structured loop-agent workflows, creating harness tasks, using Agent DAG, run-dag, pi-prompt planning/review, cursor-prompt one-shot sidecar intervention, initializing a target project with loop-agent, checking init update status, applying a safe init update, or converging website/governance docs after user-visible changes in loop-agent. Triggers: loop-agent, workflow, structured development, harness task, Agent DAG, docs converge, Converge Docs, 文档收敛, 结构化开发, 工作流, 需求实现, PRD 实现, 初始化 loop-agent, loop agent 初始化, loop agent初始化, loop-agent 初始化, 初始化更新校验, loop agent初始化更新校验, 检查初始化更新, 初始化安全更新, loop agent初始化安全更新, 应用初始化更新.
 references:
   - path: references/harness-policy.md
     required: true
@@ -19,7 +19,7 @@ references:
 
 ## Canonical Harness Policy
 
-Shared loop-agent harness workflow 规则见 `references/harness-policy.md`。Repo-local `docs/loop-agent-harness.md` / `specs/loop-agent-harness.md` 应保持为 local runtime path、governance root、verification commands 的 thin adapters。
+Shared loop-agent harness workflow 规则见 `references/harness-policy.md`。Repo-local `ai_workspace/loop-agent/loop-agent-harness.md` / `specs/loop-agent-harness.md` 应保持为 local runtime path、governance root、verification commands 的 thin adapters。
 
 ## 默认立场
 
@@ -29,7 +29,7 @@ Shared loop-agent harness workflow 规则见 `references/harness-policy.md`。Re
 - `pi-prompt` 与 `cursor-prompt` 都是一次性 full-capability helper；用作 sidecar 时必须在 prompt 和 tool/model 参数里显式收窄。
 - Cursor 仅是显式、手工触发的 `cursor-prompt` one-shot sidecar，不是受治理 DAG/Loop writer；受治理写入固定为 `implement-pi` / `repair-pi`，必须给出 allowed / forbidden paths 与 writeSet。
 - Shell verification 是事实源；任何完成声明都必须有本轮命令输出。
-- 长期结论写回 `docs/exec-plans/`、`docs/reports/`、`docs/progress/` 或 `./skill/`。
+- 长期结论写回 `ai_workspace/loop-agent/exec-plans/`、`ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/progress/` 或 `./skill/`。
 
 ## 唯一推荐执行路径
 
@@ -70,7 +70,7 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
 
 需要写代码时，默认使用 DAG `pi` executor 的 write tool profile（`implement-pi` / `repair-pi`）。Pi writer 节点必须包含 task id、目标、allowed paths、forbidden paths、writeSet、硬约束和预期验证，并在执行后由主会话独立运行 shell verification。
 
-`cursor-prompt` 仅作人工 one-shot sidecar intervention，不进入 Loop auto-execute / Delegate auto-run / DAG writer 选择。细节见 `docs/cursor-prompt-sidecar.md`、`references/harness-policy.md` 和 `references/verification-and-failure-handling.md`。
+`cursor-prompt` 仅作人工 one-shot sidecar intervention，不进入 Loop auto-execute / Delegate auto-run / DAG writer 选择。细节见 `ai_workspace/loop-agent/cursor-prompt-sidecar.md`、`references/harness-policy.md` 和 `references/verification-and-failure-handling.md`。
 
 Pi writer prompt（以及可选 sidecar prompt）都必须包含：
 
@@ -92,7 +92,7 @@ bounded writer 完成后，主会话必须独立复核；命令清单见 `refere
 |---|---|
 | Long-Running Loop（`loop` init/status/run/record-round/add-signal/closeout、auto mode、signals） | `references/long-running-loop.md` |
 | Three-Pass Convergence、repair artifact、spine audit、knowledge curate、SePO-lite prompt evolution | `references/harness-policy.md` |
-| Operator commands（status/doctor/report/closeout/promote/inspect/spine/knowledge/docs/handoff） | `references/command-reference.md` |
+| Operator commands（status/doctor/report/closeout/promote/inspect/spine/knowledge/ai_workspace/loop-agent/handoff） | `references/command-reference.md` |
 | 伴生 CLI `agent-worker`（TaskSpec / Task Pool / batch / morning report） | `references/command-reference.md` |
 | Post-writer 独立验证、verify knobs、failure handling、closeout | `references/verification-and-failure-handling.md` |
 | Docs Converge（用户可见变更后的站上/治理文档同步检查表） | `references/docs-converge.md` |

package/skills/loop-agent/references/README.md

@@ -9,7 +9,7 @@ failure handling 与 workflow 细节放在这里，避免主 skill 变成百科
 1. 先读 `../SKILL.md`，确认当前任务是否真的需要 `loop-agent`。
 2. 根据任务类型只打开相关 reference，不要一次加载整个目录。
 3. 执行时遵循 Agent DAG 路径；历史顺序式 `run ...` workflow 已移除。
-4. 如果 reference 与 `harness.json` 或 repo-local `docs/loop-agent-harness.md` / `specs/loop-agent-harness.md` 冲突，以
+4. 如果 reference 与 `harness.json` 或 repo-local `ai_workspace/loop-agent/loop-agent-harness.md` / `specs/loop-agent-harness.md` 冲突，以
    `harness.json` 的机器可读 policy 和本目录的 shared policy 为准，并回头修正文档漂移。
 
 ## 快速路由
@@ -51,7 +51,7 @@ failure handling 与 workflow 细节放在这里，避免主 skill 变成百科
 
 - `references/harness-policy.md` 是 shared workflow policy source，供多个 repo 的 thin adapter docs 引用。
 - `../SKILL.md` 是 skill trigger 与 routing source，不承载长流程细节。
-- `docs/loop-agent-harness.md` / repo-local `specs/loop-agent-harness.md` 是本仓库或目标仓库的 adapter 文档：只描述 runtime 位置、governance root、验证入口和本地边界。
+- `ai_workspace/loop-agent/loop-agent-harness.md` / repo-local `specs/loop-agent-harness.md` 是本仓库或目标仓库的 adapter 文档：只描述 runtime 位置、governance root、验证入口和本地边界。
 - `harness.json` 是 workflowPolicy、script entrypoints、artifacts 目录与 model routing 的机器可读 source of truth。
 - `.harness/tasks/<task-id>/` 是 task 运行态状态；不要把运行态事实写进本目录。
 - `.harness/runs/completed/<run-id>/` 是 one-shot tool run evidence；reference 文档只能解释如何读取和 promotion，不应复制 run facts。
@@ -64,4 +64,4 @@ failure handling 与 workflow 细节放在这里，避免主 skill 变成百科
 - 新 reference 应有清晰标题、触发场景、最小步骤、失败处理和维护边界。
 - 如果某个 reference 变成可独立触发、跨项目通用且不再依赖本仓库上下文，再考虑拆成独立 skill。
 - 更新 command、workflow policy 或 verification 规则时，同步核对 `harness.json`、`references/harness-policy.md`、repo-local harness adapter docs 和 verification matrix。
-- `~/.pi/agent/skills/loop-agent` 是指向本目录的 symlink，所以仓库内 edits 会直接更新 Pi skill。
+- `~/.pi/agent/.agents/skills/loop-agent` 是指向本目录的 symlink，所以仓库内 edits 会直接更新 Pi skill。

package/skills/loop-agent/references/command-reference.md

@@ -25,7 +25,7 @@ loop-agent doctor
 
 发布包入口加载 `dist/cli.js`；开发入口加载 `src/cli.ts`。
 
-发布包携带静态能力资料：`skills/`、`docs/*.md`、`docs/templates/` 和 `examples/`。`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 的任务正文属于目标仓库运行中生成的事实，不从 npm 包复制；包内只保留这些目录的 README 说明。
+发布包携带静态能力资料：`.agents/skills/`、`ai_workspace/loop-agent/*.md`、`ai_workspace/loop-agent/templates/` 和 `examples/`。`ai_workspace/loop-agent/progress/`、`ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/exec-plans/`、`ai_workspace/loop-agent/decisions/` 的任务正文属于目标仓库运行中生成的事实，不从 npm 包复制；包内只保留这些目录的 README 说明。
 
 ## 命令参考
 
@@ -61,7 +61,7 @@ loop-agent doctor
    loop-agent promote-run <task-id> --run-id <run-id>
    loop-agent closeout task <task-id>
    loop-agent spine audit <task-id> --markdown
-   loop-agent knowledge curate --markdown --output docs/reports/<task-id>-learned-proposal.md
+   loop-agent knowledge curate --markdown --output ai_workspace/loop-agent/reports/<task-id>-learned-proposal.md
    loop-agent loop-benchmark --markdown
    ```
 3. **Escape hatch**，仅用于 worktree 隔离委派、executor 调试或 one-shot 诊断：
@@ -100,6 +100,15 @@ export CODE_AGENT_PI_BACKEND=cli-only    # 紧急回滚：纯 CLI 路径
 SDK 回归或 SDK 可选依赖不可用时用 `cli-only` 诊断。CLI fallback 路径须与现有 workflow 行为兼容。
 
 ### 初始化与旧项目更新
+
+用户中文表达到命令的映射（与目标项目 `AGENTS.md` 的“自然语言入口路由”保持一致）：
+
+| 用户表达 | 命令 |
+|---|---|
+| loop-agent 初始化 / loop agent 初始化 / loop agent初始化 / 初始化 loop-agent | 先运行 `loop-agent init instructions --repo-root .`，再运行 `loop-agent init --repo-root . --profile full --merge`，随后补全 README/验证矩阵并复查 doctor/inspect/docs audit |
+| 初始化更新校验 / loop agent初始化更新校验 / 检查初始化更新 | `loop-agent init check-update --repo-root . --markdown`（只读，不得隐含 `apply-safe`） |
+| 初始化安全更新 / loop agent初始化安全更新 / 应用初始化更新 | 先 `loop-agent init check-update --repo-root . --markdown`，再 `loop-agent init update --repo-root . --apply-safe`（surface 缺失时先 `--bootstrap-surface`；human decisions 存在时停下等用户） |
+
 ```bash
 loop-agent init instructions --repo-root <target-repo>
 loop-agent init --repo-root <target-repo> --profile full --merge
@@ -132,7 +141,7 @@ loop-agent new-task <task-id> "Task Title"
 
 ### 导入原始 PRD（不可变事实源）
 ```bash
-loop-agent import-prd <task-id> --file docs/path/to-prd.md [--name requirement] [--json]
+loop-agent import-prd <task-id> --file ai_workspace/loop-agent/path/to-prd.md [--name requirement] [--json]
 ```
 
 把用户原始 PRD **原样复制** 到 `.harness/tasks/<task-id>/source/references/`，并写入 `source/source-manifest.json`（含 SHA-256）与 `task.json.referenceDocs`。此步骤不调用模型、不改写内容。随后再写派生的 `source/需求.md` 执行契约；冲突时以 `source/references/*` 为准。
@@ -155,7 +164,7 @@ loop-agent promote-run <task-id> --run-id <run-id>
 loop-agent closeout task <task-id>
 ```
 
-`promote-run` 从 completed DAG facts 或 one-shot completed run evidence 生成 task `修改记录.md` / `验证结果.md`，不调用 LLM、不修改 completed run facts。`closeout task` 从 task artifacts 生成 `docs/progress/YYYY-MM-DD-<slug>.md`，验证证据不足时必须写明剩余风险。
+`promote-run` 从 completed DAG facts 或 one-shot completed run evidence 生成 task `修改记录.md` / `验证结果.md`，不调用 LLM、不修改 completed run facts。`closeout task` 从 task artifacts 生成 `ai_workspace/loop-agent/progress/YYYY-MM-DD-<slug>.md`，验证证据不足时必须写明剩余风险。
 
 one-shot run evidence 位于 `.harness/runs/{active,completed,failed}/<run-id>/`。`cursor-prompt` 与 Pi `cursor` tool 会创建这类 run evidence；当前 `pi-prompt` 不创建 `.harness/runs/`。active 目录只应保留 live one-shot run，残留或 `.DS_Store` 等系统文件应清理。详见 `one-shot-runs.md`。
 
@@ -231,8 +240,8 @@ loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-models # 非 c
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance # governance warning 时失败
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-skills # missing/error/truncated skill 或 unresolved reference 时失败
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance --spine-task <task-id> # 同时消费 minimal spec spine audit
-loop-agent dag validate --dag docs/templates/agent-dag.supervised-implementation.json --strict-models --strict-governance  # role=supervisor + write-set-gate topology
-cp docs/templates/agent-dag.supervised-implementation.json <temp-dir>/supervised-dag.json
+loop-agent dag validate --dag ai_workspace/loop-agent/templates/agent-dag.supervised-implementation.json --strict-models --strict-governance  # role=supervisor + write-set-gate topology
+cp ai_workspace/loop-agent/templates/agent-dag.supervised-implementation.json <temp-dir>/supervised-dag.json
 (npx vitest run test/dag-supervised-template.test.ts test/dag-validate.test.ts test/dag-shell-executor.test.ts --reporter=dot)  # supervised template + shell.verdictGate runtime
 loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root>          # 执行 Agent DAG
 loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <temp-dir>/hybrid-dag.canvas.tsx # 可选 derived Canvas view
@@ -250,7 +259,7 @@ loop-agent dag run-task <task-id> --execute --cwd <repo-root>  # generate + vali
 loop-agent dag run-task <task-id> --dry-run --cwd <repo-root>  # generate + validate + active dry-run snapshot
 loop-agent dag status --run-id <run-id>                  # 单次 run JSON 摘要（approvalFlow, healthIssues）
 loop-agent dag doctor                                    # 扫描 active/paused/completed runs；advisoryOnly health report
-loop-agent dag report [--run-id <run-id>] [--lifecycle active|paused|completed|all] [--json|--markdown] [--failed-only] [--latest] [--paused-latest] [--action <recovery-action>]  # derived per-node 聚合（只读）；JSON 锁定于 docs/templates/agent-dag-report.schema.json；--paused-latest 聚焦最新 paused run；playbook: docs/agent-dag-recovery-playbook.md
+loop-agent dag report [--run-id <run-id>] [--lifecycle active|paused|completed|all] [--json|--markdown] [--failed-only] [--latest] [--paused-latest] [--action <recovery-action>]  # derived per-node 聚合（只读）；JSON 锁定于 ai_workspace/loop-agent/templates/agent-dag-report.schema.json；--paused-latest 聚焦最新 paused run；playbook: ai_workspace/loop-agent/agent-dag-recovery-playbook.md
 loop-agent dag reconcile-run --run-id <run-id>            # 只读检查 effectiveStatus 与恢复/收口资格
 loop-agent dag reconcile-run --run-id <run-id> --action supersede --reason "..." # 显式保留证据并标记为任务已另行完成
 loop-agent dag reconcile-run --run-id <run-id> --action abandon --reason "..."   # 显式保留证据并收口为已放弃
@@ -270,16 +279,16 @@ loop-agent dag resume --run-id <run-id>                  # approve 后继续
 - `dag validate` 做 schema/topology/ranks 检查；审 `warnings` 中的显式 `executorModels` drift 与 governance lint。
 - 手写临时 DAG spec 执行前用 `dag validate --strict-models`，model-matrix drift 应 fail fast。
 - read-only artifact-boundary 或 DAG 内 shell governance warning 应 fail fast 时用 `dag validate --strict-governance`。
-- 人工 handoff 视图用 `dag report --markdown`（summary、node timeline、failures、四段 Recovery Plan、artifacts、建议 next action）。仅 derived、advisory；需保存时重定向到平台临时目录或 `docs/reports/`。
+- 人工 handoff 视图用 `dag report --markdown`（summary、node timeline、failures、四段 Recovery Plan、artifacts、建议 next action）。仅 derived、advisory；需保存时重定向到平台临时目录或 `ai_workspace/loop-agent/reports/`。
 - operator 聚焦最新 paused run 用 `dag report --paused-latest`（等同 `--lifecycle paused --latest`；勿与显式 `--lifecycle` 并用）。
-- 需 operator 关注的 run 用 `dag report --failed-only`、`--latest`、`--action <recovery-action>` 收窄。category→action 映射见 `docs/agent-dag-recovery-playbook.md`。
+- 需 operator 关注的 run 用 `dag report --failed-only`、`--latest`、`--action <recovery-action>` 收窄。category→action 映射见 `ai_workspace/loop-agent/agent-dag-recovery-playbook.md`。
 - 只读扫描 `.harness/dag-runs/` 下所有 run 的生命周期 health issue 与建议 action 用 `dag doctor`（`advisoryOnly: true`；不 mutate facts）。
 - approve/resume 前用 `dag status --run-id <id>` 看单次 lifecycle、`approvalFlow`、`hasHumanApproval`。
 - lifecycle、raw status 与 liveness 冲突时先用 `dag reconcile-run --run-id <id>` 只读检查。只有 runner 已证明停止且 operator 明确给出 `supersede|abandon` 与 reason 时才允许收口；它保存原始 state，不把未执行节点标成成功。
 - task status、source/artifacts、DAG outcome、verification 记录可能 drift 时用 `dag reconcile-tasks --glob '<pattern>'`。默认仅报告；`--patch` 显式且不能伪造 verification evidence。
 - 大型 PRD closeout 用 `dag final-verification <task-id>` 生成确定性 DAG，final verification 在 closeout artifact 创建之后。
 - 从 run facts dry-run envelope 解析用 `dag decision inspect|validate`；`validate` 在无效 envelope 时 exit 1；永不自动 resume/retry。
-- Decision Gate prompt 可用 `buildDagDecisionGateEvidence()`（`src/workflows/dag/decision-evidence.ts`）做与 `dag report --json`、`docs/templates/agent-dag-report.schema.json` 对齐的只读摘要；不 mutate run state，不执行 retry/resume。
+- Decision Gate prompt 可用 `buildDagDecisionGateEvidence()`（`src/workflows/dag/decision-evidence.ts`）做与 `dag report --json`、`ai_workspace/loop-agent/templates/agent-dag-report.schema.json` 对齐的只读摘要；不 mutate run state，不执行 retry/resume。
 - 仅当有意在 `.harness/dag-runs/active/` 下要 active run snapshot 时用 `run-dag --dry-run`。
 - task source 应从 `harness.json.workflowPolicy.dag.profileRouting` 与确定性 candidate `governanceProfile` 选择通用候选模板时用 `dag run-task --profile auto`。无 `--profile` 仅用于旧 standard-compatible 输出；`--profile minimal|standard|reviewed|supervised` 选择治理路由，其中 supervised 模板不会被自动前端分类替换。
 - 默认 `standard` 任务会根据标题、`source/需求.md` 和结构化 `allowedPaths` 做保守、确定性的需求分类。只有高置信的前端实现需求自动选择 `frontend-implementation`；后端、前后端混合、明确排除前端或无法可靠判断的需求保留 governance profile 选出的模板，绝不自动进入 `backend-test`。显式 profile、`workflowPolicy` 或 supervised quality gate 已选中 supervised 时，自动分类不得降低治理等级。
@@ -300,7 +309,7 @@ loop-agent workflow replay <run-id>
 
 ### Cursor sidecar
 
-`cursor-worker` 已删除。人工干预使用 `cursor-prompt` one-shot sidecar；见 `docs/cursor-prompt-sidecar.md`。
+`cursor-worker` 已删除。人工干预使用 `cursor-prompt` one-shot sidecar；见 `ai_workspace/loop-agent/cursor-prompt-sidecar.md`。
 
 ### Eval Replay（M1，只读 completed evidence）
 
@@ -354,7 +363,7 @@ loop-agent status <task-id>
 ### Docs governance helpers
 ```bash
 loop-agent docs audit
-loop-agent docs archive docs/exec-plans/active/<plan>.md
+loop-agent docs archive ai_workspace/loop-agent/exec-plans/active/<plan>.md
 loop-agent plan list
 loop-agent plan create <plan-id> "<title>"
 loop-agent plan complete <plan-id> --summary "<summary>"
@@ -375,11 +384,11 @@ loop-agent handoff coverage <task-id> [--json|--markdown]
 ### Pi runtime reuse benchmark / decision（无 live call）
 ```bash
 loop-agent pi-reuse-benchmark \
-  --report docs/reports/<benchmark-report>.md \
+  --report ai_workspace/loop-agent/reports/<benchmark-report>.md \
   --json
 
 loop-agent pi-reuse-benchmark \
-  --report docs/reports/<benchmark-report>.md \
+  --report ai_workspace/loop-agent/reports/<benchmark-report>.md \
   --off-executor /path/to/off/executor.jsonl \
   --on-executor /path/to/on/executor.jsonl \
   --approval /path/to/approval.json \
@@ -391,7 +400,7 @@ loop-agent pi-reuse-benchmark \
 ### Loop convergence benchmark baseline（无 live call）
 ```bash
 loop-agent loop-benchmark --markdown
-loop-agent loop-benchmark --markdown --output docs/reports/2026-06-30-loop-agent-loop-benchmark.md
+loop-agent loop-benchmark --markdown --output ai_workspace/loop-agent/reports/2026-06-30-loop-agent-loop-benchmark.md
 ```
 
 生成 M0 deterministic baseline，对照 `single-repair`、`3-pass-convergence`、`3-pass-convergence+quota`。**不**跑 live Pi/Cursor call、不创建 task、不改 `convergence.enabled` 默认值。live dogfood 证据缺失时输出 `blocked` 并建议保持 opt-in。
@@ -422,11 +431,24 @@ loop-agent spine audit <task-id> --markdown
 ### Knowledge curator proposal
 ```bash
 loop-agent knowledge curate --markdown
-loop-agent knowledge curate --markdown --output docs/reports/<task-id>-learned-proposal.md
+loop-agent knowledge curate --markdown --output ai_workspace/loop-agent/reports/<task-id>-learned-proposal.md
 ```
 
 读取 `.harness/knowledge/patterns.jsonl` 中 completed convergence repair pattern，按 `failureClass + fixScope shape + invariant` 去重，生成 human-gated learned guidance proposal。命令只生成 proposal，不直接修改 `./skill/references/learned/*.md`；输出会先通过 skill safety audit。
 
+### Knowledge graph / query CLI
+```bash
+loop-agent knowledge graph-init --product-name <name>
+loop-agent knowledge graph-materialize
+loop-agent knowledge graph-promote
+loop-agent knowledge graph-incremental-prepare --feature F-2026-004 --service <service>
+loop-agent knowledge query --mode by_feature --feature F-2026-004 --json
+loop-agent knowledge query --mode by_id --id SVC-order --json
+loop-agent knowledge query --mode search --text "keyword" --json
+```
+
+这些子命令是 package-backed 公共入口，封装包内 knowledge runtime 资产。目标项目应使用 `loop-agent knowledge ...`，不要要求仓库内直接运行未投影的 package-only kb runtime scripts。Feature 测试知识日常写回用 `task.json.taskKind = "knowledge-sync"`（必须绑定 `featureId`）；业务图谱开荒/增量用 `taskKind = "knowledge-graph-bootstrap"`。
+
 ### Worker TaskSpec pipeline（伴生 CLI `agent-worker`）
 
 `agent-worker` 是与 `loop-agent` 一起发布的独立 CLI（`bin/agent-worker.js -> dist/worker/cli.js`），面向“产品线 Worker”场景：把一批 TaskSpec 规约成可校验、可串行调度、可晨报的流水线。它不进入 `loop-agent` 命令树，也不自带 executor——执行权全部通过子进程委托给已发布的 `loop-agent` CLI（最终是 DAG runtime + shell verification）。
@@ -491,7 +513,7 @@ loop-agent harvest <task-id> [--squash] [--no-archive] [--keep-worktree]
 loop-agent worktree create|list|remove ...
 ```
 
-用于 worktree 隔离以及可选的 Pi-only DAG 执行与 merge 收口。常规 autonomous work 应优先 Agent DAG；详见 `multi-worktree.md` 与 `docs/cursor-prompt-sidecar.md`。
+用于 worktree 隔离以及可选的 Pi-only DAG 执行与 merge 收口。常规 autonomous work 应优先 Agent DAG；详见 `multi-worktree.md` 与 `ai_workspace/loop-agent/cursor-prompt-sidecar.md`。
 
 ### One-shot Cursor sidecar（escape hatch）
 ```bash

package/skills/loop-agent/references/docs-converge.md

@@ -3,7 +3,7 @@
 本 reference 把会话协议中的 **Converge Docs** 落成可执行检查表。
 定位是**收敛 / 同步**，不是「每次重新 invent 文档大纲」。
 
-权威规划：`docs/exec-plans/completed/2026-07-14-website-docs-ia-and-converge.md`。
+权威规划：`ai_workspace/loop-agent/exec-plans/completed/2026-07-14-website-docs-ia-and-converge.md`。
 站与治理双树边界：`website/README.md`。
 
 ## 何时触发
@@ -12,7 +12,7 @@
 
 - 用户可见行为变更（CLI 输出、默认工作流、init 投影、Observe/Worker 主路径）。
 - 新增 / 修改 / 删除 CLI 命令或关键 flags。
-- runtime / 架构边界变更（`docs/architecture/*`、executor 角色、Worker 边界）。
+- runtime / 架构边界变更（`ai_workspace/loop-agent/architecture/*`、executor 角色、Worker 边界）。
 - active plan 创建、blocked、完成或归档。
 - 准备发布或写 `CHANGELOG.md` 版本条目。
 - 用户明确要求「文档收敛」「docs converge」「同步 website docs」。
@@ -24,9 +24,9 @@
 
 | 受众 | 主要入口 | 权威细节 |
 | --- | --- | --- |
-| 新贡献者 | `website/docs/intro.md` → `overview/architecture` → `overview/roadmap` → first-run | 根 `docs/architecture/*`、active plans |
+| 新贡献者 | `website/docs/intro.md` → `overview/architecture` → `overview/roadmap` → first-run | 根 `ai_workspace/loop-agent/architecture/*`、active plans |
 | 使用者 | `overview/feature-map`、`quick-start/*`、`guides/*`、`reference/*` | CLI help、根 `CHANGELOG.md` |
-| 维护者 / agent | 本检查表 + `AGENTS.md` Converge Docs | `docs/`、`skills/`、`scripts/check-*.sh` |
+| 维护者 / agent | 本检查表 + `AGENTS.md` Converge Docs | `ai_workspace/loop-agent/`、`.agents/skills/`、`scripts/check-*.sh` |
 
 ## 页面清单（站上活文档）
 
@@ -34,7 +34,7 @@
 | --- | --- |
 | `website/docs/intro.md` | 概念地图 + 30 分钟路径；非能力堆砌 |
 | `website/docs/overview/feature-map.md` | 功能导览 → guide/CLI |
-| `website/docs/overview/architecture.md` | 架构导读；链到 `docs/architecture/` |
+| `website/docs/overview/architecture.md` | 架构导读；链到 `ai_workspace/loop-agent/architecture/` |
 | `website/docs/overview/roadmap.md` | 当前有效规划短索引 |
 | `website/docs/quick-start/*` | 安装 / init / first-run |
 | `website/docs/guides/*` | 主路径操作说明 |
@@ -50,26 +50,26 @@
 
 | 若变更了… | 必须检查 / 更新 |
 | --- | --- |
-| 新/改 CLI 命令 | `website/docs/reference/cli.md` + `skills/loop-agent/references/command-reference.md`（及 agent-worker 相关 reference） |
+| 新/改 CLI 命令 | `website/docs/reference/cli.md` + `.agents/skills/loop-agent/references/command-reference.md`（及 agent-worker 相关 reference） |
 | 用户可见行为 | 对应 `guides/*` 或 `quick-start/*`；根 `CHANGELOG.md`；必要时 `overview/feature-map.md` / `intro.md` |
-| runtime / 边界 | 根 `docs/architecture/*`；站上 `overview/architecture.md` 导语与外链 |
+| runtime / 边界 | 根 `ai_workspace/loop-agent/architecture/*`；站上 `overview/architecture.md` 导语与外链 |
 | 默认工作流 | `intro.md` 流程图 + `guides/agent-dag.md` / `guides/harness-policy.md` |
-| active plan 状态 | `overview/roadmap.md` 短索引 + `docs/exec-plans/active/README.md` |
+| active plan 状态 | `overview/roadmap.md` 短索引 + `ai_workspace/loop-agent/exec-plans/active/README.md` |
 | 发布 | 根 `CHANGELOG.md` 为版本事实源；`website/docs/changelog.md` 只写摘要与链接；roadmap 仅在规划状态变化时更新 |
-| skill / init 投影 | `docs/init-surface.manifest.json`、相关测试、必要时 `docs/skills/*` |
+| skill / init 投影 | `ai_workspace/loop-agent/init-surface.manifest.json`、相关测试、必要时 `ai_workspace/loop-agent/.agents/skills/*` |
 
 跨树链接规则：
 
 - 站内页面用 Docusaurus 相对文档链接。
-- 链到根目录 `docs/`、`AGENTS.md`、`CHANGELOG.md` 等时，使用
+- 链到根目录 `ai_workspace/loop-agent/`、`AGENTS.md`、`CHANGELOG.md` 等时，使用
   `https://github.com/tea-agent/loop-agent/blob/main/<repo-path>`，
-  正文同时写出 repo-relative path；禁止伪造站内 `/docs/architecture/...` 作为根目录文档路由。
+  正文同时写出 repo-relative path；禁止伪造站内 `/ai_workspace/loop-agent/architecture/...` 作为根目录文档路由。
 
 ## 执行步骤（最小闭环）
 
 1. **列出本轮用户可见 diff**（命令、行为、边界、计划状态）。
 2. **对照上表**产出缺口清单（页面路径 + 要改的一句话）。
-3. **最小补丁**：只改清单内页面；禁止顺手重写 practices 或迁移整个 `docs/`。
+3. **最小补丁**：只改清单内页面；禁止顺手重写 practices 或迁移整个 `ai_workspace/loop-agent/`。
 4. **验证**（见下节）。
 5. **Handoff** 二选一：
    - 已更新：列出改动页面与验证命令结果。
@@ -103,11 +103,11 @@ npx vitest run test/init-command.test.ts test/package-surface.test.ts
 ## 禁止事项
 
 - 每次会话从头撰写全新文档大纲或「重新规划整个 docs 树」。
-- 把 `docs/design/`、exec-plans、reports 全文复制进 `website/docs/`。
-- 在站上建立第二套与 `docs/architecture/*` 冲突的架构真源。
+- 把 `ai_workspace/loop-agent/design/`、exec-plans、reports 全文复制进 `website/docs/`。
+- 在站上建立第二套与 `ai_workspace/loop-agent/architecture/*` 冲突的架构真源。
 - 未读 `website/README.md` 与相关 exec-plan 就扩大 scope。
 - 用删测试、降 `onBrokenMarkdownLinks` 或忽略 `docs:build` 失败制造「完成」。
-- 新增独立公共 skill 目录承载本检查表（应留在 `skills/loop-agent/references/`）。
+- 新增独立公共 skill 目录承载本检查表（应留在 `.agents/skills/loop-agent/references/`）。
 
 ## 与现有能力的关系
 

package/skills/loop-agent/references/harness-policy.md

@@ -70,9 +70,9 @@ loop-agent run-dag \
 
 `loop-agent` is the preferred global CLI. For self-hosting loop-agent development, the controller must be an installed npm-published package. Use `npm install -g @tea-agent/loop-agent@latest` for first install or intentional upgrades, then treat the installed version as frozen for the current task and record `npm list -g @tea-agent/loop-agent --depth=0`. Do not repeatedly fetch `npx @latest` inside DAG nodes, and do not use the current working tree's `npm link` or `npm run dev` to control tasks that may edit CLI, DAG runtime, executors, package metadata, or build output. Use `npm run dev -- <args>` only for source debugging and focused CLI development.
 
-The npm package carries static capability assets: `skills/`, top-level governance docs, `docs/templates/`, `examples/`, `harness.json`, `AGENTS.md`, `README.md`, and `CHANGELOG.md`. Generated or historical task facts under `docs/progress/`, `docs/reports/`, `docs/exec-plans/`, and `docs/decisions/` belong to the target repository; package only their directory README files, not prior run content.
+The npm package carries static capability assets: `.agents/skills/`, top-level governance docs, `ai_workspace/loop-agent/templates/`, `examples/`, `harness.json`, `AGENTS.md`, `README.md`, and `CHANGELOG.md`. Generated or historical task facts under `ai_workspace/loop-agent/progress/`, `ai_workspace/loop-agent/reports/`, `ai_workspace/loop-agent/exec-plans/`, and `ai_workspace/loop-agent/decisions/` belong to the target repository; package only their directory README files, not prior run content.
 
-For arbitrary target repositories, DAG skill instructions must not depend on loop-agent source history being copied into the target repo. Resolve configured, user, or target-local skills when present, then fall back to package-bundled `skills/` as the stable default capability set.
+For arbitrary target repositories, DAG skill instructions must not depend on loop-agent source history being copied into the target repo. Resolve configured, user, or target-local skills when present, then fall back to package-bundled `.agents/skills/` as the stable default capability set.
 
 `<temp-dir>` means the platform-native temp directory. Use native paths for actual `--output`, `--dag`, and `--cwd` values on macOS and Windows; use `/` only for stable repo refs, JSON/Markdown evidence refs, and glob conventions.