AGENTS.md git:20261021.7ea6378A

Immutable. This exact content never changes and is served at /api/v1/blob/0e70dcd281442f23.

# AGENTS.md

Global constraints and task routes; `CLAUDE.md` imports this file.

## 0. Meta rules (precedence + SSOT)

- Precedence: this file > affected workspace AGENTS > local harness/docs > root validation overlay. Lower layers refine, never contradict, the upper.
- SSOT: `pnpm-workspace.yaml` owns membership; package.json owns metadata/scripts; workspace AGENTS/harness own local roles, contracts, and knowledge. Do not copy inventories.
- Establish the problem, goal, constraints, and current evidence first; do not reverse-justify a change from an MR or neighboring code.
- Reuse existing modules, scripts, skills, and docs. Add assets only when existing entries cannot carry the work and the addition reduces complexity or enforces a constraint. Newness is not a reason.
- Make everything as simple as possible, but not simpler. Add an abstraction layer (port, adapter, registry, barrel, wrapper) only for a real second caller or implementation, or for a boundary that a test enforces. Write a single implementation directly; do not reserve extension points for hypothetical needs. Do not simplify away a needed invariant, guard, or boundary.
- Prefer plugin/hook/tool/service boundaries over engine-loop hardcoding. Verify that enforcement actually exists; a documented gate is not a runner.
- Maintain AGENTS by decision value and ownership: keep necessary scoped constraints and task routes; apply the content-admission principles in `harness/DESIGN.md`. Length metrics are observational.
- Write explanations and documentation in an ASD-STE100-inspired style (about 80% strictness): use short sentences, active voice, plain words, and consistent terms. Apply the same principles in Chinese; keep natural phrasing and necessary technical detail.

Self-check: evidence, reuse, smallest change, no speculative abstraction, SSOT/consumers, executable guard (or why only documentation).

## 1. Routing

Read `harness/README.md`, the affected workspace AGENTS, and local validation. Follow task-matched routes; detailed resources are required when their trigger applies.

| Task / trigger | Required owner or protocol |
|---|---|
| Engine, plugins/tools, compaction/offload, MCP/runtime config, orchestration | `packages/engine/AGENTS.md` |
| Terminal CLI / host behavior | `packages/cli/AGENTS.md` |
| Canvas app, renderer, shortcuts, embedded browser | `apps/canvas-workspace/AGENTS.md` |
| Canvas CLI / storage concurrency | `packages/canvas-cli/AGENTS.md` |
| Shared storage contracts, SQLite adapter, storage migration phases | `packages/storage/AGENTS.md`; roadmap `harness/spec/unified-storage/README.md` |
| Remote adapters, dispatcher, internal routes | `apps/remote-server/AGENTS.md` |
| Usage telemetry: Canvas client or gateway Worker | `apps/telemetry-gateway/AGENTS.md` |
| Team coordination / ACP / plugin infrastructure | `packages/agent-teams/AGENTS.md`, `packages/acp/AGENTS.md`, or `packages/plugin-kit/AGENTS.md`, according to the changed package |
| Canvas capability shared by Tool + CLI | `harness/skills/add-canvas-capability/SKILL.md` |
| Add/remove workspace | `pnpm-workspace.yaml`; its AGENTS and local validation; root overlay if impact changes |
| Harness governance / documentation structure | `harness/DESIGN.md`, `harness/README.md`, `harness/ROADMAP.md` |
| Harness visualization / entry slimming | `harness/skills/visualize-harness/SKILL.md` or `harness/skills/slim-agents-md/SKILL.md` |

## 2. Hard boundaries (real values)

- Use pnpm pinned by root package.json, never npm/yarn. Node is unpinned.
- Keep TypeScript strict. Canvas tsconfigs are independent. Match each package's module format and scripts.
- Root `tsconfig.json` owns aliases; do not invent them. Other internal dependencies use `workspace:*`.
- No lint/format tool is configured. Match local style: two spaces, semicolons, single quotes.
- Never satisfy file/component line limits by merging statements, JSX, or props onto fewer lines, or removing useful spacing/comments. Keep readable formatting; reduce size through cohesive responsibility boundaries, not line-count-only fragmentation.
- Read workspace validation for test/build and coverage limitations. Passing tests do not prove untested modules.

