Token economics: see, bound, and prove what a run costs its own context window

.agentfactory/agents/design-plan-impl/.claude/settings.json

@@ -13,6 +13,37 @@
             "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af containment-check"
           }
         ]
+      },
+      {
+        "matcher": "Task|Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af dispatch-admit"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Task|Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af subagent-observe"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af dispatch-retire"
+          }
+        ]
       }
     ],
     "SessionStart": [
@@ -21,7 +52,15 @@
         "hooks": [
           {
             "type": "command",
-            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af prime --hook && af mail check --inject && af memory check --inject"
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af prime --hook"
+          },
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af mail check --inject"
+          },
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af memory check --inject"
           }
         ]
       }

.agentfactory/agents/design-plan-impl/CLAUDE.md

@@ -54,6 +54,7 @@ This formula guides an agent through the design-plan-impl Mode A process:
 | Extracting IMPLREADMEs after the outline | Mode B belongs to design-phase-impl — STOP after the outline is verified and pushed |
 | Creating phases that aren't self-contained | Each phase must stand alone |
 | Numbering phases to match design doc when dependencies differ | Number by dependency order |
+| Inflating phase COUNT — one phase per deliverable/domain when they share a service and PR | Right-size: collapse to the fewest phases hard boundaries allow (phase-3 op 9); a net-deletion or single-service change stays 1–2 phases |
 | Planning for one environment but not the other | Deployment audit catches parity gaps |
 | Routing all phases to *implement | Classify workstreams; route to specialized skills or agents |
 | Assuming a specific file exists | Locate design artifacts from the merged input branch's diff, not guessed paths |
@@ -64,7 +65,6 @@ Every step produces a file artifact at a known path. `af done` is forbidden
 until the artifact exists and contains the required content. A fidelity gate
 runs after every response and will TERMINATE YOU if the step's directives are skipped.
 YOUR identity exists and DEPENDS ON YOU to FAITHFULLY EXECUTE formula steps.
-.
 
 You are an autonomous agent that acts independently without waiting for user input.
 
@@ -202,6 +202,7 @@ This formula guides an agent through the design-plan-impl Mode A process:
 | Extracting IMPLREADMEs after the outline | Mode B belongs to design-phase-impl — STOP after the outline is verified and pushed |
 | Creating phases that aren't self-contained | Each phase must stand alone |
 | Numbering phases to match design doc when dependencies differ | Number by dependency order |
+| Inflating phase COUNT — one phase per deliverable/domain when they share a service and PR | Right-size: collapse to the fewest phases hard boundaries allow (phase-3 op 9); a net-deletion or single-service change stays 1–2 phases |
 | Planning for one environment but not the other | Deployment audit catches parity gaps |
 | Routing all phases to *implement | Classify workstreams; route to specialized skills or agents |
 | Assuming a specific file exists | Locate design artifacts from the merged input branch's diff, not guessed paths |
@@ -223,7 +224,7 @@ YOUR identity exists and DEPENDS ON YOU to FAITHFULLY EXECUTE formula steps.
 
 ## Startup Protocol
 
-1. Check mail for pending instructions (`af mail inbox`)
+1. Act on the mail delivered at session start (`af mail inbox` lists ids for `af mail delete`)
 2. Act on any hooked work or queued tasks
 3. Begin autonomous execution — monitor, patrol, and act independently
 
@@ -240,7 +241,7 @@ YOUR identity exists and DEPENDS ON YOU to FAITHFULLY EXECUTE formula steps.
 Your learnings vault at `.agentfactory/memory/design-plan-impl/` outlives this session, your worktree, and every teardown path — it is the one place durable state survives without operator archaeology.
 
 - Record a learning the moment you earn it: `af memory add -s "<subject>" -m "<what you learned>" --type gotcha` (types: `gotcha`, `model-behavior`, `ops`, `outcome`, `improvement`).
-- Read before you re-derive: `af memory list`, then `af memory show <id>` for the full note. `af memory check --inject` already serves your own notes at session start.
+- Read before you re-derive: `af memory list`, then `af memory show <id>` for the full note. Your top notes (up to 5, ≤ 4 KB) are injected at session start by `af memory check --inject`; `af memory list` shows the rest.
 - Close the loop when a learning lands somewhere durable: `af memory graduate <id> --to commit:<sha>` (also `issue#N`, `pr#N`, `doc:<path>`, `formula:<name>`). When it stops being true: `af memory expire <id>`.
 - Notes are append-only and there is no delete verb — graduating or expiring one stops it costing you context without destroying the record.
 - `af memory status` reports what the vault holds and what is due for graduation.

.agentfactory/agents/design-v3/.claude/settings.json

@@ -13,6 +13,37 @@
             "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af containment-check"
           }
         ]
+      },
+      {
+        "matcher": "Task|Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af dispatch-admit"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Task|Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af subagent-observe"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af dispatch-retire"
+          }
+        ]
       }
     ],
     "SessionStart": [
@@ -21,7 +52,15 @@
         "hooks": [
           {
             "type": "command",
-            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af prime --hook && af mail check --inject && af memory check --inject"
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af prime --hook"
+          },
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af mail check --inject"
+          },
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af memory check --inject"
           }
         ]
       }

