devcodex-workspace · diff

git:20260913.fd8c228 to git:20261023.601469d

18 added, 0 removed. Audit A to A.

---

name: devcodex-workspace

description: >

Use when cwd belongs to a DevCodex workspace, the user asks for DevCodex behavior,

OR the user message may match a workspace custom skill under .devcodex/workspace/skills

(short triggers like skill name/id, quoted phrases in skill description, e.g. test/测试).

Prefer workspace skill fixed behavior over connectivity/chat defaults.

---

# DevCodex Workspace Resolver

Grok **UserPromptSubmit** cannot inject model context (stdout ignored). Workspace custom skills are **not** native-scanned; DevCodex uses the same staged `skill_route` contract as the other hosts: build a bounded W + managed G catalog, commit at most one route, and load only the committed stage body. Stop reports workflow and wording gaps as advisory; it does not force repeated model turns. The plugin is user-global and does not own a workspace. Resolve the nearest `workspace-namespace` marker from cwd, keep task state under that workspace's `.devcodex`, and load shared instructions/Skills from user-global DevCodex surfaces plus the committed workspace skill. Full-evidence route: `devcodex grok`.

## Unified Workspace Skill Route（用户可见闭环）

1. Before treating a short user message as connectivity ping / Ready, use the bounded catalog supplied by the unified route; do not independently scan skill trees.

2. If a route is committed, load **only that one SKILL.md** through `skill_route` and obey it for the turn. Do not invent Ready/闲聊.

3. **Privacy / process UI**: **禁止**列出或扫描用户主目录下的宿主 skill 树，例如

`C:\Users\…\.grok\skills`、`~\.grok\bundled\skills`、`~\.claude\skills`、`~\.agents\skills`（L1）。

这些 List 会把 C 盘用户路径暴露在过程时间线里。全局 skill 只读

`~/.agents/devcodex/skills/<id>/SKILL.md` 单文件；工作区 skill 只读

`.devcodex/workspace/skills/<id>/SKILL.md`。

4. 过程文案用「正在加载 <id> 技能」，不要写「命中…正在读取并按该技能执行」。

5. CLI inventory verify: `devcodex skill resolve <id>`; route regression: `npm run test:skill-route`.

6. Do not claim UPS inject on Grok. Recover stale route metadata, preserve pending work and continue available actions.

## HostParity (vs Codex) — honesty contract

|------|-------|------------|----------------|

| **Full** | `devcodex grok` (official `--rules` kernel bind) | Controlling `AGENTS.md` in context; host-owned tool permissions; path-observable context and unified staged skill route; workflow/Stop diagnostics | UserPromptSubmit context inject; forced continuation from wording gaps; verified PC0 from Hook payload alone |

| **Partial** | plain `grok` in a child Git project | Best-effort Skill discovery + advisory plugin bridge when reachable | Full host parity with Codex; `kernelInjected=true` from passive Hook stdout |

+ | **Grok Bot driver** (Partial-like) | Grok Bot assistant with mounted `devcodex-profile`/`devcodex-memory` stdio connectors (`DEVCODEX_AGENT=grok-bot`) + `devcodex grok-bot` driver | Lifecycle events synthesized by the driver (`devcodex grok-bot turn-begin` / `observe-tool`); same ContextRead → `skill_route` → admission contract; PC5 reports this tier as `WARN` | Native hooks, context inject, enforced PreToolUse, Full; driver events as host-emitted evidence |

Platform facts (Grok Build hooks docs): `PreToolUse` and `Stop`/`SubagentStop` can hard-control; UserPromptSubmit is passive (no inject). PC5 must report `Partial` unless Full launcher evidence is present. Do not equate Grok with Codex UPS inject bootstrap.

1. Preserve the semantic intent seed before reading project context.

2. Bind the nearest valid `workspace-namespace` root from cwd. Do not require or create workspace `AGENTS.md`, `.agents`, `.grok`, `.codex`, `.claude`, `.gemini`, or `.github`.

