@aipper/aiws-spec 0.0.49 → 0.0.51

package/README.md

@@ -32,5 +32,8 @@ npx @aipper/aiws init .
 - `docs/workflow-delegation-contracts.schema.json`：delegation contract JSON 的结构约束
 - `docs/opencode-omo-adapter.md`：OpenCode + oh-my-opencode 的适配边界、角色映射与 fallback 约定
 - `docs/opencode-omo-validation-checklist.md`：OpenCode + oMo 的真实项目验收清单（探测、启用、损坏配置、fallback）
+- `docs/opencode-subagent-first.md`：OpenCode 宿主 subagent-first 执行契约（主会话协调、worker/reviewer、hatch）
+- `docs/pi-subagent-first.md`：Pi 宿主 subagent-first 执行契约（借力 `@tintinweb/pi-subagents`；AIWS force policy）
+- `docs/pi-plugins-manifest.md` / `docs/pi-plugins-manifest.json`：Pi 用户级插件清单（required / recommended / forbidden）与 `aiws doctor` 检测约定
 - `templates/workspace/.opencode/oh-my-opencode.json.example`：保守的项目级 oMo agent 建议配置（只覆盖 agents）
 - `docs/collaboration-artifacts.md`：`analysis/patches/review/evidence` 的协同工件目录与生命周期约定

package/docs/opencode-subagent-first.md

@@ -182,6 +182,12 @@ worker 返回 BLOCKED ──────────────→ [stop: 输
 - `workflow-delegation-contracts.md` — 角色/scope/artifact 契约
 - `workflow-delegation-context-injection.md` — JSONL curation 规范
 
+## 跨宿主对照
+
+- **Pi** 对等契约：`pi-subagent-first.md`（运行时借力 `@tintinweb/pi-subagents`；force policy 在 `.pi/extensions/aiws.ts` + `packages/aiws/src/lib/pi-force-policy.ts`）。
+- Hatch 短语与四状态协议与 Pi 侧一致；派发工具不同（OpenCode/oMo `task` vs Pi `Agent`）。
+
 ## 更新历史
 
 - v1 (2026-05-16): 初版。基于 trellis workflow-state 纪律 + superpowers subagent-driven-development 模式。
+- v1.1 (2026-07-23): 增加 Pi 侧 `pi-subagent-first.md` 交叉链接。

package/docs/pi-plugins-manifest.json

@@ -0,0 +1,136 @@
+{
+  "version": 1,
+  "scope": "user",
+  "source_protocol": "npm:",
+  "install_template": "pi install npm:{package}{versionSuffix}",
+  "required": [
+    {
+      "id": "@tintinweb/pi-subagents",
+      "package": "@tintinweb/pi-subagents",
+      "version": "0.14.2",
+      "tier": "required",
+      "reason": "Single approved Pi subagent runtime for AIWS force policy"
+    }
+  ],
+  "recommended_a": [
+    {
+      "id": "pi-extension-settings",
+      "package": "pi-extension-settings",
+      "tier": "recommended_a"
+    },
+    {
+      "id": "pi-powerbar",
+      "package": "pi-powerbar",
+      "tier": "recommended_a"
+    },
+    {
+      "id": "pi-lsp",
+      "package": "pi-lsp",
+      "tier": "recommended_a"
+    },
+    {
+      "id": "pi-hashline-edit-pro",
+      "package": "pi-hashline-edit-pro",
+      "tier": "recommended_a"
+    },
+    {
+      "id": "rpiv-todo",
+      "package": "rpiv-todo",
+      "tier": "recommended_a"
+    },
+    {
+      "id": "rpiv-ask-user-question",
+      "package": "rpiv-ask-user-question",
+      "tier": "recommended_a"
+    },
+    {
+      "id": "pi-btw",
+      "package": "pi-btw",
+      "tier": "recommended_a"
+    },
+    {
+      "id": "pi-caffeinate",
+      "package": "pi-caffeinate",
+      "tier": "recommended_a"
+    },
+    {
+      "id": "pi-workspace-history",
+      "package": "pi-workspace-history",
+      "tier": "recommended_a"
+    }
+  ],
+  "recommended_b": [
+    {
+      "id": "pi-mcp-adapter",
+      "package": "pi-mcp-adapter",
+      "tier": "recommended_b"
+    },
+    {
+      "id": "pi-fff",
+      "package": "pi-fff",
+      "tier": "recommended_b"
+    },
+    {
+      "id": "pi-slopchop",
+      "package": "pi-slopchop",
+      "tier": "recommended_b"
+    },
+    {
+      "id": "plan-mode",
+      "package": "plan-mode",
+      "tier": "recommended_b"
+    },
+    {
+      "id": "pi-cache-optimizer",
+      "package": "pi-cache-optimizer",
+      "tier": "recommended_b"
+    },
+    {
+      "id": "pi-rtk-optimizer",
+      "package": "pi-rtk-optimizer",
+      "tier": "recommended_b"
+    },
+    {
+      "id": "pi-agent-browser-native",
+      "package": "pi-agent-browser-native",
+      "tier": "recommended_b"
+    },
+    {
+      "id": "pi-add-dir",
+      "package": "pi-add-dir",
+      "tier": "recommended_b"
+    },
+    {
+      "id": "pi-observational-memory",
+      "package": "pi-observational-memory",
+      "tier": "recommended_b",
+      "reason": "Long-session ledger compaction (observer/reflector); optional; exclusive vs other OM forks"
+    }
+  ],
+  "forbidden": [
+    {
+      "id": "@narumitw/pi-subagents",
+      "package": "@narumitw/pi-subagents",
+      "severity": "conflict",
+      "reason": "Second subagent runtime; exclusive with @tintinweb/pi-subagents"
+    },
+    {
+      "id": "pi-subagents",
+      "package": "pi-subagents",
+      "severity": "conflict",
+      "reason": "Unscoped/third-party subagents package; exclusive with @tintinweb/pi-subagents"
+    },
+    {
+      "id": "@narumitw/pi-goal",
+      "package": "@narumitw/pi-goal",
+      "severity": "forbidden",
+      "reason": "Dual goal orchestrator vs aiws goal"
+    },
+    {
+      "id": "pi-autoresearch",
+      "package": "pi-autoresearch",
+      "severity": "forbidden",
+      "reason": "Long main-write research loops under AIWS governance"
+    }
+  ]
+}

package/docs/pi-plugins-manifest.md

@@ -0,0 +1,111 @@
+# Pi plugins manifest (AIWS)
+
+**Change / Problem**: pi-plugin-doctor / PB-010  
+**Req**: TOOLING-002L  
+**Scope**: **user-level** Pi packages (`pi install npm:…` → typically `~/.pi/agent/`)  
+**Non-goals**: silent auto-install; project-local plugin install as default; dual subagent runtimes; reimplement spawn/UI
+
+AIWS owns **rules + detection + install prompts**. Runtime spawn remains `@tintinweb/pi-subagents`.
+
+Machine-readable twin: `pi-plugins-manifest.json` (same directory).
+
+## Install conventions
+
+| Item | Rule |
+|------|------|
+| Source protocol | `npm:` only (no `pnpm:` source protocol) |
+| Backend package manager | optional `settings.npmCommand: ["pnpm"]` (or npm) |
+| Default command | `pi install npm:<package>[@version]` (user scope; do **not** use project `-l` for these packages) |
+| Project `.pi/` | governance only: agents, extensions, skills, `subagents.json` |
+
+## Prerequisite: Pi agent CLI
+
+`--install-pi-plugins` **requires** global Pi CLI (`pi` on PATH), typically:
+
+```bash
+npm i -g @mariozechner/pi-coding-agent
+# or
+pnpm add -g @mariozechner/pi-coding-agent
+```
+
+AIWS **detects** missing `pi` and prints these commands; it does **not** auto-run global install.
+If `pi` is missing, `aiws doctor|init|update --install-pi-plugins` exits non-zero (unless warn-only) and does not call `pi install`.
+
+
+## Layers
+
+### required
+
+Must be present for AIWS Pi force / subagent-first.
+
+| package | pin | reason |
+|---------|-----|--------|
+| `@tintinweb/pi-subagents` | `0.14.2` | Single approved subagent runtime (Agent / get_subagent_result / steer_subagent); aligns with `pi-subagent-first.md` |
+
+Install:
+
+```bash
+pi install npm:@tintinweb/pi-subagents@0.14.2
+```
+
+### recommended (tier A — safe defaults)
+
+Low conflict with AIWS governance; useful quality-of-life.
+
+| package | notes |
+|---------|--------|
+| `pi-extension-settings` | settings UX |
+| `pi-powerbar` | status bar |
+| `pi-lsp` | LSP |
+| `pi-hashline-edit-pro` | edit helper (watch tool names vs force deny) |
+| `rpiv-todo` | todos |
+| `rpiv-ask-user-question` | structured questions |
+| `pi-btw` | asides |
+| `pi-caffeinate` | keep awake |
+| `pi-workspace-history` | history |
+
+### recommended (tier B — on demand)
+
+| package | notes |
+|---------|--------|
+| `pi-mcp-adapter` | MCP |
+| `pi-fff` | file finder |
+| `pi-slopchop` | slop cleanup |
+| `plan-mode` | plan UX (AIWS keeps plan truth) |
+| `pi-cache-optimizer` | cache (truncation caution) |
+| `pi-rtk-optimizer` | RTK |
+| `pi-agent-browser-native` | browser |
+| `pi-observational-memory` | Long-session OM (elpapi42 V3); optional; do not dual-install other OM forks |
+| `pi-add-dir` | add dirs |
+
+### forbidden / conflict
+
+| package / pattern | severity | reason |
+|-------------------|----------|--------|
+| `@narumitw/pi-subagents` | conflict | Second subagent runtime; not API-compatible with tintinweb mapping |
+| `pi-subagents` (unscoped / nicobailon-style) | conflict | Third ecosystem variant; exclusive with tintinweb |
+| `@narumitw/pi-goal` | forbidden | Dual goal orchestrator vs `aiws goal` |
+| `pi-autoresearch` | forbidden | Long main-write research loops under AIWS governance |
+
+**Rule**: install **exactly one** subagent runtime — AIWS requires `@tintinweb/pi-subagents` only.
+
+## Detect sources (priority)
+
+1. `pi list` if `pi` is on PATH  
+2. `~/.pi/agent/settings.json` and/or packages metadata under `~/.pi/agent/`  
+3. If neither available → report `pi_cli_missing` + install hints; do not crash
+
+## CLI behavior (`aiws doctor`)
+
+- Print layered report + copy-paste `pi install npm:…` lines  
+- **Default**: no install  
+- Missing **required** → exit code ≠ 0  
+- Conflicts / forbidden installed → warn (exit ≠ 0 if any required missing or any conflict)  
+- `init --pi` / `update` (when `.pi/` exists or `--pi`): print same report as **warn**; do not fail init/update by default  
+- Optional `--install-pi-plugins`: install **required only** (user scope); recommended stay print-only
+
+## Related
+
+- `docs/pi-subagent-first.md`  
+- `packages/aiws/src/lib/pi-plugins-doctor.ts`  
+- `packages/aiws/src/lib/pi-force-policy.ts`

package/docs/pi-subagent-first.md

@@ -0,0 +1,182 @@
+# Pi Subagent-First Execution
+
+<!-- Managed by aiws. Do not hand edit. -->
+
+**规范 ID**: `pi-subagent-first`  
+**版本**: 1  
+**运行时**: `@tintinweb/pi-subagents` ≥ 0.14.2（spawn/UI/RPC）  
+**策略归属**: AIWS（`.pi/extensions/aiws.ts` + validate + 本规范）
+
+## 目的
+
+在 **Pi** 宿主中强制 subagent-first：主 session 只做协调/收敛；实现与审查由 `aiws-worker` / `aiws-reviewer` 完成。对齐 `opencode-subagent-first.md` 的执行纪律，堵住主 session 直接 `write`/`edit` 业务代码的失败模式。
+
+**非目标**
+
+- 不自研 subagent runtime / pane daemon / 第二 orchestrator（TOOLING-002L）。
+- **不修改 OpenCode 插件 write-deny**（另 change）。
+- 不与 Trellis `trellis_subagent` 双 runtime；Pi 侧仅 `pi-subagents`。
+
+## 核心原则
+
+1. **Subagent-first**: 实现默认 `Agent({ subagent_type: "aiws-worker", ... })`；审查默认 `aiws-reviewer`。
+2. **Review loop**: 每个 worker 交付后至少一次 reviewer（或等价 `ws-quality-review`）；fail 则修再审。
+3. **Continuous**: 主 session 不因“下一步做什么”主动停顿——除非 BLOCKED / NEEDS_CONTEXT 超限 / 任务完成。
+4. **Explicit override (hatch)**: 仅用户**当前消息**显式短语可允许主 session 写实现；必须落盘 hatch 证据。
+5. **No silent fallback**: 委托失败 → 写 `evidence/delegate-failure.md` 并 **stop**；禁止默默改由主 session 写业务代码。
+6. **Type whitelist**: 实现路径仅允许 `aiws-worker` | `aiws-reviewer`。pi-subagents 对未知 type 会 **fallback 到 general-purpose**——AIWS 扩展必须拒绝非白名单 type。
+
+## 运行时安装
+
+```bash
+pi install npm:@tintinweb/pi-subagents
+# 建议钉版本: @tintinweb/pi-subagents@0.14.2
+```
+
+父 session 可用工具（由 pi-subagents 提供）：
+
+| Tool | 用途 |
+|------|------|
+| `Agent` | 派生子 agent |
+| `get_subagent_result` | 取回完成结果 |
+| `steer_subagent` | 运行中纠偏 |
+
+项目配置建议 `.pi/subagents.json`：
+
+```json
+{
+  "disableDefaultAgents": true
+}
+```
+
+`disableDefaultAgents: true` 关闭内置 `general-purpose` / `Explore` / `Plan` 的默认注册，减少“随便派 general-purpose 写代码”的逃逸。自定义 `.pi/agents/aiws-*.md` 仍可用。
+
+自定义 agent 发现顺序（高优先）：
+
+1. `.pi/agents/<name>.md`
+2. `.agents/agents/<name>.md`
+3. `~/.pi/agent/agents/<name>.md`
+
+## 角色
+
+| 角色 | type | 工具意图 |
+|------|------|----------|
+| 主 session / orchestrator | 父会话 | 只读 + `Agent` / `get_subagent_result` / `steer_subagent` + `aiws` CLI；**无 hatch 时禁止业务路径 write/edit** |
+| 实现者 | `aiws-worker` | read, write, edit, bash, find, grep；禁止 git commit/push/merge |
+| 审查者 | `aiws-reviewer` | 只读为主；审查产物写 `.aiws/changes/**/review|evidence`（由策略允许） |
+
+**已弃用主路径**: `aiws_subagent`（`ctx.newSession`）。可保留兼容警告/转发，不得作为 primary。
+
+## 执行循环（Continuous Loop）
+
+```text
+主 session 策划上下文（JSONL / prompt 边界）
+  → Agent(subagent_type=aiws-worker, prompt=…)
+  → worker: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
+  → DONE → Agent(subagent_type=aiws-reviewer, …)
+  → reviewer pass → 收敛 evidence → 准备 finish
+  → reviewer fail → worker 修复（≤3 轮）
+  → DONE_WITH_CONCERNS → quality 评估残余风险
+  → NEEDS_CONTEXT → 补上下文重试（≤2）
+  → BLOCKED → 停止并输出 blocker
+  → 委托失败/超时 → evidence/delegate-failure.md + stop（禁止静默主写）
+```
+
+### Worker 报告格式
+
+```text
+**Status:** DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
+**Completed:** 实现内容摘要
+**Files Changed:** 文件清单
+**Verification:** 命令 + 结果
+**Artifacts:** changes/<id>/analysis|patches|evidence 路径
+**Concerns:** 疑虑（若有）
+```
+
+### Reviewer
+
+- 输入：patches / evidence / analysis，**不是**主 session 完整历史。
+- 输出：pass/fail + findings；落盘 `changes/<id>/review/`。
+
+### 停止条件
+
+- BLOCKED（治理/脏树/validate 失败等）
+- NEEDS_CONTEXT 超过 2 次
+- 验证缺失或失败
+- 需 host permission
+- 用户改 scope
+- 委托失败已记录且未恢复
+- 全部任务完成且 evidence 收敛
+
+## Inline Escape Hatch
+
+**当前用户消息**含以下之一时，主 session 可直接写实现：
+
+- `直接改` / `do it inline` / `你直接改`
+- `别派 sub-agent` / `main session 写就行`
+- `不用 sub-agent` / `no sub-agent`
+
+规则：
+
+- 仅**当前**消息；不得沿用上轮
+- 主 session 不得自行推断
+- 必须写 `changes/<id>/evidence/inline-escape-hatch.md`
+- hatch 有效期内仍应优先小步、可验证
+
+## 主会话写路径策略（L1）
+
+**无 hatch 时**：
+
+- **拒绝** 对业务代码路径的 write/edit（扩展拦截或等价门禁）
+- **允许**（白名单示例）：
+  - `.aiws/changes/**/evidence/**`
+  - `.aiws/changes/**/analysis/**`
+  - `.aiws/changes/**/review/**`
+  - `.aiws/plan/**`
+  - （可选）`.aiws/goals/**`
+
+**Agent type**：仅 `aiws-worker` | `aiws-reviewer`；其它 type → 拒绝并要求改 type 或 hatch。
+
+**Delegate 失败**：写 `evidence/delegate-failure.md`，停止；禁止无记录地改由主 session 实现业务逻辑。
+
+## Context 纪律
+
+与 OpenCode 侧相同精神：
+
+1. 从委托合同整理 JSONL / 明确路径列表  
+2. high+medium 文件数与行数预算  
+3. 写入 `changes/<id>/analysis/<role>-context.jsonl`（若使用）  
+4. Reviewer 只收工作产物  
+
+详见 `workflow-delegation-context-injection.md`、`workflow-delegation-contracts.md`。
+
+## 四状态协议
+
+| 状态 | 含义 | 后续 |
+|------|------|------|
+| DONE | 完成且验证通过 | → reviewer |
+| DONE_WITH_CONCERNS | 完成但有残余风险 | → quality 评估 |
+| NEEDS_CONTEXT | 缺上下文 | 补后重试 ≤2；仍失败 → 记 failure，**不**静默主写 |
+| BLOCKED | 治理阻断 | stop + blocker |
+
+## 与 OpenCode 对照
+
+| 项 | OpenCode (`opencode-subagent-first`) | Pi（本规范） |
+|----|-------------------------------------|--------------|
+| 派发 | oMo / task 等 | pi-subagents `Agent` |
+| 实现 type | aiws-worker | aiws-worker（`.pi/agents/`） |
+| 审查 type | aiws-reviewer | aiws-reviewer |
+| Hatch | 相同短语 | 相同短语 |
+| 策略硬门 | 插件/约定 | `.pi/extensions/aiws.ts` + validate |
+| 未知 type | 平台相关 | 必须拒（因 general-purpose fallback） |
+
+## 引用
+
+- `opencode-subagent-first.md` — OpenCode 侧对等契约  
+- `.aiws/changes/*/analysis/pi-subagents-api-notes.md` — 版本化 API 笔记（变更工件）  
+- `workflow-delegation-contracts.md`  
+- `AI_PROJECT.md` Pi 相关规则（项目真值）
+
+## 更新历史
+
+- v1 (2026-07-23): 初版。借力 pi-subagents 0.14.x；AIWS 拥有 force policy（deny / whitelist / hatch / no silent fallback）。

package/docs/workflow-delegation-context-injection.md

@@ -73,6 +73,10 @@ changes/<id>/analysis/<role>-context.jsonl
 
 aiws 提供了两个 OpenCode 插件，自动实现上下文注入：
 
+### aiws-workflow-state（chat.message hook，每轮）
+
+每轮用户消息注入 `<workflow-state>` breadcrumb（active change / phase）。支持 skip keyword 默认 `no-aiws`（见 §per-turn workflow-state skip）。
+
 ### aiws-session-start（chat.message hook）
 
 每个新会话启动时，自动读取当前 change 上下文、项目真值、规范索引，并注入到第一条用户消息中。
@@ -90,8 +94,8 @@ aiws 提供了两个 OpenCode 插件，自动实现上下文注入：
 当 `task()` 调用且 prompt 中包含 `role: <role>` 标记时自动拦截，读取 `changes/<id>/analysis/<role>-context.jsonl` 并注入到子 agent prompt。
 
 **自动注入内容**：
-1. JSONL 中引用的每个文件内容（按 priority 排序）
-2. `<aiws-context-injection>` 头部（含 role、context file 路径、entry 数量）
+1. JSONL 中引用的每个文件内容（按 priority 排序；运行时字节 cap 后可能为 truncated/index 形态）
+2. `<aiws-context-meta>` 头部（含 role、change、files 计数：inline/truncated/index）
 3. 粘性指令：要求子 agent 先读上下文文件再工作
 
 当插件被激活时，主 agent 不需要手动粘性指令模板——插件会自动生成。
@@ -151,7 +155,40 @@ aiws 提供了两个 OpenCode 插件，自动实现上下文注入：
 
 ## 上下文预算管理
 
-子 agent 的上下文窗口有限。策展者必须执行预算检查：
+子 agent 的上下文窗口有限。策展者必须执行预算检查。除策展软规则外，OpenCode 插件还施加运行时字节 cap（见下）。
+
+### 运行时字节 cap（trellis #441 / TOOLING-003A）
+
+策展层的 5 文件 / 4000 行规则**不能**单独保证子 agent prompt 安全。OpenCode 插件在 `readJsonlWithFiles` 中额外执行运行时字节 cap（与 trellis `context_injection` 对齐）：
+
+| 限制 | 默认 | 环境变量 | `0` 含义 |
+|------|------|----------|----------|
+| 单文件 (`max_file_bytes`) | 32768 (32KiB) | `AIWS_CONTEXT_MAX_FILE_BYTES` | 不限 |
+| 单 artifact | 65536 (64KiB) | `AIWS_CONTEXT_MAX_ARTIFACT_BYTES` | 不限（预留；当前 JSONL 文件路径共用 file cap） |
+| 注入总量 | 131072 (128KiB) | `AIWS_CONTEXT_MAX_TOTAL_BYTES` | 不限 |
+
+**处理管线（每条 JSONL 条目）**：
+1. 读取文件字节 → 可选 `sections` 行裁剪（**先于**字节 cap）
+2. 按 `priority` 排序（high → medium → low）
+3. 单文件 `truncateUtf8`：不切断 UTF-8 多字节序列；截断时追加 notice：`[AIWS: truncated at N bytes — read <path> for the full content]`
+4. 总量预算：若完整 `=== path ===` 块放不下，则 **degrade-to-index**，仅注入：`[AIWS: not inlined (total context limit reached) — path (size bytes): reason]`
+5. 条目 `mode`：`inline` | `truncated` | `index`
+
+**验证入口**：`node scripts/test-context-injection-limits.mjs`
+
+### per-turn workflow-state skip（trellis #427 / TOOLING-003A）
+
+`aiws-workflow-state` 在每条用户消息注入 breadcrumb。若用户 prompt 文本中出现 skip keyword（**词边界、大小写不敏感**；连字符算词字符），则本轮**不注入**。
+
+| 项 | 值 |
+|----|-----|
+| 默认 keyword | `no-aiws` |
+| 覆盖 | 环境变量 `AIWS_WORKFLOW_SKIP_KEYWORD` |
+| 禁用 escape hatch | `AIWS_WORKFLOW_SKIP_KEYWORD=`（空串；keyword 永不匹配） |
+
+匹配示例：`no-aiws how...` / `(no-aiws)` / `path/no-aiws.md` 会 skip；`no-aiwsx` / `foo-no-aiws` **不会**。
+
+**验证入口**：`node scripts/test-workflow-skip-keyword.mjs`
 
 ### 预算规则
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipper/aiws-spec",
-  "version": "0.0.49",
+  "version": "0.0.51",
   "description": "AIWS spec and templates (single source of truth).",
   "type": "module",
   "files": [

package/templates/workspace/.opencode/lib/aiws-context.js

@@ -70,6 +70,133 @@ function parseSections(entry) {
   }).filter(Boolean)
 }
 