.agentfactory/agents/design-v3/CLAUDE.md

@@ -66,7 +66,6 @@ Every step produces a file artifact at a known path. `af done` is forbidden
 until the artifact exists and contains the required content. A fidelity gate
 runs after every response and will TERMINATE YOU if the step's directives are skipped.
 YOUR identity exists and DEPENDS ON YOU to FAITHFULLY EXECUTE formula steps.
-.
 
 You are an autonomous agent that acts independently without waiting for user input.
 
@@ -227,7 +226,7 @@ YOUR identity exists and DEPENDS ON YOU to FAITHFULLY EXECUTE formula steps.
 
 ## Startup Protocol
 
-1. Check mail for pending instructions (`af mail inbox`)
+1. Act on the mail delivered at session start (`af mail inbox` lists ids for `af mail delete`)
 2. Act on any hooked work or queued tasks
 3. Begin autonomous execution — monitor, patrol, and act independently
 
@@ -244,7 +243,7 @@ YOUR identity exists and DEPENDS ON YOU to FAITHFULLY EXECUTE formula steps.
 Your learnings vault at `.agentfactory/memory/design-v3/` outlives this session, your worktree, and every teardown path — it is the one place durable state survives without operator archaeology.
 
 - Record a learning the moment you earn it: `af memory add -s "<subject>" -m "<what you learned>" --type gotcha` (types: `gotcha`, `model-behavior`, `ops`, `outcome`, `improvement`).
-- Read before you re-derive: `af memory list`, then `af memory show <id>` for the full note. `af memory check --inject` already serves your own notes at session start.
+- Read before you re-derive: `af memory list`, then `af memory show <id>` for the full note. Your top notes (up to 5, ≤ 4 KB) are injected at session start by `af memory check --inject`; `af memory list` shows the rest.
 - Close the loop when a learning lands somewhere durable: `af memory graduate <id> --to commit:<sha>` (also `issue#N`, `pr#N`, `doc:<path>`, `formula:<name>`). When it stops being true: `af memory expire <id>`.
 - Notes are append-only and there is no delete verb — graduating or expiring one stops it costing you context without destroying the record.
 - `af memory status` reports what the vault holds and what is due for graduation.

.agentfactory/agents/design-v7/.claude/settings.json

@@ -13,6 +13,37 @@
             "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af containment-check"
           }
         ]
+      },
+      {
+        "matcher": "Task|Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af dispatch-admit"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Task|Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af subagent-observe"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af dispatch-retire"
+          }
+        ]
       }
     ],
     "SessionStart": [
@@ -21,7 +52,15 @@
         "hooks": [
           {
             "type": "command",
-            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af prime --hook && af mail check --inject && af memory check --inject"
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af prime --hook"
+          },
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af mail check --inject"
+          },
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af memory check --inject"
           }
         ]
       }

.agentfactory/agents/design-v7/CLAUDE.md

@@ -60,6 +60,8 @@ that cannot see each other's output.
 | Context filling up | Use `af handoff` to cycle to fresh session |
 | Blocked on external | Mail Supervisor, mark yourself stuck |
 | Scope unclear | Default to 'medium' unless problem is obviously small or large |
+| `af done` says "no active formula (missing .runtime/hooked_formula)" | Your shell's cwd left the agent directory (a `cd` earlier in the same command chain). Run `af done` and `af prime` from the agent directory; wrap git work in a subshell: `( cd "$AF_WORKTREE" && git ... ) && af done` |
+| WORKTREE_CONTAINMENT mail after reading factory-root data | Runtime data that lives only at the factory root (`.agentfactory/telemetry/`, `models.json`, `agents.json`) is read by ABSOLUTE path (`cat /path/...`), never by `cd` — the containment check flags any cwd outside your worktree. Acknowledge the mail and delete it |
 
 ## Anti-Patterns to Avoid
 
@@ -83,7 +85,6 @@ Every step produces a file artifact at a known path. `af done` is forbidden
 until the artifact exists and contains the required content. A fidelity gate
 runs after every response and will TERMINATE YOU if the step's directives are skipped.
 YOUR identity exists and DEPENDS ON YOU to FAITHFULLY EXECUTE formula steps.
-.
 
 You are an autonomous agent that acts independently without waiting for user input.
 
@@ -228,6 +229,8 @@ that cannot see each other's output.
 | Context filling up | Use `af handoff` to cycle to fresh session |
 | Blocked on external | Mail Supervisor, mark yourself stuck |
 | Scope unclear | Default to 'medium' unless problem is obviously small or large |
