From 9ccbdff19f4d39d41f558838ee350fc2f7f34df0 Mon Sep 17 00:00:00 2001
From: dave <futurechimp@users.noreply.github.com>
Date: Wed, 13 May 2026 05:38:34 +0000
Subject: [PATCH] huskies: merge 952

---
 .gitignore                           |  3 ++
 .huskies/AGENT.md                    | 45 ++++++++++++++++++++++++++++
 server/src/io/fs/scaffold/helpers.rs |  2 +-
 3 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index 87728359..b0919d8f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,6 +17,9 @@ _merge_parsed.json
 .huskies/build_hash
 .huskies/source-map.json
 
+# Per-worktree planning file (written by coder agents, must never reach squash commits)
+PLAN.md
+
 # Coverage report (generated by script/test_coverage, not tracked in git)
 .coverage_report.json
 .coverage_baseline
diff --git a/.huskies/AGENT.md b/.huskies/AGENT.md
index 69ee857d..da18d75e 100644
--- a/.huskies/AGENT.md
+++ b/.huskies/AGENT.md
@@ -1,5 +1,50 @@
 # Huskies project-local agent guidance
 
+## Session Start & Resume Protocol
+
+### PLAN.md — required for every coder session
+
+At the very start of each coder session, before doing any code exploration, check for `PLAN.md` in the worktree root:
+
+**If `PLAN.md` exists (resuming after a watchdog respawn):**
+1. Read `PLAN.md` first — it is your primary orientation document.
+2. Only after reading it, call `git_log` / `git_diff` to see commits made since the plan was last updated.
+3. Reconcile any divergence between the plan and the current git state, then update the plan.
+
+**If `PLAN.md` is absent (first session on this story):**
+1. Write `PLAN.md` before any grep, file read, or exploration tool call.
+2. Populate it with what you know from the story ACs alone; add specifics as you discover them.
+
+### What PLAN.md must contain
+
+`PLAN.md` is a living document. Update it after each completed AC or natural unit of work — not only at the start.
+
+Required sections:
+
+```markdown
+# Plan: Story <id>
+
+## ACs → implementation locations
+- AC 1: <exact file path>:<line range> — <one-line description of what changes>
+- AC 2: <exact file path>:<line range> — …
+…
+
+## Decisions
+- <Decision made>: <rationale> — rejected alternative: <what was considered and why it lost>
+…
+
+## Current state
+<What has been done so far. Reference commit hashes or specific functions completed.>
+
+## What's left
+- [ ] <specific remaining task with file path and function name>
+…
+```
+
+### Non-conforming outputs
+
+A PLAN.md that contains only generic steps like "read the code", "write the code", "run the tests", or leaves file paths as `<TBD>` or unspecified is **non-conforming**. Every AC entry must name a real file path and describe the actual change. Every decision entry must name both the chosen approach and at least one rejected alternative with a reason. A stub plan is worse than no plan — rewrite it with specifics.
+
 ## Documentation
 Docs live in `website/docs/*.html` (static HTML), **not** Markdown files. When a story asks you to document something, edit the relevant `.html` file in `website/docs/`.
 
diff --git a/server/src/io/fs/scaffold/helpers.rs b/server/src/io/fs/scaffold/helpers.rs
index ea81b06b..df2b0ab2 100644
--- a/server/src/io/fs/scaffold/helpers.rs
+++ b/server/src/io/fs/scaffold/helpers.rs
@@ -101,7 +101,7 @@ pub(super) fn write_story_kit_gitignore(root: &Path) -> Result<(), String> {
 /// `store.json` is excluded via `.huskies/.gitignore` since it now lives
 /// inside the `.huskies/` directory.
 pub(super) fn append_root_gitignore_entries(root: &Path) -> Result<(), String> {
-    let entries = [".huskies_port", ".mcp.json"];
+    let entries = [".huskies_port", ".mcp.json", "PLAN.md"];
 
     let gitignore_path = root.join(".gitignore");
     let existing = if gitignore_path.exists() {