feat: context health soft directive in preamble (T2+)

Adds a "periodically self-summarize" nudge to long-running skills.
Soft directive only — no thresholds, no enforcement, no auto-commit.

Goal: self-awareness during /qa, /investigate, /cso etc. If you notice
yourself going in circles, STOP and reassess instead of thrashing.

Codex review caught that fake precision thresholds (15/30/45 tool calls)
were unimplementable — SKILL.md is a static prompt, not runtime code.
This ships the soft version only.

Changes:
- scripts/resolvers/preamble.ts: add generateContextHealth(), wire into
  T2+ tier. Format: [PROGRESS] ... summary line. Explicit rule that
  progress reporting must never mutate git state.
- All T2+ skill SKILL.md files regenerated to include the new section.
- Golden ship fixtures updated (T4 skill, picks up the change).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

autoplan/SKILL.md

@@ -383,6 +383,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

canary/SKILL.md

@@ -375,6 +375,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Completion Status Protocol
 
 When completing a skill workflow, report status using one of:

checkpoint/SKILL.md

@@ -378,6 +378,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Completion Status Protocol
 
 When completing a skill workflow, report status using one of:

codex/SKILL.md

@@ -377,6 +377,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

cso/SKILL.md

@@ -380,6 +380,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Completion Status Protocol
 
 When completing a skill workflow, report status using one of:

design-consultation/SKILL.md

@@ -380,6 +380,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

design-html/SKILL.md

@@ -382,6 +382,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Completion Status Protocol
 
 When completing a skill workflow, report status using one of:

design-review/SKILL.md

@@ -380,6 +380,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

design-shotgun/SKILL.md

@@ -377,6 +377,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Completion Status Protocol
 
 When completing a skill workflow, report status using one of:

devex-review/SKILL.md

@@ -380,6 +380,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

document-release/SKILL.md

@@ -377,6 +377,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Completion Status Protocol
 
 When completing a skill workflow, report status using one of:

health/SKILL.md

@@ -377,6 +377,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Completion Status Protocol
 
 When completing a skill workflow, report status using one of:

investigate/SKILL.md

@@ -392,6 +392,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Completion Status Protocol
 
 When completing a skill workflow, report status using one of:

land-and-deploy/SKILL.md

@@ -374,6 +374,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

learn/SKILL.md

@@ -377,6 +377,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Completion Status Protocol
 
 When completing a skill workflow, report status using one of:

office-hours/SKILL.md

@@ -384,6 +384,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

open-gstack-browser/SKILL.md

@@ -374,6 +374,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

pair-agent/SKILL.md

@@ -375,6 +375,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

plan-ceo-review/SKILL.md

@@ -380,6 +380,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

plan-design-review/SKILL.md

@@ -378,6 +378,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

plan-devex-review/SKILL.md

@@ -382,6 +382,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

plan-eng-review/SKILL.md

@@ -380,6 +380,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

qa-only/SKILL.md

@@ -376,6 +376,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

qa/SKILL.md

@@ -382,6 +382,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

retro/SKILL.md

@@ -375,6 +375,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Completion Status Protocol
 
 When completing a skill workflow, report status using one of:

review/SKILL.md

@@ -378,6 +378,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

scripts/resolvers/preamble.ts

@@ -704,6 +704,23 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
 available]. [Health score if available]." Keep it to 2-3 sentences.`;
 }
 
+function generateContextHealth(): string {
+  return `## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief \`[PROGRESS]\` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+\`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.\`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.`;
+}
+
 // Preamble Composition (tier → sections)
 // ─────────────────────────────────────────────
 // T1: core + upgrade + lake + telemetry + voice(trimmed) + completion
@@ -731,7 +748,7 @@ export function generatePreamble(ctx: TemplateContext): string {
     generateVendoringDeprecation(ctx),
     generateSpawnedSessionCheck(),
     generateVoiceDirective(tier),
-    ...(tier >= 2 ? [generateContextRecovery(ctx), generateAskUserFormat(ctx), generateCompletenessSection()] : []),
+    ...(tier >= 2 ? [generateContextRecovery(ctx), generateAskUserFormat(ctx), generateCompletenessSection(), generateContextHealth()] : []),
     ...(tier >= 3 ? [generateRepoModeSection(), generateSearchBeforeBuildingSection(ctx)] : []),
     generateCompletionStatus(ctx),
   ];

setup-deploy/SKILL.md

@@ -378,6 +378,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Completion Status Protocol
 
 When completing a skill workflow, report status using one of:

ship/SKILL.md

@@ -379,6 +379,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

test/fixtures/golden/claude-ship-SKILL.md

@@ -379,6 +379,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

test/fixtures/golden/codex-ship-SKILL.md

@@ -373,6 +373,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch:

test/fixtures/golden/factory-ship-SKILL.md

@@ -375,6 +375,21 @@ AI makes completeness near-free. Always recommend the complete option over short
 
 Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut).
 
+## Context Health (soft directive)
+
+During long-running skill sessions, periodically write a brief `[PROGRESS]` summary
+(2-3 sentences: what's done, what's next, any surprises). Example:
+
+`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.`
+
+If you notice you're going in circles — repeating the same diagnostic, re-reading the
+same file, or trying variants of a failed fix — STOP and reassess. Consider escalating
+or calling /checkpoint to save progress and start fresh.
+
+This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The
+goal is self-awareness during long sessions. If the session stays short, skip it.
+Progress summaries must NEVER mutate git state — they are reporting, not committing.
+
 ## Repo Ownership — See Something, Say Something
 
 `REPO_MODE` controls how to handle issues outside your branch: