@dawipong/opcflow 0.2.0 → 0.2.1

package/README.en.md

@@ -141,94 +141,30 @@ never silently deviate.
 > `docs/design/prototypes/<endpoint>/<module>/<page>.html` — once `scan` registers it, it goes through
 > the usual 👍 release. Both paths are equivalent in the system; both must pass a user 👍.
 
-## CLI Commands & Parameters
+## CLI Commands
 
-Every command: `opcflow <command> [args]` (after global install; or `npx -y @dawipong/opcflow <command>` without installing). Global `--project=<path>` sets the project
-root (otherwise it searches upward for `workbench.config.json`). File-path arguments are separated with
-`--` (e.g. `submit --actor=x -- <path>`).
+`opcflow <command> [args]` (after a global install; or `npx -y @dawipong/opcflow <command>` without installing). Approval actions (approve/reject) are human-only; the AI uses the MCP `wb_*` typed tools.
 
-**Tasks**
+**Each command's purpose, when to use it, and parameters are in [COMMANDS.en.md](COMMANDS.en.md).** At a glance:
 
-| Command | Purpose | Parameters |
-| --- | --- | --- |
-| `list` | list tasks | `--status` `--assignee` `--module` `--role` `--endpoint` `--type` `--stale=true` |
-| `show <id>` | task detail (events / outputs / stale) | `--json=true` |
-| `create` | create a task | required `--role` `--creator`; opt `--module` `--endpoint` `--page` `--type` `--assignee` `--content` |
-| `claim <id>` | claim (passes the gate, auto-snapshots deps) | `--assignee=<role>` |
-| `update <id>` | change status | `--status` `--operator`; `--force=true` bypasses the stale block (traced) |
-| `remove <id>` | delete a task | `--operator`; `--force=true` |
-| `record <id> "note"` | add a note | `--operator` |
-| `input <id> -- <path>` | declare a dependency read outside the gate | `--operator` |
-
-**Outputs**
-
-| Command | Purpose | Parameters |
-| --- | --- | --- |
-| `output -- <path>` | register an output (auto-links your claimed task) | required `--role` `--endpoint`; opt `--module` `--page` `--task` |
-| `artifacts` | list artifacts | `--module` `--endpoint` `--page` `--kind` |
-| `scan` | full scan & register (docs + codeRoots), derive DAG edges | `--actor` |
-| `move --from=<> --to=<>` | move an artifact (keeps id, keeps approval) | `--actor` |
-
-**Trust**
-
-| Command | Purpose | Parameters |
-| --- | --- | --- |
-| `submit -- <path>` | submit for review | `--actor` |
-| `approve -- <path>` | approve | `--actor`; `--trivial=true` for tweaks: re-bless downstream + close derived reviews |
-| `reject -- <path>` | reject | `--actor` `--reason` |
-| `feedback -- <path>` | feedback / 👍👎 (release prototype) | `--actor` `--verdict=+1\|-1`; opt `--comment` `--task` |
-| `dispute -- <path>` | trace an objection to approved content and stop for a ruling | `--actor` `--reason` |
-| `queue` | review queue (pending + invalidated) | — |
-| `sync` | reconcile: invalidation propagation + dispatch review | `--actor` |
-
-**Flow**
-
-| Command | Purpose | Parameters |
-| --- | --- | --- |
-| `plan` | dispatch downstream tasks once contracts are approved | `--module`; opt `--creator` |
-| `qa <id>` | record acceptance result (fail auto-dispatches rework) | `--result=pass\|fail` `--operator`; fail needs `--reason` |
-| `audit` | module contract reconciliation report (settlement status) | `--module` |
-| `graph` | emit a Mermaid dependency graph | `--module` |
-| `lint` | run protocol lints | opt `--role` `--endpoint` |
-| `events` | event stream | `--taskId`/`<id>` `--module` `--event` `--limit` `--json` |
-| `intake` | pull GitHub issues into the queue (standard lane / hotfix) | — |
-
-**Evolution / Maintenance**
-
-| Command | Purpose | Parameters |
-| --- | --- | --- |
-| `retro` | retrospective: skill candidates / Red Flags / approval throughput | opt `--module` `--json` |
-| `export` | export events/feedback as jsonl | — |
-| `init` | bootstrap a new project | `--endpoints` (required); `--platforms` `--model` `--writehooks=false` `--preset=false` `--hooks=false` |
-| `gen-agents` | regenerate agent definitions from templates | — |
-| `register-meta` | register meta artifacts (agent-def/skill/plan) | `--actor` |
-| `install-hooks` | install git hooks | — |
-| `migrate` | migrate a legacy DB | `--from=<path>` |
-
-> On the AI side, prefer the MCP `wb_*` typed tools (same source & transaction as the CLI). **approve/reject are deliberately not exposed to the AI — those are your actions.**
+- **Tasks** `list` · `show` · `create` · `claim` · `update` · `remove` · `record` · `input`
+- **Outputs** `output` · `artifacts` · `scan` · `move`
+- **Trust** `submit` · `approve` · `reject` · `feedback` · `dispute` · `queue` · `sync`
+- **Flow** `plan` · `qa` · `audit` · `graph` · `lint` · `events` · `intake`
+- **Evolution / Maintenance** `retro` · `export` · `init` · `gen-agents` · `register-meta` · `install-hooks` · `migrate`
+- **Service & Integration** `serve` · `mcp` · `hook` · `postcommit` (mostly auto-invoked by platform / git)
 
 ## Configuration (workbench.config.json)
 
+Generated by `init`, hand-edited afterwards — each project's coordinate system and discipline switches. **Every field's purpose, default, and when to tune it is in [CONFIG.en.md](CONFIG.en.md).**
+
 ```jsonc
 {
-  "platforms": ["claude", "cursor"],          // target platforms (picked by init), default ["claude"]
+  "platforms": ["claude", "cursor"],          // target platforms
   "endpoints": ["service", "web"],            // your endpoints
-  "pipeline": ["product-manager", "architect", "designer", "developer", "qa"], // role pipeline (excluded roles get no tasks)
-  "codeRoots": {                              // [required] code dir per endpoint, {module} placeholder
-    "service": ["service/src/modules/{module}"],
-    "web": ["web/src/pages/{module}"]
-  },
-  "moduleMapping": { "userProfile": "user" }, // merge fine modules into coarse ones
-  "machineChecks": { "enabled": false,        // run on developer complete
-    "service": ["cd service && npx tsc --noEmit"] },
-  "protocolLints": [                          // machine-checkable conventions → lints (violations block complete)
-    { "name": "no-page-size", "grep": "pageSize", "paths": ["service/src"] }
-  ],
-  "gates": {
-    "approvalMode": "warn",                   // warn = unreviewed only warns / enforce = blocks
-    "writeGate": "observe"                     // off / observe (log only) / enforce (block edits to approved contracts)
-  },
-  "git": { "taskTrailer": "off", "trailerKey": "Task" }  // on = inject a Task:#id attribution trailer on commit
+  "pipeline": ["product-manager", "architect", "designer", "developer", "qa"],
+  "codeRoots": { "service": ["service/src/modules/{module}"] },  // [required] code dir per endpoint, {module} placeholder
+  "gates": { "approvalMode": "warn", "writeGate": "observe" }    // approval / write-gate discipline levels
 }
 ```
 

package/README.md

@@ -129,93 +129,30 @@ flowchart LR
 > `docs/design/prototypes/<端>/<模块>/<页面>.html`,`scan` 登记后照常走 👍 放行——两条路径产出的原型
 > 在体系里等价,都要过用户 👍。
 
-## CLI 命令参数
+## CLI 命令
 
-所有命令:`opcflow <命令> [参数]`(全局装后即用;或 `npx -y @dawipong/opcflow <命令>` 免装)。全局 `--project=<路径>` 指定项目根(缺省向上找
-`workbench.config.json`)。文件路径参数用 `--` 分隔(如 `submit --actor=x -- <路径>`)。
+`opcflow <命令> [参数]`(全局装后即用;或 `npx -y @dawipong/opcflow <命令>` 免装)。审批类动作(approve/reject)只给人,AI 侧走 MCP 的 `wb_*` typed tools。
 
-**任务**
+**每条命令的作用、使用场景与参数见 [COMMANDS.md](COMMANDS.md)。** 速览:
 
-| 命令 | 作用 | 参数 |
-| --- | --- | --- |
-| `list` | 列任务 | `--status` `--assignee` `--module` `--role` `--endpoint` `--type` `--stale=true` |
-| `show <id>` | 任务详情(含事件/产出/stale) | `--json=true` |
-| `create` | 建任务 | 必填 `--role` `--creator`;选 `--module` `--endpoint` `--page` `--type` `--assignee` `--content` |
-| `claim <id>` | 领取(过 gate,自动快照依赖) | `--assignee=<角色>` |
-| `update <id>` | 改状态 | `--status` `--operator`;`--force=true` 越过 stale 拦截(留痕) |
-| `remove <id>` | 删任务 | `--operator`;`--force=true` |
-| `record <id> "备注"` | 加备注 | `--operator` |
-| `input <id> -- <路径>` | 补充申报 gate 之外读过的依赖 | `--operator` |
-
-**产出**
-
-| 命令 | 作用 | 参数 |
-| --- | --- | --- |
-| `output -- <路径>` | 登记产物(自动关联你领取的任务) | 必填 `--role` `--endpoint`;选 `--module` `--page` `--task` |
-| `artifacts` | 列产物 | `--module` `--endpoint` `--page` `--kind` |
-| `scan` | 全量扫描登记(docs + codeRoots),推导 DAG 边 | `--actor` |
-| `move --from=<> --to=<>` | 移动产物(保 id、不断审批) | `--actor` |
-
-**信任**
-
-| 命令 | 作用 | 参数 |
-| --- | --- | --- |
-| `submit -- <路径>` | 送审 | `--actor` |
-| `approve -- <路径>` | 批准 | `--actor`;`--trivial=true` 微调:re-bless 下游 + 关派生 review |
-| `reject -- <路径>` | 打回 | `--actor` `--reason` |
-| `feedback -- <路径>` | 反馈 / 👍👎(原型放行) | `--actor` `--verdict=+1\|-1`;选 `--comment` `--task` |
-| `dispute -- <路径>` | 对 approved 内容留痕异议,停下等裁决 | `--actor` `--reason` |
-| `queue` | 待审队列(pending + invalidated) | — |
-| `sync` | 对账:失效传播 + 沿图派 review | `--actor` |
-
-**流程**
-
-| 命令 | 作用 | 参数 |
-| --- | --- | --- |
-| `plan` | 契约全批后一键派发下游任务 | `--module`;选 `--creator` |
-| `qa <id>` | 记验收结果(fail 自动派 rework) | `--result=pass\|fail` `--operator`;fail 需 `--reason` |
-| `audit` | 模块契约对账报告(清算状态) | `--module` |
-| `graph` | 输出 Mermaid 依赖图 | `--module` |
-| `lint` | 跑协议 lint | 选 `--role` `--endpoint` |
-| `events` | 事件流 | `--taskId`/`<id>` `--module` `--event` `--limit` `--json` |
-| `intake` | 拉 GitHub issue 入队(标准道 / hotfix) | — |
-
-**进化 / 维护**
-
-| 命令 | 作用 | 参数 |
-| --- | --- | --- |
-| `retro` | 复盘:skill 候选 / Red Flag / 审批吞吐 | 选 `--module` `--json` |
-| `export` | 导出 events/feedback 为 jsonl | — |
-| `init` | 新项目引导 | `--endpoints`(必填);`--platforms` `--model` `--writehooks=false` `--preset=false` `--hooks=false` |
-| `gen-agents` | 从模板重生成 agent 定义 | — |
-| `register-meta` | 注册元产物(agent-def/skill/plan) | `--actor` |
-| `install-hooks` | 安装 git hooks | — |
-| `migrate` | 迁移旧库 | `--from=<路径>` |
-
-> AI 侧优先用 MCP 的 `wb_*` typed tools(与 CLI 同源同事务);**审批 approve/reject 刻意不暴露给 AI——那是你的动作**。
+- **任务** `list` · `show` · `create` · `claim` · `update` · `remove` · `record` · `input`
+- **产出** `output` · `artifacts` · `scan` · `move`
+- **信任** `submit` · `approve` · `reject` · `feedback` · `dispute` · `queue` · `sync`
+- **流程** `plan` · `qa` · `audit` · `graph` · `lint` · `events` · `intake`
+- **进化 / 维护** `retro` · `export` · `init` · `gen-agents` · `register-meta` · `install-hooks` · `migrate`
+- **服务与集成** `serve` · `mcp` · `hook` · `postcommit`(多由平台 / git 自动调用)
 
 ## 配置(workbench.config.json)
 
+`init` 生成、之后手工编辑,是每个项目的坐标系与纪律开关。**每个字段的作用、默认值与何时调,见 [CONFIG.md](CONFIG.md)。**
+
 ```jsonc
 {
-  "platforms": ["claude", "cursor"],          // 目标平台(init 选),缺省 ["claude"]
+  "platforms": ["claude", "cursor"],          // 目标平台
   "endpoints": ["service", "web"],            // 你的端
-  "pipeline": ["product-manager", "architect", "designer", "developer", "qa"], // 角色流水线(不含的角色不派任务)
-  "codeRoots": {                              // 【必填】每端代码目录,{module} 占位
-    "service": ["service/src/modules/{module}"],
-    "web": ["web/src/pages/{module}"]
-  },
-  "moduleMapping": { "userProfile": "user" }, // 细模块归并到粗模块
-  "machineChecks": { "enabled": false,        // developer complete 时跑
-    "service": ["cd service && npx tsc --noEmit"] },
-  "protocolLints": [                          // 能机器查的约定 → 降级为 lint(违例阻断 complete)
-    { "name": "no-page-size", "grep": "pageSize", "paths": ["service/src"] }
-  ],
-  "gates": {
-    "approvalMode": "warn",                   // warn=未批只警告 / enforce=阻断
-    "writeGate": "observe"                     // off / observe(只记录)/ enforce(拦改 approved 契约)
-  },
-  "git": { "taskTrailer": "off", "trailerKey": "Task" }  // on=提交注入 Task:#id 归因 trailer
+  "pipeline": ["product-manager", "architect", "designer", "developer", "qa"],
+  "codeRoots": { "service": ["service/src/modules/{module}"] },  // 【必填】每端代码目录,{module} 占位
+  "gates": { "approvalMode": "warn", "writeGate": "observe" }    // 审批 / 写门禁纪律档位
 }
 ```
 

package/dist/cli.mjs

@@ -2528,7 +2528,7 @@ function deriveEdges(ctx) {
   return created;
 }
 function scanArtifacts(ctx, actor = "system") {
-  const summary = { registered: 0, refreshed: 0, edges: 0, skipped: [] };
+  const summary = { registered: 0, refreshed: 0, remapped: 0, edges: 0, skipped: [] };
   const files = [];
   for (const dir of Object.values(ctx.config.docs)) {
     const abs = join10(ctx.root, dir);
@@ -2537,7 +2537,12 @@ function scanArtifacts(ctx, actor = "system") {
   for (const p of ["ARCHITECTURE.md", "TECH.md"]) {
     if (existsSync9(join10(ctx.root, p))) files.push(p);
   }
-  const exists = ctx.db.prepare("SELECT id, content_hash FROM artifacts WHERE path = ?");
+  const exists = ctx.db.prepare(
+    "SELECT id, kind, module, endpoint, page, content_hash FROM artifacts WHERE path = ?"
+  );
+  const remap = ctx.db.prepare(
+    "UPDATE artifacts SET kind = ?, module = ?, endpoint = ?, page = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?"
+  );
   const insert = ctx.db.prepare(
     "INSERT INTO artifacts (kind, module, endpoint, page, path, content_hash) VALUES (?, ?, ?, ?, ?, ?)"
   );
@@ -2547,6 +2552,27 @@ function scanArtifacts(ctx, actor = "system") {
       const before = row.content_hash;
       const after = refreshArtifact(ctx, { id: row.id }, actor);
       if (after.content_hash !== before) summary.refreshed++;
+      if (row.kind !== kind || row.module !== coords.module || row.endpoint !== coords.endpoint || row.page !== coords.page) {
+        const tx2 = ctx.db.transaction(() => {
+          remap.run(kind, coords.module, coords.endpoint, coords.page, row.id);
+          logEvent(ctx.db, {
+            entityType: "artifact",
+            entityId: row.id,
+            event: "coords_remapped",
+            actor,
+            payload: {
+              path: relPath,
+              from: { kind: row.kind, module: row.module, endpoint: row.endpoint, page: row.page },
+              to: { kind, module: coords.module, endpoint: coords.endpoint, page: coords.page }
+            },
+            module: coords.module,
+            endpoint: coords.endpoint,
+            page: coords.page
+          });
+        });
+        tx2();
+        summary.remapped++;
+      }
       return;
     }
     const hash = hashPath(join10(ctx.root, relPath));
@@ -4411,7 +4437,7 @@ async function runCommand(ctx, command, a) {
     }
     case "scan": {
       const s = scanArtifacts(ctx, a.actor || "system");
-      console.log(chalk.green(`\u2705 \u626B\u63CF\u5B8C\u6210:\u65B0\u767B\u8BB0 ${s.registered},\u5185\u5BB9\u5237\u65B0 ${s.refreshed},\u65B0\u589E\u8FB9 ${s.edges},\u6392\u9664\u5143\u4EA7\u7269 ${s.skipped.length}`));
+      console.log(chalk.green(`\u2705 \u626B\u63CF\u5B8C\u6210:\u65B0\u767B\u8BB0 ${s.registered},\u5185\u5BB9\u5237\u65B0 ${s.refreshed},\u91CD\u6302\u5750\u6807 ${s.remapped},\u65B0\u589E\u8FB9 ${s.edges},\u6392\u9664\u5143\u4EA7\u7269 ${s.skipped.length}`));
       break;
     }
     case "move": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dawipong/opcflow",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Spec-anchored, drift-enforced execution layer for AI coding agents — artifact DAG, trust gates, multi-role pipeline; generates agents/MCP/hooks for Claude Code, Codex, OpenCode & Cursor.",
   "license": "MIT",
   "author": "Dawi",