Update agent workflow guardrails from two-week audit

[simple-agent-manager]

Summary

• Add read-only investigation/status guidance so PR/task history questions stay in-session unless the user asks for changes.
• Add failed SAM task retry guardrails: inspect failed sessions and active duplicates before redispatching the same prompt.
• Add profile setup guidance to avoid multiple provider-specific built-in default profiles and prefer guided setup/templates.
• Mirror retry diagnosis guidance in Claude and Codex workflow prompts.

Knowledge, Policy, And Idea Updates

Updated SAM durable state outside the repo:

• Added policies for read-only status/investigation handling and failed duplicate task retry diagnosis.
• Added profile-default preference policy.
• Updated ideas for PR 1172 and PR 1173 to reflect open PR state, not completed/shipped state.
• Updated the profile wizard idea to align with the no-default-profile-clutter direction.
• Created linked idea 01KT3XKJ308ZJRS30V8FNZN6ZD for dedupe/diagnose failed SAM task starts.
• Added knowledge for merged PR 1177 public workspace ports and PR 1183 transient ACP prompt retry behavior.

Local Subagent Critique

I attempted three full-context local subagents first, but all stalled and were shut down. I then spawned two narrower local critique agents; both completed and converged on the scoped approach used here: update existing task/workflow guardrails, avoid a new rule file, keep PR-specific state in ideas, and phrase profile guidance as setup/onboarding guidance.

Validation

• pnpm lint
• pnpm typecheck
• pnpm test
• Additional validation run: pnpm exec prettier --check AGENTS.md CLAUDE.md .claude/rules/09-task-tracking.md .codex/prompts/workflow.md .claude/commands/workflow.md

Staging Verification (REQUIRED for all code changes — merge-blocking)

N/A: docs-only — this PR modifies only agent instruction files (.claude/rules/*.md, .claude/commands/*.md, .codex/prompts/*.md, AGENTS.md, CLAUDE.md). No runtime code (.ts, .tsx, .go) was changed.

UI Compliance Checklist (Required for UI changes)

N/A: no UI changes.

End-to-End Verification (Required for multi-component changes)

N/A: no multi-component code changes. This PR updates agent instruction documents only.

Data Flow Trace

N/A: docs-only change.

Untested Gaps

N/A: docs-only change.

Post-Mortem (Required for bug fix PRs)

N/A: not a bug fix. This PR adds guardrails based on a two-week audit of recurring agent workflow failures.

Specialist Review Evidence (Required for agent-authored PRs)

• All dispatched reviewers completed and findings addressed before merge

Reviewer	Status	Outcome
doc-sync-validator	PASS	Guardrail additions are consistent with existing CLAUDE.md and .claude/rules/ content; no contradictions found

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

N/A: internal agent instruction update based on audit of recent workflow failures.

Codebase Impact Analysis

Affected files: CLAUDE.md, AGENTS.md, .claude/rules/09-task-tracking.md, .claude/commands/workflow.md, .codex/prompts/workflow.md. No runtime code paths affected.

Documentation & Specs

Updated agent instruction files directly. No public docs changes needed — these files are agent-facing, not user-facing.

Constitution & Risk Check

Checked Principle XI: no hardcoded values introduced. All guidance is behavioral (agent workflow rules), not configuration.

Notes

This is intentionally a draft PR. Do not merge until Raphaël reviews it.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud