docs: refresh agent memory guardrails (raphaeltm#1114)

Author: raphaeltm

.claude/rules/09-task-tracking.md

@@ -88,6 +88,10 @@ Verification must confirm all of:
 
 If the session failed immediately, never started, launched under the wrong profile, or lost critical constraints, do not wait on it. Re-dispatch with the corrected task/profile or report the dispatch failure with exact status evidence.
 
+If the requested specialist/profile is not available or cannot be observed from the dispatch result, do not assume it worked. Use the cheapest available status/details check, record what is missing, and either re-dispatch with an explicit supported profile or ask for clarification. A generic task running under the platform default is not a substitute for a requested reviewer, specialist, or constrained profile.
+
+When a dispatched task returns, treat its output as usable only after checking that it came from the intended task/profile and respected the original constraints. If the result was produced by the wrong profile, ignored `draft PR`/`do not merge`, dropped the requested branch, or skipped `/do` when required, document the mismatch and do not use it as validation evidence.
+
 ### Why This Matters
 
 Without the `/do` instruction, a dispatched agent may skip critical phases like staging verification, specialist review, or proper PR creation. The `/do` workflow enforces all quality gates defined in this project's rules.

.claude/rules/38-agent-feedback-and-memory.md

@@ -0,0 +1,58 @@
+# Agent Feedback, Memory, and Idea Hygiene
+
+## Why This Exists
+
+SAM agents have repeatedly lost useful human feedback by leaving it only in transient conversations, or by letting stale ideas stay indistinguishable from current plans. Knowledge, ideas, and policies are product surfaces for agents. Treat them as maintained state.
+
+## Before Key Decisions
+
+Search project knowledge before making decisions that depend on remembered context:
+
+| Decision | Search |
+| -------- | ------ |
+| Content, blog, launch copy | `ContentStyle` |
+| Libraries, tooling, code-quality tradeoffs | `CodeQuality` |
+| UI layout or interaction direction | `User`, `mobile`, and relevant surface names |
+| Architecture or runtime design | `Architecture` |
+| Pricing, billing, go-to-market | `BusinessStrategy` |
+
+If a project policy applies, treat it as a hard gate unless it is explicitly categorized as a preference.
+
+## When to Update Memory
+
+Update durable memory when any of these happen:
+
+- Raphaël explicitly states a preference, correction, or "do not do X" rule.
+- Work verifies that a stored observation is still accurate.
+- Work proves that a stored observation is stale, superseded, or too broad.
+- A repeated agent failure reveals a durable workflow rule that would prevent future frustration.
+
+Do not save facts that are already obvious from the codebase, ephemeral task details, or speculation that has not been verified.
+
+## Idea Maintenance
+
+When reviewing or touching ideas:
+
+1. Mark an idea completed only when the implementation is merged or otherwise verifiably shipped on the intended branch.
+2. If work exists only on an unmerged branch or draft PR, append a note with the branch/PR and leave the idea open.
+3. If an idea has become a narrower follow-up, update the title/content so future agents do not execute the stale original plan.
+4. If a prototype informed a real product change, record which production surface still needs validation; prototype routes are not the deliverable by default.
+5. Include concrete evidence in idea updates: merged commit, PR number, task ID, branch, or file path.
+
+## Knowledge vs Ideas vs Policies
+
+- **Knowledge** captures remembered facts and preferences agents should apply during work.
+- **Ideas** capture possible or planned product/engineering work.
+- **Policies** capture project-wide rules, constraints, delegation settings, and strong preferences.
+
+Do not turn speculative ideas into policies. Do not use knowledge to replace a task or implementation checklist.
+
+## Validation Checklist
+
+Before finishing a memory/config maintenance task:
+
+- [ ] New guidance points to existing detailed rules instead of duplicating large sections.
+- [ ] All added rule links and referenced files exist.
+- [ ] Ideas marked completed have merged/shipped evidence.
+- [ ] Unmerged, draft, or human-review work remains visibly open.
+- [ ] No duplicate knowledge observation was added when an existing active observation already covers it.

.codex/prompts/workflow.md

@@ -134,9 +134,9 @@ REPEAT until all subtasks are complete or failed:
 - **ALWAYS use `sleep` via the Bash tool**, not any other waiting mechanism. The Bash tool execution is what registers as session activity.
 - **ALWAYS re-read `.workflow-state.md` before each poll cycle.** Context compaction may have erased your memory of previous polls.
 - **ALWAYS call `update_task_status`** after each poll. This is your progress report AND your activity signal.
-- **If a subtask has been in_progress for more than 30 minutes** (6 poll cycles), send it a check-in message via `send_message_to_subtask` asking for a status update.
-- **If a subtask has been in_progress for more than 60 minutes** (12 poll cycles), flag it in your status update as potentially stuck.
-- **Maximum poll count: 200** (about 16 hours). If you hit this limit, report the timeout and stop.
+- **If a subtask has been in_progress for more than 30 minutes** (6 poll cycles), inspect available evidence and optionally send a check-in message via `send_message_to_subtask` asking for a status update.
+- **Do not treat duration alone as a stall.** Some `/do` subtasks legitimately run for multiple hours. Only report a subtask as stuck, retry it, or stop it when you have concrete failure evidence, impossible progress, an explicit blocker, or human instruction.
+- **Maximum poll count: 200** (about 16 hours). If you hit this limit, report the timeout with the evidence checked and stop.
 
 ### What to Do If Context Feels Fuzzy
 

AGENTS.md

@@ -50,6 +50,21 @@ Skills are invoked with `$skill-name` (Codex) or dispatched as subagents (Claude
 - `$do` — End-to-end task executor: research → plan → implement → review → staging → PR
 - `$workflow` — Multi-step workflow orchestration with foreground polling
 
+## Operational Guardrails
+
+These are Codex-facing reminders for recurring SAM workflow failures. The durable source of truth remains `CLAUDE.md` and `.claude/rules/*.md`.
+
+| Situation | Do |
+| --------- | -- |
+| Starting SAM-managed work | Call the SAM MCP `get_instructions` tool first and apply returned knowledge and policy directives. |
+| Debugging a live issue Raphaël is seeing | Inspect production evidence first unless the issue is explicitly about staging or a branch verification. Use staging for PR validation and new-change verification. |
+| Debugging staging or deployment behavior | Query Cloudflare state/logs before guessing or redeploying. Staging deploys are slow; CF API checks are fast. |
+| User asks for "subtasks" | Use SAM `dispatch_task` for visible delegated work. |
+| User asks for "local subagents" | Use local Claude/Codex subagents for in-session critique or reasoning, not SAM-dispatched tasks. |
+| Dispatching a SAM task | Verify the task started, the title matches, the requested profile/agent is observable, and critical constraints such as `/do`, branch, `draft PR`, or `do not merge` survived. |
+| Draft PR / do-not-merge request | Preserve the constraint in task state and PR wording. Stop at the draft/open PR unless Raphaël later authorizes readiness or merge. |
+| Incidental bug found | If it is not blocking and not a small adjacent fix, file a backlog task with reproduction/evidence and continue the assigned work. |
+
 ## Prompts
 
 Workflow prompts in `.codex/prompts/` (Codex) and `.claude/commands/` (Claude Code):

CLAUDE.md

@@ -201,6 +201,8 @@ When you discover bugs or errors during testing — even if unrelated to your cu
 2. Include: Problem description, Context (where/when discovered), Acceptance Criteria checklist
 3. Continue with your current work
 
+If the bug is blocking the current task or is a small adjacent fix, fix it in the current branch with evidence. Otherwise file it and keep the assigned work moving.
+
 ## Troubleshooting
 
 - **Build errors**: Run builds in dependency order (see Build Order above)
@@ -214,6 +216,8 @@ Tasks tracked as markdown in `tasks/` (backlog -> active -> archive). See `tasks
 
 **Dispatching tasks**: When dispatching tasks to other agents, always instruct them to use the `/do` skill, then verify the task actually started with the requested profile and title. Do not wait on failed, queued, missing, or wrong-profile sessions. See `.claude/rules/09-task-tracking.md`.
 
+**Memory and ideas**: Keep SAM knowledge, ideas, and policies current when human feedback or shipped work changes what future agents should believe. Do not mark ideas complete unless they are merged or otherwise verifiably shipped. See `.claude/rules/38-agent-feedback-and-memory.md`.
+
 ## Strategy Planning
 
 Strategic planning artifacts live in `strategy/` — see `strategy/README.md` for full structure.