+
+// ============================================================
+// Context injection limits (trellis #441 / TOOLING-003A)
+// Defaults mirror trellis: 32KiB / 64KiB / 128KiB; 0 = unlimited
+// Env: AIWS_CONTEXT_MAX_FILE_BYTES | AIWS_CONTEXT_MAX_ARTIFACT_BYTES | AIWS_CONTEXT_MAX_TOTAL_BYTES
+// ============================================================
+
+export const DEFAULT_CONTEXT_INJECTION_LIMITS = Object.freeze({
+  max_file_bytes: 32768,
+  max_artifact_bytes: 65536,
+  max_total_bytes: 131072,
+})
+
+/**
+ * Parse a non-negative integer env override; invalid/missing → default.
+ * Note: empty string is invalid → default (use "0" for unlimited).
+ */
+function parseLimitEnv(name, defaultValue) {
+  const raw = process.env[name]
+  if (raw === undefined || raw === null || raw === "") return defaultValue
+  const n = Number.parseInt(String(raw), 10)
+  if (!Number.isFinite(n) || n < 0) return defaultValue
+  return n
+}
+
+/** Resolve context injection byte limits from env (or defaults). */
+export function getContextInjectionLimits() {
+  return {
+    max_file_bytes: parseLimitEnv("AIWS_CONTEXT_MAX_FILE_BYTES", DEFAULT_CONTEXT_INJECTION_LIMITS.max_file_bytes),
+    max_artifact_bytes: parseLimitEnv("AIWS_CONTEXT_MAX_ARTIFACT_BYTES", DEFAULT_CONTEXT_INJECTION_LIMITS.max_artifact_bytes),
+    max_total_bytes: parseLimitEnv("AIWS_CONTEXT_MAX_TOTAL_BYTES", DEFAULT_CONTEXT_INJECTION_LIMITS.max_total_bytes),
+  }
+}
+
+/**
+ * Truncate raw bytes to at most `cap` without splitting a UTF-8 multi-byte sequence.
+ * `cap <= 0` means unlimited — returns data unchanged.
+ * @param {Buffer} data
+ * @param {number} cap
+ * @returns {Buffer}
+ */
+export function truncateUtf8(data, cap) {
+  if (!Buffer.isBuffer(data)) {
+    data = Buffer.from(data ?? "", "utf8")
+  }
+  if (cap <= 0 || data.length <= cap) return data
+
+  let truncated = data.subarray(0, cap)
+  let i = truncated.length
+  // Back off over continuation bytes (10xxxxxx)
+  while (i > 0 && (truncated[i - 1] & 0xc0) === 0x80) {
+    i -= 1
+  }
+  if (i === 0) return Buffer.alloc(0)
+
+  const lead = truncated[i - 1]
+  if (lead & 0x80) {
+    let seqLen = 1
+    if ((lead & 0xe0) === 0xc0) seqLen = 2
+    else if ((lead & 0xf0) === 0xe0) seqLen = 3
+    else if ((lead & 0xf8) === 0xf0) seqLen = 4
+    // Drop the lead byte too if its full sequence didn't fit
+    if (i - 1 + seqLen > truncated.length) {
+      i -= 1
+    }
+  }
+  return truncated.subarray(0, i)
+}
+
+function truncateNotice(path, cap) {
+  return `\n[AIWS: truncated at ${cap} bytes — read ${path} for the full content]`
+}
+
+function indexNotice(path, size, reason) {
+  return (
+    `[AIWS: not inlined (total context limit reached) — ` +
+    `${path} (${size} bytes): ${reason || "budget"}]`
+  )
+}
+
+class ContextBudget {
+  constructor(maxTotalBytes) {
+    this.maxTotalBytes = maxTotalBytes
+    this.used = 0
+  }
+  hasRoom(size) {
+    if (this.maxTotalBytes <= 0) return true
+    return this.used + size <= this.maxTotalBytes
+  }
+  add(size) {
+    this.used += size
+  }
+}
+
+// ============================================================
+// Workflow skip keyword (trellis #427 / TOOLING-003A)
+// Default: no-aiws; env AIWS_WORKFLOW_SKIP_KEYWORD ("" disables)
+// ============================================================
+
+export const DEFAULT_WORKFLOW_SKIP_KEYWORD = "no-aiws"
+
+/**
+ * Resolve per-turn workflow-state skip keyword.
+ * - unset → "no-aiws"
+ * - "" → disabled (never matches)
+ * - any other string → custom keyword
+ */
+export function resolveWorkflowSkipKeyword() {
+  if (!Object.prototype.hasOwnProperty.call(process.env, "AIWS_WORKFLOW_SKIP_KEYWORD")) {
+    return DEFAULT_WORKFLOW_SKIP_KEYWORD
+  }
+  return String(process.env.AIWS_WORKFLOW_SKIP_KEYWORD)
+}
+
+/**
+ * Case-insensitive, word-boundary match of `keyword` in `text`.
+ * Hyphen counts as a word char so "no-aiwsx" / "foo-no-aiws" don't match.
+ * Empty keyword never matches.
+ */
+export function promptHasSkipKeyword(text, keyword) {
+  if (!keyword || typeof text !== "string") return false
+  const escaped = String(keyword).replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  const pattern = new RegExp(`(?<![\\w-])${escaped}(?![\\w-])`, "i")
+  return pattern.test(text)
+}
+
+
 // ============================================================
 // AiwsContext
 // ============================================================
