docs(agents): fix stale references in architect.md and coordinator.md

architect.md:
- ADR-009 §"What this framework is NOT" → ADR-032 — the pointer was an
  alknet-numbering leftover; in-crate ADR-009 is BiStream-as-handler-leaf,
  the door-framework section lives in ADR-032. Same collision class the
  docs pass (5f019c0) fixed in the spec.
- OQ status list now includes deferred(scope), deferred(unclear),
  dissolved — matching the tracker's actual vocabulary and this prompt's
  own Safe-Exit section (they contradicted each other).
- tasks/architecture/ softened: this repo has no tasks/ dir; the OQ
  "Blocked on:" field is the tracker of record.
- Deferral-blocker examples re-keyed off alknet ("alknet-http crate
  spec" → the composition-layer crate spec, OQ-43; "alknet-agent crate
  spec" → "the agent crate's spec") — examples were teaching the exact
  repo-pinned blocker class just cleaned out of the OQs.

coordinator.md:
- Example spawn template said "implementation specialist for
  @alkdev/alknet" with alknet-era constraints ("feature flags for
  transports (tls, iroh, acme)") — agents copying the template would
  re-introduce the residue into every spawned prompt. Now names
  @alkdev/alkcall and points at AGENTS.md convention 11 (lean base
  crate, no quinn/iroh unless the feature is on).

Verification: repo-wide residue sweep — alknet mentions survive only in
AGENTS.md's intentional provenance/historical framing; no stale ADR
number pointers remain in .opencode/agents/; architect.md's internal
sections (Safe Exit, anti-patterns, status vocabulary) are mutually
consistent.
This commit is contained in:
glm-5.3-flash committed 2026-10-13 11:16:31 +00:00
1 parent f93ac3792d
commit ff07f92bdb
2 files changed
+11 -7

No files matched your search

+8 -4
View File
@@ -99,7 +99,8 @@ organized by theme. Each question has:
- **OQ-ID** (OQ-01, OQ-02, ...) — stable reference - **OQ-ID** (OQ-01, OQ-02, ...) — stable reference
- **Origin** — which spec doc(s) the question appeared in - **Origin** — which spec doc(s) the question appeared in
- **Status** — open, resolved, partially resolved - **Status** — open, resolved, partially resolved, deferred(scope),
deferred(unclear), dissolved
- **Priority** — high, medium, low - **Priority** — high, medium, low
- **Resolution** — when resolved, what was decided and which ADR addresses it - **Resolution** — when resolved, what was decided and which ADR addresses it
- **Cross-references** — related OQs and ADRs - **Cross-references** — related OQs and ADRs
@@ -190,6 +191,8 @@ When you encounter a decision that genuinely can't be made:
1. Mark the OQ as `deferred(scope)` with a concrete blocking condition 1. Mark the OQ as `deferred(scope)` with a concrete blocking condition
2. Create a blocker task in `tasks/architecture/` naming the dependency 2. Create a blocker task in `tasks/architecture/` naming the dependency
(where the project tracks tasks that way — otherwise the OQ's
`Blocked on:` field is the tracker of record)
3. Continue to decisions that *can* be made — do not stall on one question 3. Continue to decisions that *can* be made — do not stall on one question
### 6. Request Architecture Review ### 6. Request Architecture Review
@@ -274,7 +277,7 @@ Door type classifies **reversal cost** (one-way vs two-way), not
urgency. A two-way door is a decision you make now and can revert urgency. A two-way door is a decision you make now and can revert
later — not a decision to defer. Using "it's a two-way door" as a later — not a decision to defer. Using "it's a two-way door" as a
reason to leave a decision unmade conflates reversal cost with reason to leave a decision unmade conflates reversal cost with
decision-making. See ADR-009 §"What this framework is NOT" for the decision-making. See ADR-032 §"What this framework is NOT" for the
full rationale. full rationale.
Architecture decisions are the architect's, regardless of door type. Architecture decisions are the architect's, regardless of door type.
@@ -329,7 +332,8 @@ A decision should be `deferred(scope)` when:
- The use case isn't concrete (e.g., "we don't know what the agent crate - The use case isn't concrete (e.g., "we don't know what the agent crate
will need from the call protocol") will need from the call protocol")
- The options depend on something that doesn't exist yet (e.g., - The options depend on something that doesn't exist yet (e.g.,
"depends on the alknet-http crate spec") "depends on the composition-layer crate spec — owner and shape not
committed, see OQ-43")
- The trade-off requires data that can only come from implementation - The trade-off requires data that can only come from implementation
(e.g., "need performance benchmarks to choose between X and Y") (e.g., "need performance benchmarks to choose between X and Y")
- The decision is genuinely not needed for the current scope (e.g., "the - The decision is genuinely not needed for the current scope (e.g., "the
@@ -373,7 +377,7 @@ A decision should be `deferred(unclear)` when:
(implies it's decided). (implies it's decided).
2. **State the blocking condition** (`deferred(scope)`) or 2. **State the blocking condition** (`deferred(scope)`) or
**investigation target** (`deferred(unclear)`) — what specific thing **investigation target** (`deferred(unclear)`) — what specific thing
would unblock this? Be concrete: "blocked on: alknet-agent crate spec would unblock this? Be concrete: "blocked on: the agent crate's spec
exists" or "investigation: work through 2+ example outbound-dial use exists" or "investigation: work through 2+ example outbound-dial use
cases (hub→worker, worker→hub) to see how verifier-selection + cases (hub→worker, worker→hub) to see how verifier-selection +
provider + connector compose." provider + connector compose."
+3 -3
View File
@@ -191,7 +191,7 @@ also include:
Example prompt template: Example prompt template:
``` ```
You are an implementation specialist for the @alkdev/alknet project. You are an implementation specialist for the @alkdev/alkcall project.
Your task: {{task}} Your task: {{task}}
@@ -204,11 +204,11 @@ Your task: {{task}}
7. Push: git push origin $(git branch --show-current) 7. Push: git push origin $(git branch --show-current)
8. Notify: worktree({action: "notify", args: {message: "Task completed: {{task}}. <brief summary>", level: "info"}}) 8. Notify: worktree({action: "notify", args: {message: "Task completed: {{task}}. <brief summary>", level: "info"}})
Key project constraints (@alkdev/alknet): Key project constraints (@alkdev/alkcall):
- Rust: use cargo build, cargo clippy, cargo fmt, cargo test - Rust: use cargo build, cargo clippy, cargo fmt, cargo test
- No comments in code - No comments in code
- anyhow::Result for application errors, thiserror for library error types - anyhow::Result for application errors, thiserror for library error types
- Feature flags for transports (tls, iroh, acme) - Base crate compiles lean (no quinn/iroh unless the feature is on — see AGENTS.md convention 11)
- Async via tokio runtime - Async via tokio runtime
- No panics in library code - No panics in library code
``` ```