@ouro.bot/cli 0.1.0-alpha.16 → 0.1.0-alpha.18

package/dist/senses/bluebubbles.js

@@ -46,10 +46,12 @@ const tokens_1 = require("../mind/friends/tokens");
 const resolver_1 = require("../mind/friends/resolver");
 const store_file_1 = require("../mind/friends/store-file");
 const prompt_1 = require("../mind/prompt");
+const phrases_1 = require("../mind/phrases");
 const runtime_1 = require("../nerves/runtime");
 const bluebubbles_model_1 = require("./bluebubbles-model");
 const bluebubbles_client_1 = require("./bluebubbles-client");
 const bluebubbles_mutation_log_1 = require("./bluebubbles-mutation-log");
+const debug_activity_1 = require("./debug-activity");
 const defaultDeps = {
     getAgentName: identity_1.getAgentName,
     buildSystem: prompt_1.buildSystem,
@@ -92,10 +94,58 @@ function buildInboundText(event) {
     }
     return `${event.sender.displayName}: ${baseText}`;
 }
+function buildInboundContent(event) {
+    const text = buildInboundText(event);
+    if (event.kind !== "message" || !event.inputPartsForAgent || event.inputPartsForAgent.length === 0) {
+        return text;
+    }
+    return [
+        { type: "text", text },
+        ...event.inputPartsForAgent,
+    ];
+}
 function createBlueBubblesCallbacks(client, chat, replyToMessageGuid) {
     let textBuffer = "";
+    const phrases = (0, phrases_1.getPhrases)();
+    const activity = (0, debug_activity_1.createDebugActivityController)({
+        thinkingPhrases: phrases.thinking,
+        followupPhrases: phrases.followup,
+        transport: {
+            sendStatus: async (text) => {
+                const sent = await client.sendText({
+                    chat,
+                    text,
+                    replyToMessageGuid,
+                });
+                return sent.messageGuid;
+            },
+            editStatus: async (_messageGuid, text) => {
+                await client.sendText({
+                    chat,
+                    text,
+                    replyToMessageGuid,
+                });
+            },
+            setTyping: async (active) => {
+                await client.setTyping(chat, active);
+            },
+        },
+        onTransportError: (operation, error) => {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "senses",
+                event: "senses.bluebubbles_activity_error",
+                message: "bluebubbles activity transport failed",
+                meta: {
+                    operation,
+                    reason: error instanceof Error ? error.message : String(error),
+                },
+            });
+        },
+    });
     return {
         onModelStart() {
+            activity.onModelStart();
             (0, runtime_1.emitNervesEvent)({
                 component: "senses",
                 event: "senses.bluebubbles_turn_start",
@@ -112,10 +162,12 @@ function createBlueBubblesCallbacks(client, chat, replyToMessageGuid) {
             });
         },
         onTextChunk(text) {
+            activity.onTextChunk(text);
             textBuffer += text;
         },
         onReasoningChunk(_text) { },
         onToolStart(name, _args) {
+            activity.onToolStart(name, _args);
             (0, runtime_1.emitNervesEvent)({
                 component: "senses",
                 event: "senses.bluebubbles_tool_start",
@@ -124,6 +176,7 @@ function createBlueBubblesCallbacks(client, chat, replyToMessageGuid) {
             });
         },
         onToolEnd(name, summary, success) {
+            activity.onToolEnd(name, summary, success);
             (0, runtime_1.emitNervesEvent)({
                 component: "senses",
                 event: "senses.bluebubbles_tool_end",
@@ -132,6 +185,7 @@ function createBlueBubblesCallbacks(client, chat, replyToMessageGuid) {
             });
         },
         onError(error, severity) {
+            activity.onError(error);
             (0, runtime_1.emitNervesEvent)({
                 level: severity === "terminal" ? "error" : "warn",
                 component: "senses",
@@ -144,8 +198,10 @@ function createBlueBubblesCallbacks(client, chat, replyToMessageGuid) {
             textBuffer = "";
         },
         async flush() {
+            await activity.drain();
             const trimmed = textBuffer.trim();
             if (!trimmed) {
+                await activity.finish();
                 return;
             }
             textBuffer = "";
@@ -154,6 +210,10 @@ function createBlueBubblesCallbacks(client, chat, replyToMessageGuid) {
                 text: trimmed,
                 replyToMessageGuid,
             });
+            await activity.finish();
+        },
+        async finish() {
+            await activity.finish();
         },
     };
 }
@@ -227,6 +287,15 @@ async function handleBlueBubblesEvent(payload, deps = {}) {
         friendStore: store,
         summarize: (0, core_1.createSummarize)(),
         context,
+        codingFeedback: {
+            send: async (message) => {
+                await client.sendText({
+                    chat: event.chat,
+                    text: message,
+                    replyToMessageGuid: event.kind === "message" ? event.messageGuid : undefined,
+                });
+            },
+        },
     };
     const friendId = context.friend.id;
     const sessPath = resolvedDeps.sessionPath(friendId, "bluebubbles", event.chat.sessionKey);
@@ -234,31 +303,51 @@ async function handleBlueBubblesEvent(payload, deps = {}) {
     const messages = existing?.messages && existing.messages.length > 0
         ? existing.messages
         : [{ role: "system", content: await resolvedDeps.buildSystem("bluebubbles", undefined, context) }];
-    messages.push({ role: "user", content: buildInboundText(event) });
+    messages.push({ role: "user", content: buildInboundContent(event) });
     const callbacks = createBlueBubblesCallbacks(client, event.chat, event.kind === "message" ? event.messageGuid : undefined);
     const controller = new AbortController();
     const agentOptions = {
         toolContext,
     };
-    const result = await resolvedDeps.runAgent(messages, callbacks, "bluebubbles", controller.signal, agentOptions);
-    await callbacks.flush();
-    resolvedDeps.postTurn(messages, sessPath, result.usage);
-    await resolvedDeps.accumulateFriendTokens(store, friendId, result.usage);
-    (0, runtime_1.emitNervesEvent)({
-        component: "senses",
-        event: "senses.bluebubbles_turn_end",
-        message: "bluebubbles event handled",
-        meta: {
-            messageGuid: event.messageGuid,
+    try {
+        const result = await resolvedDeps.runAgent(messages, callbacks, "bluebubbles", controller.signal, agentOptions);
+        await callbacks.flush();
+        resolvedDeps.postTurn(messages, sessPath, result.usage);
+        await resolvedDeps.accumulateFriendTokens(store, friendId, result.usage);
+        try {
+            await client.markChatRead(event.chat);
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "senses",
+                event: "senses.bluebubbles_mark_read_error",
+                message: "failed to mark bluebubbles chat as read",
+                meta: {
+                    chatGuid: event.chat.chatGuid ?? null,
+                    reason: error instanceof Error ? error.message : String(error),
+                },
+            });
+        }
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.bluebubbles_turn_end",
+            message: "bluebubbles event handled",
+            meta: {
+                messageGuid: event.messageGuid,
+                kind: event.kind,
+                sessionKey: event.chat.sessionKey,
+            },
+        });
+        return {
+            handled: true,
+            notifiedAgent: true,
             kind: event.kind,
-            sessionKey: event.chat.sessionKey,
-        },
-    });
-    return {
-        handled: true,
-        notifiedAgent: true,
-        kind: event.kind,
-    };
+        };
+    }
+    finally {
+        await callbacks.finish();
+    }
 }
 function createBlueBubblesWebhookHandler(deps = {}) {
     return async (req, res) => {

package/dist/senses/debug-activity.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDebugActivityController = createDebugActivityController;
+const format_1 = require("../mind/format");
+const phrases_1 = require("../mind/phrases");
+const runtime_1 = require("../nerves/runtime");
+function createDebugActivityController(options) {
+    let queue = Promise.resolve();
+    let statusMessageGuid;
+    let typingActive = false;
+    let hadToolRun = false;
+    let followupShown = false;
+    let lastPhrase = "";
+    function reportTransportError(operation, error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.debug_activity_transport_error",
+            message: "debug activity transport failed",
+            meta: {
+                operation,
+                reason: error instanceof Error ? error.message : String(error),
+            },
+        });
+        options.onTransportError?.(operation, error);
+    }
+    function enqueue(operation, task) {
+        queue = queue
+            .then(task)
+            .catch((error) => {
+            reportTransportError(operation, error);
+        });
+    }
+    function nextPhrase(pool) {
+        const phrase = (0, phrases_1.pickPhrase)(pool, lastPhrase);
+        lastPhrase = phrase;
+        return phrase;
+    }
+    function ensureTyping(active) {
+        if (typingActive === active) {
+            return;
+        }
+        typingActive = active;
+        enqueue(active ? "typing_start" : "typing_stop", async () => {
+            await options.transport.setTyping(active);
+        });
+    }
+    function setStatus(text) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.debug_activity_update",
+            message: "debug activity status updated",
+            meta: {
+                hasStatusGuid: Boolean(statusMessageGuid),
+                textLength: text.length,
+            },
+        });
+        ensureTyping(true);
+        enqueue("status_update", async () => {
+            if (statusMessageGuid) {
+                await options.transport.editStatus(statusMessageGuid, text);
+                return;
+            }
+            statusMessageGuid = await options.transport.sendStatus(text);
+        });
+    }
+    return {
+        onModelStart() {
+            const pool = hadToolRun ? options.followupPhrases : options.thinkingPhrases;
+            setStatus(`${nextPhrase(pool)}...`);
+        },
+        onToolStart(name, args) {
+            hadToolRun = true;
+            followupShown = false;
+            const argSummary = Object.values(args).join(", ");
+            const detail = argSummary ? ` (${argSummary})` : "";
+            setStatus(`running ${name}${detail}...`);
+        },
+        onToolEnd(name, summary, success) {
+            hadToolRun = true;
+            followupShown = false;
+            setStatus((0, format_1.formatToolResult)(name, summary, success));
+        },
+        onTextChunk(text) {
+            if (!text || !hadToolRun || followupShown) {
+                return;
+            }
+            followupShown = true;
+            setStatus(`${nextPhrase(options.followupPhrases)}...`);
+        },
+        onError(error) {
+            setStatus((0, format_1.formatError)(error));
+            this.finish();
+        },
+        async drain() {
+            await queue;
+        },
+        async finish() {
+            if (!typingActive) {
+                await queue;
+                return;
+            }
+            ensureTyping(false);
+            await queue;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.16",
+  "version": "0.1.0-alpha.18",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "ouro": "dist/heart/daemon/ouro-entry.js",

package/subagents/work-doer.md

@@ -8,17 +8,18 @@ You are a task executor. Read a doing.md file and execute all units sequentially
 
 ## On Startup
 
-1. **Find doing doc**: Look for `YYYY-MM-DD-HHMM-doing-*.md` in repo root
-2. If multiple found, ask which one
-3. If none found, ask user for location
-4. **Check execution_mode**: Read the doing doc's `Execution Mode` field
-5. **Verify artifacts directory exists**: `{task-name}/` next to `{task-name}.md`
+1. **Find task-doc directory**: Read project instructions (for example `AGENTS.md`) to determine where planning/doing docs live for this repo
+2. **Find doing doc**: Look for `YYYY-MM-DD-HHMM-doing-*.md` in that project-defined task-doc directory
+3. If multiple found, ask which one
+4. If none found, ask user for location
+5. **Check execution_mode**: Read the doing doc's `Execution Mode` field
+6. **Verify artifacts directory exists**: `{task-name}/` next to `{task-name}.md`
    - If missing, create it: `mkdir {task-name}`
-6. **Detect resume vs fresh start:**
+7. **Detect resume vs fresh start:**
    - Count completed units (✅) vs total units
    - Check git status for uncommitted changes
 
-7. **Announce status clearly:**
+8. **Announce status clearly:**
 
 **If fresh start (0 units complete):**
 ```
@@ -214,20 +215,21 @@ When all units are `✅`:
 ## Rules
 
 1. **File naming**: Expect `YYYY-MM-DD-HHMM-doing-{name}.md` format
-2. **Artifacts directory**: Use `{task-name}/` for all outputs, logs, data
-3. **Execution mode**: Honor `pending | spawn | direct` from doing doc
-4. **TDD strictly enforced** — tests before implementation, always
-5. **100% coverage** — no exceptions, no exclude attributes
-6. **Atomic commits** — one logical unit per commit, push after each
-7. **Timestamps from git** — `git log -1 --format="%Y-%m-%d %H:%M"`
-8. **Push after each unit phase complete**
-9. **Update doing.md after each unit** — status and progress log
-10. **Spawn sub-agents for fixes** — don't ask, just do it
-11. **Update docs immediately** — when decisions made, commit right away
-12. **Stop on actual blocker** — unclear requirements or need user input
-13. **/compact proactively** — preserve context between units
-14. **No warnings** — treat warnings as errors
-15. **Run full test suite** — before marking unit complete, not just new tests
-16. **Always compile** — run the project's build command after every implementation/refactor unit. Tests passing is necessary but not sufficient.
-17. **Checklist hygiene is mandatory** — keep doing/planning `Completion Criteria` checklists synchronized with verified completion evidence.
-18. **Verify APIs before importing** — before writing `import { Foo } from './bar'`, use `grep` or `read_file` to confirm `Foo` is actually exported from that module. Never assume an export exists — always check the source first. This prevents wasted cycles on "module has no exported member" errors.
+2. **Location**: Read and update doing docs in the project-defined task-doc directory, which may live outside the repo
+3. **Artifacts directory**: Use `{task-name}/` for all outputs, logs, data
+4. **Execution mode**: Honor `pending | spawn | direct` from doing doc
+5. **TDD strictly enforced** — tests before implementation, always
+6. **100% coverage** — no exceptions, no exclude attributes
+7. **Atomic commits** — one logical unit per commit, push after each
+8. **Timestamps from git** — `git log -1 --format="%Y-%m-%d %H:%M"`
+9. **Push after each unit phase complete**
+10. **Update doing.md after each unit** — status and progress log
+11. **Spawn sub-agents for fixes** — don't ask, just do it
+12. **Update docs immediately** — when decisions made, commit right away
+13. **Stop on actual blocker** — unclear requirements or need user input
+14. **/compact proactively** — preserve context between units
+15. **No warnings** — treat warnings as errors
+16. **Run full test suite** — before marking unit complete, not just new tests
+17. **Always compile** — run the project's build command after every implementation/refactor unit. Tests passing is necessary but not sufficient.
+18. **Checklist hygiene is mandatory** — keep doing/planning `Completion Criteria` checklists synchronized with verified completion evidence.
+19. **Verify APIs before importing** — before writing `import { Foo } from './bar'`, use `grep` or `read_file` to confirm `Foo` is actually exported from that module. Never assume an export exists — always check the source first. This prevents wasted cycles on "module has no exported member" errors.

package/subagents/work-merger.md

@@ -19,12 +19,16 @@ The branch follows the `<agent>/<slug>` convention (e.g., `ouroboros/context-ker
 
 Do not hardcode agent names. Derive `<agent>` from the branch at runtime.
 
+### 1a. Determine the project-defined task-doc directory
+
+Read project instructions (for example `AGENTS.md`) to determine where this repo keeps planning/doing docs. Set `TASK_DIR` to that project-defined location. Do not assume task docs live in the repo.
+
 ### 2. Find own doing doc
 
-The caller provides the doing doc path (e.g., `ouroboros/tasks/2026-03-03-1032-doing-sync-and-merge.md`). If not provided, find the most recent doing doc:
+The caller provides the doing doc path. If not provided, read project instructions (for example `AGENTS.md`) to find the project-defined task-doc directory, then find the most recent doing doc there:
 
 ```bash
-ls -t ${AGENT}/tasks/*-doing-*.md | head -1
+ls -t "${TASK_DIR}"/*-doing-*.md | head -1
 ```
 
 Read this doing doc to understand what was just implemented. You will need it for conflict resolution context.
@@ -134,35 +138,28 @@ You already have the path from On Startup. Read the doing doc to understand:
 - The objective, completion criteria, and unit descriptions
 - What files were changed and why
 
-### Step 2: Discover other agents' doing docs (git-informed)
-
-Find exactly which doing docs landed on main since this branch diverged. Do NOT scan by filename timestamps or guess -- use git history:
-
-```bash
-git log origin/main --not HEAD --name-only --diff-filter=A -- '*/tasks/*-doing-*.md'
-```
+### Step 2: Gather incoming-main intent (git-informed)
 
-This returns the paths of doing docs that were **added to main** after this branch's merge base. These are the docs from the other agent's completed work that caused the conflicts.
-
-If no doing docs are found with `--diff-filter=A` (added), also check for modifications:
+Do not assume task docs live in this repo. Instead, use git history and diffs to understand what landed on `main` since this branch diverged:
 
 ```bash
-git log origin/main --not HEAD --name-only --diff-filter=M -- '*/tasks/*-doing-*.md'
+git log origin/main --not HEAD --oneline
+git diff --name-only HEAD...origin/main
 ```
 
-**Why git-informed discovery matters:**
-- Timestamp-sorted filename scans can miss relevant docs or include irrelevant ones
-- Git history tells you exactly what landed on main since you branched
-- This is deterministic and correct regardless of doc naming or timing
+If a clearly relevant local task doc exists outside the repo (for example in another local bundle/worktree task directory), you may read it for extra context. Treat that as optional context, not a required precondition.
 
-### Step 3: Read discovered doing docs
+**Why this is the primary source of truth:**
+- Task docs may live outside the repo entirely
+- Git history tells you exactly what changed on `main` since you branched
+- This keeps work-merger generic instead of assuming one repo's task-doc layout
 
-For each doing doc found in Step 2, read it to understand:
-- What the other agent implemented
-- Their objective and completion criteria
-- Which files they changed and why
+### Step 3: Combine own task intent with incoming-main changes
 
-This gives you both intents: what your branch did, and what landed on main.
+Use:
+- your own doing doc as the source of truth for this branch's intent
+- incoming git commits/diffs as the source of truth for what landed on `main`
+- any optional local task docs only when they materially clarify a conflict
 
 ### Step 4: Resolve conflicts
 
@@ -182,7 +179,7 @@ With both intents understood, resolve each conflict:
 If the merge was syntactically clean but tests fail (Case B):
 
 1. Read the test failure output to identify which tests broke
-2. Cross-reference with both doing docs to understand the conflict
+2. Cross-reference with your doing doc plus the incoming git changes to understand the conflict
 3. Fix the code to satisfy both agents' intents
 4. Re-run tests: `npm test`
 5. Repeat until tests pass
@@ -204,7 +201,7 @@ git commit -m "fix: resolve semantic conflicts after merging main"
 npm test
 ```
 
-All tests must pass before proceeding to PR Workflow. If tests still fail after resolution, re-examine the doing docs and try again. If genuinely stuck after multiple attempts, escalate to the user (see **Escalation**).
+All tests must pass before proceeding to PR Workflow. If tests still fail after resolution, re-examine your doing doc, the incoming git changes, and any optional supporting task docs, then try again. If genuinely stuck after multiple attempts, escalate to the user (see **Escalation**).
 
 ---
 
@@ -227,20 +224,17 @@ git push --force-with-lease origin ${BRANCH}
 
 ### Step 2: Create the pull request
 
-Before creating the PR, build a comprehensive description of **all** changes on this branch relative to main — not just the most recent task. Use git to understand the full scope:
+Before creating the PR, build a comprehensive description of **all** changes on this branch relative to main — not just the most recent task. Use your doing doc plus git to understand the full scope:
 
 ```bash
 # All commits on this branch not on main
 git log origin/main..HEAD --oneline
 
-# All doing docs on this branch (completed tasks)
-git log origin/main..HEAD --name-only --diff-filter=A -- '*/tasks/*-doing-*.md'
-
 # Summary of all files changed
 git diff origin/main --stat
 ```
 
-Read each doing doc found above. The PR body should summarize every completed task on the branch, grouped logically. Include:
+Read the doing doc you are executing, plus any other explicitly provided task docs for this branch. The PR body should summarize every completed task on the branch, grouped logically when needed. Include:
 - A section per task (or group of related tasks) with a brief summary of what was implemented
 - A final "Files changed" summary (e.g., "164 files changed — new context kernel, codebase restructure, sync-and-merge system")
 

package/subagents/work-planner.md

@@ -8,8 +8,16 @@ You are a task planner for coding work. Help the user define scope, then convert
 
 ## On Startup
 
+**Determine task doc directory:**
+1. Read project instructions (for example `AGENTS.md`) to find the canonical task-doc location for the current repo
+2. Derive `AGENT` from the current git branch when the project uses agent-scoped task docs
+3. Set `TASK_DIR` to the project-defined planning/doing directory
+4. If the project-defined parent location exists but `TASK_DIR` does not, create it
+5. If the project does not define a task-doc location, STOP and ask the user or caller where planning/doing docs should live
+6. Do not assume task docs live in the repo root; many projects keep them externally
+
 **Check for existing planning docs:**
-1. Look for `YYYY-MM-DD-HHMM-planning-*.md` files in repo root
+1. Look for `YYYY-MM-DD-HHMM-planning-*.md` files in `TASK_DIR`
 2. If found, ask: `"found planning-{name}.md from [date]. resume or start new?"`
 3. If resuming: run Template Compliance Check (see below), then continue
 4. If new: proceed with Phase 1
@@ -100,7 +108,7 @@ fix and continue? (y/n)
 
 1. User describes the task
 2. Generate timestamp: `date '+%Y-%m-%d-%H%M'`
-3. Create `YYYY-MM-DD-HHMM-planning-{short-desc}.md` using PLANNING TEMPLATE — **follow template exactly, no extra sections**
+3. Create `TASK_DIR/YYYY-MM-DD-HHMM-planning-{short-desc}.md` using PLANNING TEMPLATE — **follow template exactly, no extra sections**
 4. Commit immediately: `git commit -m "docs(planning): create planning-{short-desc}.md"`
 5. Ask clarifying questions about scope, completion criteria, unknowns
 6. Refine based on answers — **commit after each significant change**
@@ -150,13 +158,13 @@ User answers questions → agent updates doc → agent sets status to `NEEDS_REV
 
 **Only proceed after user says "approved" or equivalent.**
 
-**CRITICAL: Planning doc is KEPT. Conversion creates a NEW doing doc alongside it.**
+**CRITICAL: Planning doc is KEPT. Conversion creates a NEW doing doc alongside it in `TASK_DIR`.**
 
 Run these passes — announce each. **ALL 4 PASSES ARE MANDATORY. You must run every pass, even if you think nothing changed. Each pass MUST have its own commit (use "no changes needed" in the commit message if the pass found nothing to fix). Do NOT skip or combine passes.**
 
 **Pass 1 — First Draft:**
 - Create `YYYY-MM-DD-HHMM-doing-{short-desc}.md` (same timestamp and short-desc as planning)
-- Create adjacent artifacts directory: `YYYY-MM-DD-HHMM-doing-{short-desc}/` for any files, outputs, or working data
+- Create adjacent artifacts directory in `TASK_DIR`: `YYYY-MM-DD-HHMM-doing-{short-desc}/` for any files, outputs, or working data
 - Use DOING TEMPLATE — **follow exactly**, including emoji status on every unit header (`### ⬜ Unit X:`)
 - Fill from planning doc
 - Decide execution_mode: `pending` (needs approval), `spawn` (spawn sub-agent per unit), or `direct` (run directly)
@@ -347,27 +355,28 @@ use work-doer to execute.
 ## Rules
 
 1. **File naming**: `YYYY-MM-DD-HHMM-{type}-{name}.md` — timestamp prefix always
-2. **Artifacts directory**: Create `{task-name}/` next to `{task-name}.md` for outputs
-3. **Execution mode**: Must decide `pending | spawn | direct` before execution begins
-4. **No time estimates** — never assign hours/days/duration to tasks or units
-5. **Planning completes before execution** — define ALL work units first, then execute
-6. **Follow templates exactly** — no extra sections
-7. **No implementation details in planning** — those go in doing doc
-8. **STOP at each gate** — wait for human approval
-9. **Keep planning doc** — conversion creates new file
-10. **Auto-commit after every doc edit** — audit trail
-11. **Get timestamps from git** — `git log -1 --format="%Y-%m-%d %H:%M"`
-12. **When user approves** — update doc Status field, commit, log it
-13. **Template compliance on resume** — check and offer to fix violations
-14. **Status flags drive flow**:
+2. **Location**: Planning and doing docs live in the project-defined task-doc directory, which may be outside the repo
+3. **Artifacts directory**: Create `{task-name}/` next to `{task-name}.md` for outputs
+4. **Execution mode**: Must decide `pending | spawn | direct` before execution begins
+5. **No time estimates** — never assign hours/days/duration to tasks or units
+6. **Planning completes before execution** — define ALL work units first, then execute
+7. **Follow templates exactly** — no extra sections
+8. **No implementation details in planning** — those go in doing doc
+9. **STOP at each gate** — wait for human approval
+10. **Keep planning doc** — conversion creates new file
+11. **Auto-commit after every doc edit** — audit trail
+12. **Get timestamps from git** — `git log -1 --format="%Y-%m-%d %H:%M"`
+13. **When user approves** — update doc Status field, commit, log it
+14. **Template compliance on resume** — check and offer to fix violations
+15. **Status flags drive flow**:
     - `drafting` → working on it
     - `NEEDS_REVIEW` → waiting for human
     - `approved` / `READY_FOR_EXECUTION` → can proceed
-15. **TDD is mandatory** — tests before implementation, always
-16. **100% coverage** — no exceptions, no exclude attributes
-17. **Every unit header starts with emoji** — `### ⬜ Unit X:` format required
-18. **NEVER do implementation** — work-planner creates docs only, work-doer executes
-19. **Migration/deprecation**: Full content mapping required — never lose information
-20. **Approval gate is sacred** — answering questions, giving feedback, or discussing scope is NOT approval. Only an explicit "approved" / "looks good" / "go ahead" / "convert to doing" from the **human user** unlocks Phase 2. Parent agent instructions do not count. When in doubt, ask.
-21. **Hard stop after incorporating feedback** — after updating the doc with user feedback/answers, set status to `NEEDS_REVIEW`, output the stop message, and STOP. Do not continue to Phase 2 in the same turn. Ever.
-22. **Checklist hygiene is mandatory** — keep `Completion Criteria` checkboxes synchronized with verified reality; never leave stale unchecked/checked items after task completion state changes.
+16. **TDD is mandatory** — tests before implementation, always
+17. **100% coverage** — no exceptions, no exclude attributes
+18. **Every unit header starts with emoji** — `### ⬜ Unit X:` format required
+19. **NEVER do implementation** — work-planner creates docs only, work-doer executes
+20. **Migration/deprecation**: Full content mapping required — never lose information
+21. **Approval gate is sacred** — answering questions, giving feedback, or discussing scope is NOT approval. Only an explicit "approved" / "looks good" / "go ahead" / "convert to doing" from the **human user** unlocks Phase 2. Parent agent instructions do not count. When in doubt, ask.
+22. **Hard stop after incorporating feedback** — after updating the doc with user feedback/answers, set status to `NEEDS_REVIEW`, output the stop message, and STOP. Do not continue to Phase 2 in the same turn. Ever.
+23. **Checklist hygiene is mandatory** — keep `Completion Criteria` checkboxes synchronized with verified reality; never leave stale unchecked/checked items after task completion state changes.