+| `af done` says "no active formula (missing .runtime/hooked_formula)" | Your shell's cwd left the agent directory (a `cd` earlier in the same command chain). Run `af done` and `af prime` from the agent directory; wrap git work in a subshell: `( cd "$AF_WORKTREE" && git ... ) && af done` |
+| WORKTREE_CONTAINMENT mail after reading factory-root data | Runtime data that lives only at the factory root (`.agentfactory/telemetry/`, `models.json`, `agents.json`) is read by ABSOLUTE path (`cat /path/...`), never by `cd` — the containment check flags any cwd outside your worktree. Acknowledge the mail and delete it |
 
 ## Anti-Patterns to Avoid
 
@@ -262,7 +265,7 @@ YOUR identity exists and DEPENDS ON YOU to FAITHFULLY EXECUTE formula steps.
 
 ## Startup Protocol
 
-1. Check mail for pending instructions (`af mail inbox`)
+1. Act on the mail delivered at session start (`af mail inbox` lists ids for `af mail delete`)
 2. Act on any hooked work or queued tasks
 3. Begin autonomous execution — monitor, patrol, and act independently
 
@@ -279,7 +282,7 @@ YOUR identity exists and DEPENDS ON YOU to FAITHFULLY EXECUTE formula steps.
 Your learnings vault at `.agentfactory/memory/design-v7/` outlives this session, your worktree, and every teardown path — it is the one place durable state survives without operator archaeology.
 
 - Record a learning the moment you earn it: `af memory add -s "<subject>" -m "<what you learned>" --type gotcha` (types: `gotcha`, `model-behavior`, `ops`, `outcome`, `improvement`).
-- Read before you re-derive: `af memory list`, then `af memory show <id>` for the full note. `af memory check --inject` already serves your own notes at session start.
+- Read before you re-derive: `af memory list`, then `af memory show <id>` for the full note. Your top notes (up to 5, ≤ 4 KB) are injected at session start by `af memory check --inject`; `af memory list` shows the rest.
 - Close the loop when a learning lands somewhere durable: `af memory graduate <id> --to commit:<sha>` (also `issue#N`, `pr#N`, `doc:<path>`, `formula:<name>`). When it stops being true: `af memory expire <id>`.
 - Notes are append-only and there is no delete verb — graduating or expiring one stops it costing you context without destroying the record.
 - `af memory status` reports what the vault holds and what is due for graduation.

.agentfactory/agents/design/.claude/settings.json

@@ -13,6 +13,37 @@
             "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af containment-check"
           }
         ]
+      },
+      {
+        "matcher": "Task|Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af dispatch-admit"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Task|Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af subagent-observe"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af dispatch-retire"
+          }
+        ]
       }
     ],
     "SessionStart": [
@@ -21,7 +52,15 @@
         "hooks": [
           {
             "type": "command",
-            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af prime --hook && af mail check --inject && af memory check --inject"
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af prime --hook"
+          },
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af mail check --inject"
+          },
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$HOME/bin:$PATH\" && af memory check --inject"
           }
         ]
       }

.agentfactory/agents/design/CLAUDE.md

@@ -33,7 +33,6 @@ Every step produces a file artifact at a known path. `af done` is forbidden
 until the artifact exists and contains the required content. A fidelity gate
 runs after every response and will TERMINATE YOU if the step's directives are skipped.
 YOUR identity exists and DEPENDS ON YOU to FAITHFULLY EXECUTE formula steps.
-.
 
 You are an autonomous agent that acts independently without waiting for user input.
 
@@ -145,7 +144,7 @@ YOUR identity exists and DEPENDS ON YOU to FAITHFULLY EXECUTE formula steps.
 
 ## Startup Protocol
 
-1. Check mail for pending instructions (`af mail inbox`)
+1. Act on the mail delivered at session start (`af mail inbox` lists ids for `af mail delete`)
 2. Act on any hooked work or queued tasks
 3. Begin autonomous execution — monitor, patrol, and act independently
 
@@ -162,7 +161,7 @@ YOUR identity exists and DEPENDS ON YOU to FAITHFULLY EXECUTE formula steps.
 Your learnings vault at `.agentfactory/memory/design/` outlives this session, your worktree, and every teardown path — it is the one place durable state survives without operator archaeology.
 
 - Record a learning the moment you earn it: `af memory add -s "<subject>" -m "<what you learned>" --type gotcha` (types: `gotcha`, `model-behavior`, `ops`, `outcome`, `improvement`).
-- Read before you re-derive: `af memory list`, then `af memory show <id>` for the full note. `af memory check --inject` already serves your own notes at session start.
+- Read before you re-derive: `af memory list`, then `af memory show <id>` for the full note. Your top notes (up to 5, ≤ 4 KB) are injected at session start by `af memory check --inject`; `af memory list` shows the rest.
 - Close the loop when a learning lands somewhere durable: `af memory graduate <id> --to commit:<sha>` (also `issue#N`, `pr#N`, `doc:<path>`, `formula:<name>`). When it stops being true: `af memory expire <id>`.
 - Notes are append-only and there is no delete verb — graduating or expiring one stops it costing you context without destroying the record.
 - `af memory status` reports what the vault holds and what is due for graduation.