Surface Route Work

surface-route-work

Use this when a task touches connected ClawJS/Clawix surfaces, runtime-critical paths, bridge/Relay behavior, CLI/MCP/API contracts, storage ownership, permissions, grants, approvals, audit, or agent chat routes.

Procedure

1. Run claw search <topic> --json first. If claw is not on PATH, use the ClawJS checkout binary from the ClawJS repo root (node packages/clawjs/bin/claw.mjs) or a configured sibling checkout such as ../clawjs/packages/clawjs/bin/claw.mjs, and note the fallback.
2. Resolve the working node or route with:
   • claw inspect show <surface> --json
   • claw inspect neighbors <surface> --json
   • claw inspect routes --json
   • claw inspect route <route-id> --json
3. Read the ADRs, docs, tests, and source files named by the inspection output. For the route graph contract itself, start from sibling ClawJS canon docs/adr/0049-surface-route-graph.md. For remote, Relay, Gateway, Coordinator, Connector, Sync, Iroh, node trust, or sync-resource route work, also read sibling ClawJS canon docs/adr/0022-remote-gateway-sync-redesign.md. The local Clawix mirror is docs/adr/0011-surface-route-graph.md.
4. Choose the work mode explicitly:
   • surface-first: start at one node and inspect adjacent ingress/egress;
   • route-first: follow every explicit step in the registered route.
5. Keep ownership intact. Framework contracts, schemas, storage, SDK, CLI, MCP, service APIs, and Relay contracts stay in ClawJS/Claw. Clawix owns native UI, host identity, visual state, and host operational state.
6. Update the registry graph when a stable node, edge, route, transport, contract, owner, validation, or gap changes.
7. Add surfaceNarrative to every new or changed stable node/route that creates a surface: concept, authorizing decision, completing human/programmatic surface, and non-inference boundary.
8. Add resourceContract to every new or changed stable node/route that creates a runtime, UI, storage, stream, cache, API, CLI, permission, or feature-flag surface: startup, idle, memory, streaming, storage, hot path, scale, and validation.
9. Register new durable route docs, skills, guards, or harnesses in docs/discoverability.registry.json per docs/adr/0017-discoverability-and-meta-code-routing.md.
10. Before closure, run the discoverability closure gate for the changed canon/route files, for example node scripts/discoverability-check.mjs closure --changed-file <path> --json. The closing report must cite the real claw search ... --json and claw inspect ... --json command evidence plus the discovered artifact, or mark the work PARTIAL/BLOCKED.
11. Validate with the route's listed tests or add a focused fixture/E2E when the route did not have one. Mark unavailable physical/provider validation as EXTERNAL PENDING, separate from defects.

Constraints

• Do not rely on a hand-drawn diagram as source of truth.
• Do not touch adjacent owners just because they are connected; inspect the edge type and contract first.
• Relay is a critical remote-safe surface, not the canonical local API.
• A route is incomplete if any step lacks a registered node, contract, validation, or explicit gap.
• A route or surface without surfaceNarrative is incomplete unless it is already captured as bounded pre-existing debt in the narrative baseline.
• A route or surface without resourceContract is incomplete unless it is already captured as bounded pre-existing debt in the resource-contract baseline.
• A closure-gated route or surface change is incomplete if claw search or claw inspect cannot discover the affected registered artifact or route.