@ouro.bot/cli 0.1.0-alpha.6 → 0.1.0-alpha.60

package/dist/senses/trust-gate.js

@@ -39,6 +39,9 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const identity_1 = require("../heart/identity");
 const runtime_1 = require("../nerves/runtime");
+const types_1 = require("../mind/friends/types");
+const pending_1 = require("../mind/pending");
+// Canned reply; eventually agents should compose their own first-contact message
 exports.STRANGER_AUTO_REPLY = "I'm sorry, I'm not allowed to talk to strangers";
 function buildExternalKey(provider, externalId, tenantId) {
     return `${provider}:${tenantId ?? ""}:${externalId}`;
@@ -77,16 +80,107 @@ function appendPrimaryNotification(bundleRoot, provider, externalId, tenantId, n
     fs.mkdirSync(inboxDir, { recursive: true });
     fs.appendFileSync(notificationsPath, `${JSON.stringify(payload)}\n`, "utf8");
 }
+function writeInnerPendingNotice(bundleRoot, noticeContent, nowIso) {
+    const innerPendingDir = path.join(bundleRoot, "state", "pending", pending_1.INNER_DIALOG_PENDING.friendId, pending_1.INNER_DIALOG_PENDING.channel, pending_1.INNER_DIALOG_PENDING.key);
+    const fileName = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`;
+    const filePath = path.join(innerPendingDir, fileName);
+    const payload = {
+        from: "instinct",
+        content: noticeContent,
+        timestamp: Date.now(),
+        at: nowIso,
+    };
+    fs.mkdirSync(innerPendingDir, { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(payload), "utf-8");
+}
 function enforceTrustGate(input) {
+    const { senseType } = input;
+    // Local (CLI) and internal (inner dialog) — always allow
+    if (senseType === "local" || senseType === "internal") {
+        return { allowed: true };
+    }
+    // Closed senses (Teams) — org already gates access, allow all trust levels
+    if (senseType === "closed") {
+        return { allowed: true };
+    }
+    // Open senses (BlueBubbles/iMessage) — enforce trust rules
     const trustLevel = input.friend.trustLevel ?? "friend";
-    if (trustLevel !== "stranger") {
+    // Family and friend — always allow on open
+    if ((0, types_1.isTrustedLevel)(trustLevel)) {
         return { allowed: true };
     }
     const bundleRoot = input.bundleRoot ?? (0, identity_1.getAgentRoot)();
-    const repliesPath = path.join(bundleRoot, "stranger-replies.json");
     const nowIso = (input.now ?? (() => new Date()))().toISOString();
+    // Acquaintance rules
+    if (trustLevel === "acquaintance") {
+        return handleAcquaintance(input, bundleRoot, nowIso);
+    }
+    // Stranger rules (trustLevel === "stranger")
+    return handleStranger(input, bundleRoot, nowIso);
+}
+function handleAcquaintance(input, bundleRoot, nowIso) {
+    const { isGroupChat, groupHasFamilyMember, hasExistingGroupWithFamily } = input;
+    // Group chat with family member present — allow
+    if (isGroupChat && groupHasFamilyMember) {
+        return { allowed: true };
+    }
+    let result;
+    let noticeDetail;
+    if (isGroupChat) {
+        // Group chat without family member — reject silently
+        result = { allowed: false, reason: "acquaintance_group_no_family" };
+        noticeDetail = `acquaintance "${input.friend.name}" messaged in a group chat without a family member present`;
+    }
+    else if (hasExistingGroupWithFamily) {
+        // 1:1 but shares a group with family — redirect
+        result = {
+            allowed: false,
+            reason: "acquaintance_1on1_has_group",
+            autoReply: "Hey! Reach me in our group chat instead.",
+        };
+        noticeDetail = `acquaintance "${input.friend.name}" DMed me directly — redirected to our group chat`;
+    }
+    else {
+        // 1:1, no shared group with family — redirect to any group
+        result = {
+            allowed: false,
+            reason: "acquaintance_1on1_no_group",
+            autoReply: "Hey! Reach me in a group chat instead.",
+        };
+        noticeDetail = `acquaintance "${input.friend.name}" DMed me directly — asked to reach me in a group chat`;
+    }
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "senses",
+        event: "senses.trust_gate",
+        message: "acquaintance message blocked",
+        meta: {
+            channel: input.channel,
+            provider: input.provider,
+            reason: result.reason,
+        },
+    });
+    try {
+        writeInnerPendingNotice(bundleRoot, noticeDetail, nowIso);
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            component: "senses",
+            event: "senses.trust_gate_error",
+            message: "failed to write inner pending notice",
+            meta: {
+                reason: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+    return result;
+}
+function handleStranger(input, bundleRoot, nowIso) {
+    const repliesPath = path.join(bundleRoot, "stranger-replies.json");
     const externalKey = buildExternalKey(input.provider, input.externalId, input.tenantId);
     const state = loadRepliesState(repliesPath);
+    // Subsequent contact — silent drop
     if (state[externalKey]) {
         (0, runtime_1.emitNervesEvent)({
             level: "warn",
@@ -103,6 +197,7 @@ function enforceTrustGate(input) {
             reason: "stranger_silent_drop",
         };
     }
+    // First contact — auto-reply, persist state, notify agent
     state[externalKey] = nowIso;
     try {
         persistRepliesState(repliesPath, state);
@@ -132,6 +227,21 @@ function enforceTrustGate(input) {
             },
         });
     }
+    const noticeDetail = `stranger "${input.friend.name}" tried to reach me via ${input.channel}. Auto-replied once.`;
+    try {
+        writeInnerPendingNotice(bundleRoot, noticeDetail, nowIso);
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            component: "senses",
+            event: "senses.trust_gate_error",
+            message: "failed to write inner pending notice",
+            meta: {
+                reason: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
     (0, runtime_1.emitNervesEvent)({
         level: "warn",
         component: "senses",

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.60",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
+    "cli": "dist/heart/daemon/ouro-bot-entry.js",
     "ouro": "dist/heart/daemon/ouro-entry.js",
     "ouro.bot": "dist/heart/daemon/ouro-bot-entry.js"
   },
   "files": [
     "dist/",
     "AdoptionSpecialist.ouro/",
-    "subagents/"
+    "subagents/",
+    "assets/",
+    "changelog.json"
   ],
   "exports": {
     ".": "./dist/heart/daemon/daemon-cli.js",
@@ -30,11 +33,19 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.78.0",
+    "@azure/identity": "^4.13.0",
     "@microsoft/teams.apps": "^2.0.5",
     "@microsoft/teams.dev": "^2.0.5",
-    "openai": "^6.27.0"
+    "fast-glob": "^3.3.3",
+    "openai": "^6.27.0",
+    "semver": "^7.7.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ouroborosbot/ouroboros"
   },
   "devDependencies": {
+    "@types/semver": "^7.7.1",
     "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^10.0.2",
     "typescript": "^5.7.0",

package/subagents/README.md

@@ -1,52 +1,68 @@
-# Sub-agents
+# Workflow Helpers
 
-These are source-of-truth workflow definitions (`work-planner`, `work-doer`, `work-merger`) for planning, execution, and merge. They can be consumed either as Claude sub-agents (`.md` files with YAML frontmatter) or as Codex-style skills (`SKILL.md`).
+These files are the source-of-truth workflow helpers for:
 
-## Installation
+- `work-planner`
+- `work-doer`
+- `work-merger`
 
-### Claude Code (sub-agents)
+They are written to stay generic enough for different agent shells, while following this repo’s local rules through `AGENTS.md`.
 
-Copy or symlink these files into Claude's sub-agent directory:
+## What They Do
+
+- `work-planner.md`
+  Creates and refines planning docs, then converts approved plans into doing docs.
+- `work-doer.md`
+  Executes approved doing docs unit by unit with strict validation discipline.
+- `work-merger.md`
+  Syncs with `main`, resolves conflicts, creates the PR, handles CI, and merges.
+
+## Important Repo-Specific Truth
+
+These helpers do not hardcode task-doc paths. They are expected to read project instructions to discover them.
+
+In this repo, that means:
+
+- task docs live in `~/AgentBundles/<agent>.ouro/tasks/one-shots/`
+- not inside the repo
+
+## Installing For Claude Code
 
 ```bash
-# Claude Code
+mkdir -p ~/.claude/agents
 cp subagents/*.md ~/.claude/agents/
-# or
-ln -s "$(pwd)"/subagents/*.md ~/.claude/agents/
 ```
 
-### Codex / skill-based harnesses
-
-For tools that support skills but not Claude sub-agents, install these as skills:
+## Installing For Codex-Style Skills
 
 ```bash
-mkdir -p ~/.codex/skills/work-planner ~/.codex/skills/work-doer ~/.codex/skills/work-merger
+mkdir -p ~/.agents/skills/work-planner ~/.agents/skills/work-doer ~/.agents/skills/work-merger
 
 # Hard-link to keep one source of truth
-ln -f "$(pwd)/subagents/work-planner.md" ~/.codex/skills/work-planner/SKILL.md
-ln -f "$(pwd)/subagents/work-doer.md" ~/.codex/skills/work-doer/SKILL.md
-ln -f "$(pwd)/subagents/work-merger.md" ~/.codex/skills/work-merger/SKILL.md
+ln -f "$(pwd)/subagents/work-planner.md" ~/.agents/skills/work-planner/SKILL.md
+ln -f "$(pwd)/subagents/work-doer.md" ~/.agents/skills/work-doer/SKILL.md
+ln -f "$(pwd)/subagents/work-merger.md" ~/.agents/skills/work-merger/SKILL.md
 ```
 
-**Important:** Hard-links break when editors save by replacing the file (new inode). After editing any `subagents/*.md` file, re-run the `ln -f` command for that file to restore the link. You can verify with `stat -f '%i'` — both files should share the same inode.
+**Important:** For Codex/OpenAI skill installs, use the generic `~/.agents/skills` root and use hard links (`ln`, not `ln -s`). Installing the same skill into both `~/.agents/skills` and `~/.codex/skills` can produce duplicate entries in Codex. Symlinked `SKILL.md` files may load but are not advertised reliably by Codex surfaces. Hard-links break when editors save by replacing the file (new inode). After editing any `subagents/*.md` file, re-run the `ln -f` command for that file to restore the link. You can verify with `stat -f '%i'` — both files should share the same inode.
 
 Optional UI metadata:
 
 ```bash
-mkdir -p ~/.codex/skills/work-planner/agents ~/.codex/skills/work-doer/agents ~/.codex/skills/work-merger/agents
-cat > ~/.codex/skills/work-planner/agents/openai.yaml << 'EOF'
+mkdir -p ~/.agents/skills/work-planner/agents ~/.agents/skills/work-doer/agents ~/.agents/skills/work-merger/agents
+cat > ~/.agents/skills/work-planner/agents/openai.yaml << 'EOF'
 interface:
   display_name: "Work Planner"
   short_description: "Create and gate planning/doing task docs"
   default_prompt: "Use $work-planner to create or update a planning doc, then stop at NEEDS_REVIEW."
 EOF
-cat > ~/.codex/skills/work-doer/agents/openai.yaml << 'EOF'
+cat > ~/.agents/skills/work-doer/agents/openai.yaml << 'EOF'
 interface:
   display_name: "Work Doer"
   short_description: "Execute approved doing docs with strict TDD"
   default_prompt: "Use $work-doer to execute an approved doing doc unit by unit."
 EOF
-cat > ~/.codex/skills/work-merger/agents/openai.yaml << 'EOF'
+cat > ~/.agents/skills/work-merger/agents/openai.yaml << 'EOF'
 interface:
   display_name: "Work Merger"
   short_description: "Merge feature branch into main via PR after work-doer completes"
@@ -54,20 +70,17 @@ interface:
 EOF
 ```
 
-Restart the harness after install so new skills are discovered.
+## Keeping Local Skill Copies Fresh
+
+After editing any `subagents/*.md` file, resync your local installed copies.
 
-## Available sub-agents
+The repo workflow usually checks this with diffs like:
 
-| File | Purpose |
-|------|---------|
-| `work-planner.md` | Interactive task planner. Generates planning docs through conversation, then converts to doing docs after human approval. |
-| `work-doer.md` | Task executor. Reads a doing doc and works through each unit sequentially with strict TDD. |
-| `work-merger.md` | Sync-and-merge agent. Merges feature branch into main via PR after work-doer completes. Handles conflicts, CI failures, and race conditions. |
+```bash
+diff -q ~/.agents/skills/work-planner/SKILL.md subagents/work-planner.md
+diff -q ~/.agents/skills/work-doer/SKILL.md subagents/work-doer.md
+```
 
-## Workflow
+## Restart Behavior
 
-1. Human describes a task
-2. Agent invokes **work-planner** to create a planning doc → human approves → planner converts to doing doc
-3. Agent invokes **work-doer** to execute the doing doc unit by unit
-4. Each unit is committed independently with progress tracked in the doing doc
-5. Agent invokes **work-merger** to merge the feature branch into main via PR (fetch, merge, resolve conflicts, CI gate, merge PR, cleanup)
+Some tools only discover new skills on startup. If a shell/app does not see updates immediately, restart that shell/app after syncing.

package/subagents/work-doer.md

@@ -8,17 +8,19 @@ 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. **Confirm worktree**: Run from the dedicated task worktree required by the project. If the current checkout is shared, ambiguous, or not on the task branch, switch/create the correct worktree first when project instructions allow it. Only STOP to ask the user when they explicitly want to control naming/layout or automatic creation fails.
+3. **Find doing doc**: Look for `YYYY-MM-DD-HHMM-doing-*.md` in that project-defined task-doc directory
+4. If multiple found, ask which one
+5. If none found, ask user for location
+6. **Check execution_mode**: Read the doing doc's `Execution Mode` field
+7. **Verify artifacts directory exists**: `{task-name}/` next to `{task-name}.md`
    - If missing, create it: `mkdir {task-name}`
-6. **Detect resume vs fresh start:**
+8. **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 +216,22 @@ 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. **Respect the approved structure**: A `READY_FOR_EXECUTION` doing doc should already be ambiguity-clean. Do not rewrite unit structure unless the user changes scope or the doing doc is actually blocked/inaccurate.
+6. **TDD strictly enforced** — tests before implementation, always
+7. **100% coverage** — no exceptions, no exclude attributes
+8. **Atomic commits** — one logical unit per commit, push after each
+9. **Timestamps from git** — `git log -1 --format="%Y-%m-%d %H:%M"`
+10. **Push after each unit phase complete**
+11. **Update doing.md after each unit** — status and progress log
+12. **Spawn sub-agents for fixes** — don't ask, just do it
+13. **Update docs immediately** — when decisions made, commit right away
+14. **Stop on actual blocker** — unclear requirements or need user input
+15. **/compact proactively** — preserve context between units
+16. **No warnings** — treat warnings as errors
+17. **Run full test suite** — before marking unit complete, not just new tests
+18. **Always compile** — run the project's build command after every implementation/refactor unit. Tests passing is necessary but not sufficient.
+19. **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,17 @@ 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. Confirm the task is running from a dedicated task worktree when the project requires parallel agent work; if the checkout is shared or ambiguous, create/switch to the dedicated worktree yourself when project instructions allow it, and only STOP to ask the caller when they explicitly want to control naming/layout or automatic creation fails
+4. Set `TASK_DIR` to the project-defined planning/doing directory
+5. If the project-defined parent location exists but `TASK_DIR` does not, create it
+6. If the project does not define a task-doc location, STOP and ask the user or caller where planning/doing docs should live
+7. 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 +109,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 +159,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.**
+Run these passes — announce each. **ALL 5 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)
@@ -173,7 +182,14 @@ Run these passes — announce each. **ALL 4 PASSES ARE MANDATORY. You must run e
 - Update units if reality differs from what was assumed during planning
 - Commit: `git commit -m "docs(doing): validation pass"` (or `"docs(doing): validation pass - no changes needed"` if nothing to fix)
 
-**Pass 4 — Quality:**
+**Pass 4 — Ambiguity:**
+- Remove doer-facing ambiguity before execution starts
+- Tighten units so a `READY_FOR_EXECUTION` doing doc does not require structural rewrites by `work-doer`
+- Resolve fuzzy phrases like "appropriate files", "as needed", or "wherever the bug is" into concrete targets unless the project instructions explicitly require that flexibility
+- If uncertainty remains, keep it in the planning doc's `Open Questions`, set status to `NEEDS_REVIEW`, and STOP instead of shipping an ambiguous doing doc
+- Commit: `git commit -m "docs(doing): ambiguity pass"` (or `"docs(doing): ambiguity pass - no changes needed"` if nothing to fix)
+
+**Pass 5 — Quality:**
 - All units have acceptance criteria?
 - No TBD items?
 - Completion criteria testable?
@@ -347,27 +363,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.