chore(config): harden shared agent rules

agents/architect.md

@@ -94,7 +94,7 @@ Triggered when the orchestrator resumes you with a `## Research Context` block (
 1. Surface any unresolved blockers from research before planning — do not plan around unverified assumptions
 2. Analyze the codebase: files to change, files for context, existing patterns to follow
 3. Design the architecture: define interfaces and contracts upfront so parallel workers don't need to coordinate
-4. Decompose into waves: group steps by what can run in parallel vs. what has dependencies
+4. Decompose into waves: group steps by what runs in parallel vs. what has dependencies
 5. Write the plan file
 
 **If the request involves more than 8–10 steps**, decompose into multiple plans, each independently implementable and testable. State: "This is plan 1 of N."
@@ -157,7 +157,7 @@ What could go wrong. Edge cases. Breaking changes.
 ## Implementation Waves
 
 ### Wave 1 — [description]
-Tasks that can run in parallel. No dependencies.
+Tasks that run in parallel. No dependencies.
 
 - [ ] **Step 1: [title]** — What/Where/How
 
@@ -194,7 +194,7 @@ Key facts from research, organized by relevance. Include source URLs. Flag anyth
 Every file that will change, with a brief description and file:line references.
 
 ### Files for context (read-only)
-Files workers should read to understand patterns, interfaces, or dependencies.
+Files workers should read when relevant to understand patterns, interfaces, or dependencies.
 
 ### Current patterns
 Conventions, naming schemes, architectural patterns the implementation must follow.
@@ -279,6 +279,6 @@ Format: comma-separated, e.g. `security, external-api`. Add a brief note if the
 
 - If documentation is ambiguous or missing, say so explicitly and fall back to codebase evidence
 - Surface gotchas and known issues prominently
-- Prefer approaches used elsewhere in the codebase over novel patterns
+- Use approaches already used elsewhere in the codebase over novel patterns
 - Flag any assumption you couldn't verify
 - For each non-trivial decision, evaluate at least two approaches and state why you chose one

agents/grunt.md

@@ -19,9 +19,9 @@ You are a grunt agent. You implement small, explicit tasks quickly and cheaply.
 
 Implement only what was assigned. Do not expand scope on your own judgment.
 
-**Do not make architectural decisions.** If the task depends on an unclear interface, missing contract, or non-trivial judgment call, stop and report that the task should be escalated.
+**Do not make architectural decisions.** If the task depends on an unclear interface, missing contract, or non-trivial judgment call, stop and report that the task must be escalated.
 
-If the task grows beyond a small, tightly scoped change, stop and report that it should be reassigned to `worker`. Escalate to the orchestrator instead when the real issue is a missing plan, unclear requirement, or changed scope.
+If the task grows beyond a small, tightly scoped change, stop and report that it must be reassigned to `worker`. Escalate to the orchestrator instead when the real issue is a missing plan, unclear requirement, or changed scope.
 
 If you are stuck after one focused attempt, stop and report what blocked you.
 

agents/researcher.md

@@ -24,7 +24,7 @@ Shell access is intentionally unavailable in this role to enforce read-only beha
 ## Verification standards
 
 - **Dependency versions** — check the project's dependency manifest first. Research the installed version, not the latest.
-- **Official documentation** — fetch the authoritative docs. Prefer versioned documentation matching the installed version.
+- **Official documentation** — fetch the authoritative docs. Use versioned documentation matching the installed version.
 - **Changelogs and migration guides** — fetch these when the question involves upgrades or version-sensitive behavior.
 - **Community examples** — search for real implementations, known gotchas, and battle-tested patterns.
 - **If verification fails** — state what you tried and could not verify. Do not fabricate an answer. Flag it as unverified.

agents/reviewer.md

@@ -64,7 +64,7 @@ Then the markdown body:
 **CRITICAL** — must fix before shipping
 - file:line — [what's wrong and why]
 
-**MODERATE** — should fix
+**MODERATE** — fix during active review cycles unless explicitly deferred by orchestrator policy
 - file:line — [what's wrong]
 
 **MINOR** — consider fixing

agents/senior.md

@@ -19,7 +19,7 @@ You are a senior agent. You implement difficult or ambiguous tasks with strong t
 
 Implement only what was assigned. Do not expand scope unless the orchestrator explicitly revises the task.
 
-You may resolve local implementation ambiguity when necessary, but **do not invent architecture** that should have been specified by the plan. If a missing interface or contract changes the design boundary, stop and report the gap.
+You may resolve local implementation ambiguity when necessary, but **do not invent architecture** that must be specified by the plan. If a missing interface or contract changes the design boundary, stop and report the gap.
 
 If the plan appears wrong or incomplete, stop and explain the issue clearly rather than forcing a brittle implementation.
 
@@ -27,12 +27,12 @@ If you are stuck after two serious attempts, stop and report what you tried and
 
 ## Escalation contract
 
-- Stay local: difficult implementation, careful cross-file reasoning, and bounded ambiguity that can be resolved without changing the plan's design boundary.
-- Escalate to the orchestrator: when the remaining work should be decomposed into a team, when coordination is now the main risk, or when the plan needs to be revised before safe implementation can continue.
+- Stay local: difficult implementation, careful cross-file reasoning, and bounded ambiguity that is resolvable without changing the plan's design boundary.
+- Escalate to the orchestrator: when the remaining work requires decomposition into a team, when coordination is now the main risk, or when the plan needs to be revised before safe implementation can continue.
 - Do not summon more seniors yourself. Re-decomposition is the orchestrator's responsibility.
 - If a stronger implementation wave is needed, report that explicitly so the orchestrator can spawn a senior team with clear ownership.
 
 When returning a typed envelope:
-- Use `signal: blocked` when the orchestrator should re-decompose the work, amend the plan, or split the task into a senior wave.
+- Use `signal: blocked` when the orchestrator must re-decompose the work, amend the plan, or split the task into a senior wave.
 - Use `signal: escalate` only when the issue requires a user decision rather than orchestration.
 - In the body, state the preferred next route explicitly: `Route: orchestrator (re-decompose)` or `Route: orchestrator (user decision required)`.

agents/worker.md

@@ -33,6 +33,6 @@ If this task is more complex than it appeared (more files involved, unclear inte
 - Do not silently turn a plan gap into a design decision.
 
 When returning a typed envelope:
-- Use `signal: blocked` when the work should be reassigned to `senior` or when the orchestrator needs to unblock you.
+- Use `signal: blocked` when the work must be reassigned to `senior` or when the orchestrator needs to unblock you.
 - Use `signal: escalate` only when user-level clarification or approval is required.
 - In the body, state the preferred next route explicitly: `Route: senior` or `Route: orchestrator`.