## 3. Auxiliary-workspace boundary

`apps/devtools-web` is excluded from pnpm workspaces but remote-server still serves it; do not delete it. Serving details: `apps/remote-server/AGENTS.md`.

## 4. Prerequisites and automation

Before code/review: owning AGENTS + local validation. Before contract changes: affected contracts + root overlay. Before docs: nearest owner + `harness/DESIGN.md`.

After creating or entering a linked git worktree, run `pnpm bootstrap:worktree` before build/test. It keeps each worktree's `node_modules` layout local while reusing the shared pnpm store, and refuses dependency links that resolve into another checkout.

Performance, harness-integrity, and quality CI are defined. Quality runs core package tests and Canvas typecheck, dead-code check, and tests on every PR; other bound workspace acceptance still runs manually, and the integrity workflow only checks harness code/data and plans commands. See `harness/validate/README.md`. Qualify further enforcement before enabling it.

Repo protocols live in harness/skills; product skills in .pulse-coder/skills. Use existing protocols; add one only for stable recurring work.

## 5. Acceptance (reproducible + verifiable)

Run `node scripts/harness/run-harness-check.mjs --level standard` for completed changes; quick for iteration, release for relevant performance/release evidence. Use explicit paths to scope unrelated work. Escalation reminders require judgment and manual execution.

Include Canvas explicitly when affected: root core build/test excludes it. Full-sweep and evidence details: `harness/validate/README.md`.

Harness edits must pass `node scripts/harness/check-harness.mjs` with `harnessGaps: 0`. Report executed checks, results, and unverified scope; dry-run/structural success is not full acceptance.

Creating or updating a PR/MR is not completion. After each push, inspect the CI run for the current HEAD; do not report success while required checks are running or failing. Read the exact failing job output, reproduce it where practical, fix the root cause, push, and inspect the replacement run. Detailed procedure belongs in the affected workspace validation skill.

## 6. Failure capture (named failure -> guard)

Before changing a failure-sensitive boundary, read its existing guards:

| Boundary | Required detail |
|---|---|
| History cleanup / later user turns | `packages/engine/harness/knowledge/loop-lifecycle.md` |
| Tool blocking I/O, UTF-8, shell argument safety | `packages/engine/harness/knowledge/tools-reference.md` |
| Engine/plugin logging in terminal hosts | `packages/engine/harness/knowledge/host-integration.md` |
| MCP scope activation / fresh reload | `apps/canvas-workspace/harness/knowledge/plugin-market.md` |
| Hidden webview capture / guest lifetime | `apps/canvas-workspace/harness/knowledge/dock-browser.md` |
| CLI write locks / app-versus-CLI arbitration | `packages/canvas-cli/harness/knowledge/storage-concurrency.md` |
| Menu, registry, and terminal shortcut ownership | `apps/canvas-workspace/harness/knowledge/keyboard-shortcuts.md` |

Preserve guards; new history cleanup needs a regression test. Cross-check tests against their script before claiming no coverage. Debug with `git log -- <file>` and focused tests, not TODO searches.

Write back: facts -> owning Knowledge; checks -> local validation; procedures -> existing Skills. Update the existing owner, consolidate duplicate rules, and retire source-verified obsolete guidance. Entry changes must satisfy the content-admission principles; retain the constraint or trigger with its owner pointer. No task-log accumulation or separate feedback store.

## 7. Security / secrets

Never commit keys/tokens. Follow the env-only key policy in engine config-reference; plugin secrets use vault helpers. Remote internal routes stay loopback-only and require INTERNAL_API_SECRET.

## 8. .pulse-coder/ vs .coder/

Use .pulse-coder for new runtime config; preserve .coder compatibility unless explicitly migrating. Runtime layout, loaders, and inventory sources: `packages/engine/harness/knowledge/config-reference.md`.