@@ -145,11 +272,28 @@ export class AiwsContext {
    * Returns array of { path, content, priority, kind, reason }
    * Sorted by priority: high → medium → low
    */
-  readJsonlWithFiles(jsonlPath) {
+  /**
+   * Read a JSONL file and load referenced file contents with byte caps (#441).
+   *
+   * Supports aiws 5-field format:
+   *   {"file"|"glob": "...", "sections": [[25,50]], "priority": "high", "kind": "truth", "reason": "why"}
+   *
+   * Pipeline per entry (after priority sort of *candidates*):
+   *   1. read file bytes
+   *   2. optional section filter (line-based on UTF-8 text)
+   *   3. per-file truncateUtf8 (max_file_bytes; 0 = unlimited)
+   *   4. total budget: if full block won't fit → mode "index" notice only
+   *
+   * Returns array of:
+   *   { path, content, priority, kind, reason, mode: "inline"|"truncated"|"index", byteSize?, originalByteSize? }
+   * Sorted by priority: high → medium → low (stable relative to JSONL order within tier).
+   */
+  readJsonlWithFiles(jsonlPath, limits = null) {
     const content = this.readFile(jsonlPath)
     if (!content) return []
 
-    const entries = []
+    const lim = limits || getContextInjectionLimits()
+    const candidates = []
 
     for (const rawLine of content.split(/\r?\n/)) {
       const line = rawLine.trim()
@@ -157,7 +301,6 @@ export class AiwsContext {
       try {
         const item = JSON.parse(line)
 
-        // Resolve glob to actual file
         const globPattern = item.glob || item.file
         if (!globPattern) continue
 
@@ -166,32 +309,98 @@ export class AiwsContext {
         const reason = item.reason || ""
         const sections = parseSections(item)
 
-        // Read the file
         const fullPath = resolvePath(this.directory, globPattern)
-        let fileContent = this.readFile(fullPath)
-        if (!fileContent) continue
+        let rawBytes
+        try {
+          if (!existsSync(fullPath)) continue
+          rawBytes = readFileSync(fullPath)
+        } catch {
+          continue
+        }
+        if (!rawBytes || rawBytes.length === 0) {
+          // empty file still allowed as empty content
+          rawBytes = Buffer.alloc(0)
+        }
+
+        let text = rawBytes.toString("utf8")
+        const originalByteSize = Buffer.byteLength(text, "utf8")
 
-        // Apply section filtering if specified
+        // Apply section filtering if specified (before byte caps)
         if (sections) {
-          const lines = fileContent.split("\n")
+          const lines = text.split("\n")
           const filtered = []
           for (const [start, end] of sections) {
             const from = Math.max(0, start - 1)
             const to = Math.min(lines.length, end)
             filtered.push(...lines.slice(from, to))
           }
-          fileContent = filtered.join("\n")
+          text = filtered.join("\n")
         }
 
-        entries.push({ path: globPattern, content: fileContent, priority, kind, reason })
+        candidates.push({
+          path: globPattern,
+          text,
+          priority,
+          kind,
+          reason,
+          originalByteSize,
+        })
       } catch {
         // Skip malformed lines
       }
     }
 
-    // Sort: high → medium → low
+    // Sort: high → medium → low (preserve relative order within tier via stable sort)
     const order = { high: 0, medium: 1, low: 2 }
-    entries.sort((a, b) => (order[a.priority] ?? 2) - (order[b.priority] ?? 2))
+    candidates.sort((a, b) => (order[a.priority] ?? 2) - (order[b.priority] ?? 2))
+
+    const budget = new ContextBudget(lim.max_total_bytes)
+    const entries = []
+
+    for (const c of candidates) {
+      const sectionBytes = Buffer.from(c.text, "utf8")
+      const fileCap = lim.max_file_bytes
+      const truncatedBytes = truncateUtf8(sectionBytes, fileCap)
+      let body = truncatedBytes.toString("utf8")
+      let mode = "inline"
+      if (truncatedBytes.length < sectionBytes.length) {
+        mode = "truncated"
+        body += truncateNotice(c.path, fileCap)
+      }
+
+      // Budget the emitted block the same shape as buildContextFromEntries header+content
+      const header = `=== ${c.path} ===${c.reason ? ` (${c.reason})` : ""}`
+      const block = `${header}\n${body}`
+      const blockBytes = Buffer.byteLength(block, "utf8")
+
+      if (!budget.hasRoom(blockBytes)) {
+        const notice = indexNotice(c.path, c.originalByteSize, c.reason)
+        budget.add(Buffer.byteLength(notice, "utf8"))
+        entries.push({
+          path: c.path,
+          content: notice,
+          priority: c.priority,
+          kind: c.kind,
+          reason: c.reason,
+          mode: "index",
+          byteSize: Buffer.byteLength(notice, "utf8"),
+          originalByteSize: c.originalByteSize,
+        })
+        continue
+      }
+
+      budget.add(blockBytes)
+      entries.push({
+        path: c.path,
+        content: body,
+        priority: c.priority,
+        kind: c.kind,
+        reason: c.reason,
+        mode,
+        byteSize: Buffer.byteLength(body, "utf8"),
+        originalByteSize: c.originalByteSize,
+      })
+    }
 
     return entries
   }
@@ -206,7 +415,10 @@ export class AiwsContext {
     if (!entries || entries.length === 0) return ""
     return entries
       .map(e => {
-        const header = `=== ${e.path} ===${e.reason ? ` (${e.reason})` : ""}`
+        // index mode content is already a self-describing notice (no === header)
+        if (e.mode === "index") return e.content
+        const modeTag = e.mode && e.mode !== "inline" ? ` [mode=${e.mode}]` : ""
+        const header = `=== ${e.path} ===${e.reason ? ` (${e.reason})` : ""}${modeTag}`
         return `${header}\n${e.content}`
       })
       .join("\n\n")

package/templates/workspace/.opencode/plugins/aiws-inject-context.js

@@ -176,8 +176,20 @@ export default async ({ directory }) => {
           return
         }
 
-        const contextBlock = ctx.buildContextBlock(entries)
-        debugLog("inject", `Injected context for role "${role}", entries: ${entries.length}`)
+        const counts = { inline: 0, truncated: 0, index: 0 }
+        for (const e of entries) {
+          const m = e.mode || "inline"
+          if (m in counts) counts[m] += 1
+          else counts.inline += 1
+        }
+        const metaHeader =
+          `<aiws-context-meta>\n` +
+          `role: ${role}\n` +
+          `change: ${changeId}\n` +
+          `files: ${entries.length} (inline=${counts.inline}, truncated=${counts.truncated}, index=${counts.index})\n` +
+          `</aiws-context-meta>`
+        const contextBlock = `${metaHeader}\n\n${ctx.buildContextBlock(entries)}`
+        debugLog("inject", `Injected context for role "${role}", entries: ${entries.length}`, counts)
 
         // Record delegation event to journal
         const sessionKey = ctx.getSessionKey({ sessionID: input?.session_id || "" })

package/templates/workspace/.opencode/plugins/aiws-workflow-state.js

@@ -8,7 +8,10 @@
  * Reference: trellis/packages/cli/src/templates/opencode/plugins/inject-workflow-state.js
  */
 
-import { AiwsContext, AiwsSessionJournal, debugLog } from "../lib/aiws-context.js"
+import { AiwsContext, AiwsSessionJournal, debugLog, promptHasSkipKeyword, resolveWorkflowSkipKeyword } from "../lib/aiws-context.js"
+
+// Re-export for tests (TOOLING-003A / #427)
+export { promptHasSkipKeyword, resolveWorkflowSkipKeyword }
 
 /**
  * Build the workflow-state breadcrumb block.
@@ -79,6 +82,18 @@ export default async ({ directory }) => {
           return
         }
 
+        // Escape hatch (trellis #427): skip keyword in user prompt (default no-aiws)
+        const partsProbe = output?.parts || []
+        const originalText = partsProbe
+          .filter(p => p && p.type === "text" && typeof p.text === "string")
+          .map(p => p.text)
+          .join("\n")
+        const skipKeyword = resolveWorkflowSkipKeyword()
+        if (promptHasSkipKeyword(originalText, skipKeyword)) {
+          debugLog("workflow-state", "Skipping turn: skip keyword present in prompt", skipKeyword)
+          return
+        }
+
         if (!ctx.isAiwsProject()) {
           return
         }