3. Resolve the project namespace relative to that workspace and bind runtime state under `.devcodex/<project>/`.

4. Follow the kernel's intent-first route and read only selected files from the managed global runtime plus the resulting workspace Profile/context plan, and the single workspace skill committed by `skill_route`.

5. Use `~/.agents/devcodex/instructions.full.md` only for an explicit fallback; workspace `.devcodex` remains the sole workspace-owned DevCodex surface.

6. Before substantive output, satisfy **UserVisibleReplyLayoutV1** + **UserVisibleNoisePolicyV1** (six-host shared): emit plain-language PC0~PC10; show completion checks only when claiming completion. Runtime cannot inject on Grok; models still own S07.

7. Optional assist: call MCP `profile_compose_entry_check` for PC0~PC10; missing template/receipt details are repaired while continuing the original task.

8. Run `devcodex doctor` / `devcodex status` and read `hostParity` (`HostParityScorecardV1`): `full-capable` means hard path is ready; still use `devcodex grok` for Full session kernel evidence. `partial` lists **failedChecks** and **executable repairSteps** (commands); re-run doctor after each fix.

9. Execute **GrokTurnChecklist** every non-trivial turn (PF-165 + C16/PI-20260724-01): PC0~PC10 → Intent→Skill mandatory bundle → ContextReadPlan → **scan-hygiene** → **TTFV first delivery** → work/gates → report+memory → honest platform ceiling. Never skip S05/S07/C17 because inject is missing.

10. **Workspace skill trigger**: if user message matches a W skill, obey that skill before checklist bulk for chat-like turns.

+ ## Grok Bot (no native hooks)

+ Grok Bot has no lifecycle hooks, so the model drives them. The kernel's rules apply unchanged; this only adds the event plumbing.

+ **Session id (required for concurrent conversations).** Pick one id per Grok Bot conversation (`[A-Za-z0-9][A-Za-z0-9._-]{0,63}`, e.g. the conversation/agent id) and use it everywhere in that conversation: `--session-id <id>` on `turn-begin` and on every `observe-tool`, and `"hostSession": "<id>"` in the args of every connector call (the args file must be the exact args sent). Lifecycle, recovery, admission and route state live under `.memory/hooks/<project>/.sessions/<id>/`, so conversations on the same project never overwrite each other and a task admitted in one session can only be closed from that session. The connector rejects an invalid `hostSession` or a `contextBinding` minted for another session (`HOST_SESSION_INVALID`); the driver rejects a bracket whose args name another session or omit it (`GROK_BOT_HOST_SESSION_MISMATCH` / `GROK_BOT_HOST_SESSION_REQUIRED`). Without `--session-id` the shared default `grok-bot-session` is used (state stays at `.memory/hooks/<project>/`) — only safe when a single conversation is active.

+ 1. Once per user message, from the project dir: `devcodex grok-bot turn-begin <projectDir> "<message verbatim>"`. Keep `contextEpoch`, `turnBinding`, `skillRouteBootstrap`, `semanticDecisionSourceRef`. Never repeat it within the turn.

+ 2. Bracket **every** DevCodex connector call with the same id and args file:

+ `devcodex grok-bot observe-tool --project-dir <dir> --phase pre --tool devcodex-<profile|memory>__<tool> --tool-use-id <id> --args-file <f>`, then the call, then the same command with `--phase post --response-file <raw tool output file>` (the driver strips the host's untrusted-data fence). A skipped or duplicated bracket breaks the context binding (`scope-drift` / `receipt-status-stale`).

+ 3. Entry check first (S07): bracketed `profile_compose_entry_check` with `entry: { prompt, specRadar?, activeTask?, languageDecision? }`; emit the returned PC0~PC10 table verbatim (it renders in the prompt's language unless `languageDecision` says otherwise). PC5 shows the Grok Bot driver tier (`WARN`, never Full); PC6 shows observed Git state; PC4 is `PASS` in dev mode only when `specRadar` names the bound Skills/Profile.

+ 4. Read `turn-begin` `warnings` / `profileFreshness`: `PROFILE_TRUTH_DRIFT` or `PROFILE_POSSIBLY_STALE` means the Profile may not match the code; say so and refresh it when the turn depends on it.

+ 5. Then the kernel route: `profile_context_plan` (with `semanticDecision.sourceRef`) → `profile_load` (pass `files`) → required memory queries → `skill_route` catalog (paginate) + commit → `memory_task_admit_v2` (omit `ingressRef`; any `ingressWarnings` means a supplied ref was ignored).

+ 6. Closeout (S05): one bracketed `memory_turn_closeout_v1` call writes the optional report (new file under the task's `reports/`, same authority as the operational write lease), the session row and status, and the SUMMARY entry. Keep `sessionStatus: in-progress` until a formal task's terminal closeout. To close a formal task in the same call, add `terminal: {taskId, terminalStatus, ecr: {summary, checks: [{item, result}]}, completion: {items: [{item, status}]}}`. The server renders the ECR and the completion checklist from that real turn data under `<taskRoot>/evidence/closeout/`, cites the report and session-memory digests, reads the owner CAS state and runs the fenced `memory_task_terminal_v1` transition. `completed` still requires a verified CP1; otherwise use `cancelled`, `failed` or `rejected` honestly.

+ 7. S04 limit: Grok Bot edits files through its own shell/file tools, so DevCodex cannot see or block whole-file rewrites. S04 (incremental edits only) is not enforceable on this path and relies on model discipline; prefer targeted patch edits and never regenerate whole source/spec files.

+ 8. Prerequisites: `devcodex init` at the parent workspace (not inside a repo), `devcodex profile init` per project, connectors started after the workspace exists. Run the connectors and the driver from a clean runtime copy (default `/workspace/devcodex-runtime`), never from a development checkout; to pick up new DevCodex code run `scripts/grok-bot-runtime.sh update` then `scripts/grok-bot-runtime.sh restart`.

+ 9. Driver events are recorded with provenance `driver-synthesized-host-event` (accepted for the `grok-bot` host variant only), never as native `trusted-host-event`.

## GrokTurnChecklist + Intent→Skill bundle (PF-165)

| Step | Must do |

|------|---------|

| entry-pc0-pc10 | Full PC0~PC10 first; re-emit after compact/resume |

| intent-route | Final route before loading workflow Skills |

| skill-bundle | Non-chat mandatory: `intent` + `compliance` + `user-visible-output-contract` + workflow Skill + `report` + `memory` (minimal-sufficient; no full Skill encyclopedia preload) |

| context-plan | Bounded plan/receipts only |

| scan-hygiene | **WorkspaceRootScanHygiene**: prefer a bound project path and exclude `node_modules`/`dist`; Hook telemetry is advisory and the host owns permission |

| ttfv-first-delivery | **TimeToFirstValueGate**: same user-visible turn delivers scope card OR first findings/conclusion OR hard block (non-chat) |

| work-and-gates | CP/ECR as applicable |

| report-memory | Non-chat write report + memory |

| honest-ceiling | No inject / forced Stop loops / Grok===Codex claims; preserve pending facts and continue available work |

Machine source: `scripts/lib/host-parity-scorecard.js` (`GROK_TURN_EXECUTION_CHECKLIST`, `classifyWorkspaceRootScanSample`, `classifyTtfvOmissionSample`, `repairSteps`). Site doc: `public-site/docs/reference/hosts.md`.

The plugin is a discovery adapter, not a second rules source. Its passive Hook output must never be presented as kernel-injection evidence. Do not copy `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.agents`, `.github`, `.grok`, `.codex`, `.claude`, or `.gemini` into a workspace.