@ouro.bot/cli 0.1.0-alpha.2 → 0.1.0-alpha.20

package/dist/senses/teams.js

@@ -44,6 +44,8 @@ exports.startTeamsApp = startTeamsApp;
 const teams_apps_1 = require("@microsoft/teams.apps");
 const teams_dev_1 = require("@microsoft/teams.dev");
 const core_1 = require("../heart/core");
+const tools_1 = require("../repertoire/tools");
+const channel_1 = require("../mind/friends/channel");
 const config_1 = require("../heart/config");
 const prompt_1 = require("../mind/prompt");
 const phrases_1 = require("../mind/phrases");
@@ -58,6 +60,7 @@ const resolver_1 = require("../mind/friends/resolver");
 const tokens_1 = require("../mind/friends/tokens");
 const turn_coordinator_1 = require("../heart/turn-coordinator");
 const identity_1 = require("../heart/identity");
+const http = __importStar(require("http"));
 const path = __importStar(require("path"));
 const trust_gate_1 = require("./trust-gate");
 // Strip @mention markup from incoming messages.
@@ -317,7 +320,14 @@ function createTeamsCallbacks(stream, controller, sendMessage, options) {
         onToolStart: (name, args) => {
             stopPhraseRotation();
             flushTextBuffer();
-            const argSummary = Object.values(args).join(", ");
+            // Emit a placeholder to satisfy the 15s Copilot timeout for initial
+            // stream.emit(). Without this, long tool chains (e.g. ADO batch ops)
+            // never emit before the timeout and the user sees "this response was
+            // stopped". The placeholder is replaced by actual content on next emit.
+            // https://learn.microsoft.com/en-us/answers/questions/2288017/m365-custom-engine-agents-timeout-message-after-15
+            if (!streamHasContent)
+                safeEmit("⏳");
+            const argSummary = (0, tools_1.summarizeArgs)(name, args) || Object.keys(args).join(", ");
             safeUpdate(`running ${name} (${argSummary})...`);
             hadToolRun = true;
         },
@@ -421,7 +431,12 @@ async function withConversationLock(convId, fn) {
 // Create a fresh friend store per request so mkdirSync re-runs if directories
 // are deleted while the process is alive.
 function getFriendStore() {
-    const friendsPath = path.join((0, identity_1.getAgentRoot)(), "friends");
+    // On Azure App Service, os.homedir() returns /root which is ephemeral.
+    // Use /home/.agentstate/ (persistent) when WEBSITE_SITE_NAME is set.
+    /* v8 ignore next 3 -- Azure vs local path branch; environment-specific @preserve */
+    const friendsPath = process.env.WEBSITE_SITE_NAME
+        ? path.join("/home", ".agentstate", (0, identity_1.getAgentName)(), "friends")
+        : path.join((0, identity_1.getAgentRoot)(), "friends");
     return new store_file_1.FileFriendStore(friendsPath);
 }
 // Handle an incoming Teams message
@@ -445,6 +460,8 @@ async function handleTeamsMessage(text, stream, conversationId, teamsContext, se
         signin: teamsContext.signin,
         friendStore: store,
         summarize: (0, core_1.createSummarize)(),
+        tenantId: teamsContext.tenantId,
+        botApi: teamsContext.botApi,
     } : undefined;
     if (toolContext) {
         const resolver = new resolver_1.FriendResolver(store, {
@@ -497,6 +514,8 @@ async function handleTeamsMessage(text, stream, conversationId, teamsContext, se
     const messages = existing?.messages && existing.messages.length > 0
         ? existing.messages
         : [{ role: "system", content: await (0, prompt_1.buildSystem)("teams", undefined, toolContext?.context) }];
+    // Repair any orphaned tool calls from a previous aborted turn
+    (0, core_1.repairOrphanedToolCalls)(messages);
     // Push user message
     messages.push({ role: "user", content: text });
     // Run agent
@@ -518,12 +537,12 @@ async function handleTeamsMessage(text, stream, conversationId, teamsContext, se
     // This must happen after the stream is done so the OAuth card renders properly.
     if (teamsContext) {
         const allContent = messages.map(m => typeof m.content === "string" ? m.content : "").join("\n");
-        if (allContent.includes("AUTH_REQUIRED:graph"))
-            await teamsContext.signin("graph");
-        if (allContent.includes("AUTH_REQUIRED:ado"))
-            await teamsContext.signin("ado");
-        if (allContent.includes("AUTH_REQUIRED:github"))
-            await teamsContext.signin("github");
+        if (allContent.includes("AUTH_REQUIRED:graph") && teamsContext.graphConnectionName)
+            await teamsContext.signin(teamsContext.graphConnectionName);
+        if (allContent.includes("AUTH_REQUIRED:ado") && teamsContext.adoConnectionName)
+            await teamsContext.signin(teamsContext.adoConnectionName);
+        if (allContent.includes("AUTH_REQUIRED:github") && teamsContext.githubConnectionName)
+            await teamsContext.signin(teamsContext.githubConnectionName);
     }
     // Trim context and save session
     (0, context_1.postTurn)(messages, sessPath, result.usage);
@@ -533,49 +552,85 @@ async function handleTeamsMessage(text, stream, conversationId, teamsContext, se
     }
     // SDK auto-closes the stream after our handler returns (app.process.js)
 }
-// Start the Teams app in DevtoolsPlugin mode (local dev) or Bot Service mode (real Teams).
-// Mode is determined by getTeamsConfig().clientId.
-// Text is always accumulated in textBuffer and flushed periodically (chunked streaming).
-function startTeamsApp() {
+// Internal port for the secondary bot App (not exposed externally).
+// The primary app proxies /api/messages-secondary → localhost:SECONDARY_PORT/api/messages.
+const SECONDARY_INTERNAL_PORT = 3979;
+// Collect all unique OAuth connection names across top-level config and tenant overrides.
+/* v8 ignore start -- runtime Teams SDK config; no unit-testable surface @preserve */
+function allOAuthConnectionNames() {
+    const oauthConfig = (0, config_1.getOAuthConfig)();
+    const names = new Set();
+    if (oauthConfig.graphConnectionName)
+        names.add(oauthConfig.graphConnectionName);
+    if (oauthConfig.adoConnectionName)
+        names.add(oauthConfig.adoConnectionName);
+    if (oauthConfig.githubConnectionName)
+        names.add(oauthConfig.githubConnectionName);
+    if (oauthConfig.tenantOverrides) {
+        for (const ov of Object.values(oauthConfig.tenantOverrides)) {
+            if (ov.graphConnectionName)
+                names.add(ov.graphConnectionName);
+            if (ov.adoConnectionName)
+                names.add(ov.adoConnectionName);
+            if (ov.githubConnectionName)
+                names.add(ov.githubConnectionName);
+        }
+    }
+    return [...names];
+}
+// Create an App instance from a TeamsConfig. Returns { app, mode }.
+function createBotApp(teamsConfig) {
     const mentionStripping = { activity: { mentions: { stripText: true } } };
-    const teamsConfig = (0, config_2.getTeamsConfig)();
-    let app;
-    let mode;
     const oauthConfig = (0, config_1.getOAuthConfig)();
-    if (teamsConfig.clientId) {
-        // Bot Service mode -- real Teams connection with SingleTenant credentials
-        app = new teams_apps_1.App({
-            clientId: teamsConfig.clientId,
-            clientSecret: teamsConfig.clientSecret,
-            tenantId: teamsConfig.tenantId,
-            oauth: { defaultConnectionName: oauthConfig.graphConnectionName },
-            ...mentionStripping,
-        });
-        mode = "Bot Service";
+    if (teamsConfig.clientId && teamsConfig.clientSecret) {
+        return {
+            app: new teams_apps_1.App({
+                clientId: teamsConfig.clientId,
+                clientSecret: teamsConfig.clientSecret,
+                tenantId: teamsConfig.tenantId,
+                oauth: { defaultConnectionName: oauthConfig.graphConnectionName },
+                ...mentionStripping,
+            }),
+            mode: "Bot Service (client secret)",
+        };
+    }
+    else if (teamsConfig.clientId) {
+        return {
+            app: new teams_apps_1.App({
+                clientId: teamsConfig.clientId,
+                tenantId: teamsConfig.tenantId,
+                ...(teamsConfig.managedIdentityClientId ? { managedIdentityClientId: teamsConfig.managedIdentityClientId } : {}),
+                oauth: { defaultConnectionName: oauthConfig.graphConnectionName },
+                ...mentionStripping,
+            }),
+            mode: "Bot Service (managed identity)",
+        };
     }
     else {
-        // DevtoolsPlugin mode -- local development with Teams DevtoolsPlugin UI
-        app = new teams_apps_1.App({
-            plugins: [new teams_dev_1.DevtoolsPlugin()],
-            ...mentionStripping,
-        });
-        mode = "DevtoolsPlugin";
+        return {
+            app: new teams_apps_1.App({
+                plugins: [new teams_dev_1.DevtoolsPlugin()],
+                ...mentionStripping,
+            }),
+            mode: "DevtoolsPlugin",
+        };
     }
+}
+/* v8 ignore stop */
+// Register message, verify-state, and error handlers on an App instance.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function registerBotHandlers(app, label) {
+    const connectionNames = allOAuthConnectionNames();
     // Override default OAuth verify-state handler.  The SDK's built-in handler
     // uses a single defaultConnectionName, which breaks multi-connection setups
     // (graph + ado + github).  The verifyState activity only carries a `state`
     // code with no connectionName, so we try each configured connection until
     // one succeeds.
-    const allConnectionNames = [
-        oauthConfig.graphConnectionName,
-        oauthConfig.adoConnectionName,
-        oauthConfig.githubConnectionName,
-    ].filter(Boolean);
     app.on("signin.verify-state", async (ctx) => {
         const { api, activity } = ctx;
         if (!activity.value?.state)
             return { status: 404 };
-        for (const cn of allConnectionNames) {
+        for (const cn of connectionNames) {
             try {
                 await api.users.token.get({
                     channelId: activity.channelId,
@@ -583,12 +638,12 @@ function startTeamsApp() {
                     connectionName: cn,
                     code: activity.value.state,
                 });
-                (0, runtime_1.emitNervesEvent)({ level: "info", event: "channel.verify_state", component: "channels", message: `verify-state succeeded for connection "${cn}"`, meta: { connectionName: cn } });
+                (0, runtime_1.emitNervesEvent)({ level: "info", event: "channel.verify_state", component: "channels", message: `[${label}] verify-state succeeded for connection "${cn}"`, meta: { connectionName: cn } });
                 return { status: 200 };
             }
             catch { /* try next */ }
         }
-        (0, runtime_1.emitNervesEvent)({ level: "warn", event: "channel.verify_state", component: "channels", message: "verify-state failed for all connections", meta: {} });
+        (0, runtime_1.emitNervesEvent)({ level: "warn", event: "channel.verify_state", component: "channels", message: `[${label}] verify-state failed for all connections`, meta: {} });
         return { status: 412 };
     });
     app.on("message", async (ctx) => {
@@ -598,16 +653,12 @@ function startTeamsApp() {
         const turnKey = teamsTurnKey(convId);
         const userId = activity.from?.id || "";
         const channelId = activity.channelId || "msteams";
-        (0, runtime_1.emitNervesEvent)({ level: "info", event: "channel.message_received", component: "channels", message: "incoming teams message", meta: { userId: userId.slice(0, 12), conversationId: convId.slice(0, 20) } });
+        (0, runtime_1.emitNervesEvent)({ level: "info", event: "channel.message_received", component: "channels", message: `[${label}] incoming teams message`, meta: { userId: userId.slice(0, 12), conversationId: convId.slice(0, 20) } });
         // Resolve pending confirmations IMMEDIATELY — before token fetches or
         // the conversation lock.  The original message holds the lock while
         // awaiting confirmation, so acquiring it here would deadlock.  Token
         // fetches are also unnecessary (and slow) for a simple yes/no reply.
         if (resolvePendingConfirmation(convId, text)) {
-            // Don't emit on this stream — the original message's stream is still
-            // active.  Opening a second streaming response in the same conversation
-            // can corrupt the first.  The original stream will show tool progress
-            // once the confirmation Promise resolves.
             return;
         }
         // If this conversation already has an active turn, steer follow-up input
@@ -621,27 +672,30 @@ function startTeamsApp() {
             return;
         }
         try {
+            // Resolve OAuth connection names for this user's tenant (supports per-tenant overrides).
+            const tenantId = activity.conversation?.tenantId;
+            const tenantOAuth = (0, config_1.resolveOAuthForTenant)(tenantId);
             // Fetch tokens for both OAuth connections independently.
             // Failures are silently caught -- the tool handler will request signin if needed.
             let graphToken;
             let adoToken;
             let githubToken;
             try {
-                const graphRes = await api.users.token.get({ userId, connectionName: oauthConfig.graphConnectionName, channelId });
+                const graphRes = await api.users.token.get({ userId, connectionName: tenantOAuth.graphConnectionName, channelId });
                 graphToken = graphRes?.token;
             }
             catch { /* no token yet — tool handler will trigger signin */ }
             try {
-                const adoRes = await api.users.token.get({ userId, connectionName: oauthConfig.adoConnectionName, channelId });
+                const adoRes = await api.users.token.get({ userId, connectionName: tenantOAuth.adoConnectionName, channelId });
                 adoToken = adoRes?.token;
             }
             catch { /* no token yet — tool handler will trigger signin */ }
             try {
-                const githubRes = await api.users.token.get({ userId, connectionName: oauthConfig.githubConnectionName, channelId });
+                const githubRes = await api.users.token.get({ userId, connectionName: tenantOAuth.githubConnectionName, channelId });
                 githubToken = githubRes?.token;
             }
             catch { /* no token yet — tool handler will trigger signin */ }
-            (0, runtime_1.emitNervesEvent)({ level: "info", event: "channel.token_status", component: "channels", message: "oauth token availability", meta: { graph: !!graphToken, ado: !!adoToken, github: !!githubToken } });
+            (0, runtime_1.emitNervesEvent)({ level: "info", event: "channel.token_status", component: "channels", message: "oauth token availability", meta: { graph: !!graphToken, ado: !!adoToken, github: !!githubToken, tenantId } });
             const teamsContext = {
                 graphToken,
                 adoToken,
@@ -661,6 +715,11 @@ function startTeamsApp() {
                 aadObjectId: activity.from?.aadObjectId,
                 tenantId: activity.conversation?.tenantId,
                 displayName: activity.from?.name,
+                graphConnectionName: tenantOAuth.graphConnectionName,
+                adoConnectionName: tenantOAuth.adoConnectionName,
+                githubConnectionName: tenantOAuth.githubConnectionName,
+                /* v8 ignore next -- bot API availability branch; requires live SDK context @preserve */
+                botApi: app.id && api ? { id: app.id, conversations: api.conversations } : undefined,
             };
             /* v8 ignore next 5 -- bot-framework integration callback; tested via handleTeamsMessage sendMessage path @preserve */
             const ctxSend = async (t) => {
@@ -678,6 +737,23 @@ function startTeamsApp() {
             _turnCoordinator.endTurn(turnKey);
         }
     });
+    app.event("error", ({ error }) => {
+        const msg = error instanceof Error ? error.message : String(error);
+        (0, runtime_1.emitNervesEvent)({ level: "error", event: "channel.app_error", component: "channels", message: `[${label}] ${msg}`, meta: {} });
+    });
+}
+// Start the Teams app in DevtoolsPlugin mode (local dev) or Bot Service mode (real Teams).
+// Mode is determined by getTeamsConfig().clientId.
+// Text is always accumulated in textBuffer and flushed periodically (chunked streaming).
+//
+// Dual-bot support: if teamsSecondary is configured with a clientId, a second App
+// instance starts on an internal port and the primary app proxies requests from
+// /api/messages-secondary to it. This lets a single App Service serve two bot
+// registrations (e.g. one per tenant) without SDK modifications.
+function startTeamsApp() {
+    const teamsConfig = (0, config_2.getTeamsConfig)();
+    const { app, mode } = createBotApp(teamsConfig);
+    registerBotHandlers(app, "primary");
     if (!process.listeners("unhandledRejection").some((l) => l.__agentHandler)) {
         const handler = (err) => {
             const msg = err instanceof Error ? err.message : String(err);
@@ -686,11 +762,54 @@ function startTeamsApp() {
         handler.__agentHandler = true;
         process.on("unhandledRejection", handler);
     }
-    app.event("error", ({ error }) => {
-        const msg = error instanceof Error ? error.message : String(error);
-        (0, runtime_1.emitNervesEvent)({ level: "error", event: "channel.app_error", component: "channels", message: msg, meta: {} });
-    });
-    const port = (0, config_2.getTeamsChannelConfig)().port;
+    /* v8 ignore next -- PORT env branch; runtime-only @preserve */
+    const port = process.env.PORT ? Number(process.env.PORT) : (0, config_2.getTeamsChannelConfig)().port;
     app.start(port);
-    (0, runtime_1.emitNervesEvent)({ level: "info", event: "channel.app_started", component: "channels", message: `Teams bot started on port ${port} with ${mode} (chunked streaming)`, meta: { port, mode } });
+    // Diagnostic: log tool count at startup to verify deploy
+    const startupTools = (0, tools_1.getToolsForChannel)((0, channel_1.getChannelCapabilities)("teams"));
+    const toolNames = startupTools.map((t) => t.function.name);
+    (0, runtime_1.emitNervesEvent)({ level: "info", event: "channel.app_started", component: "channels", message: `Teams bot started on port ${port} with ${mode} (chunked streaming)`, meta: { port, mode, toolCount: toolNames.length, hasProactive: toolNames.includes("teams_send_message") } });
+    // --- Secondary bot (dual-bot support) ---
+    // If teamsSecondary has a clientId, start a second App on an internal port
+    // and proxy /api/messages-secondary on the primary app to it.
+    /* v8 ignore start -- dual-bot proxy wiring; requires live Teams SDK + HTTP @preserve */
+    const secondaryConfig = (0, config_1.getTeamsSecondaryConfig)();
+    if (secondaryConfig.clientId) {
+        const { app: secondaryApp, mode: secondaryMode } = createBotApp(secondaryConfig);
+        registerBotHandlers(secondaryApp, "secondary");
+        secondaryApp.start(SECONDARY_INTERNAL_PORT);
+        (0, runtime_1.emitNervesEvent)({ level: "info", event: "channel.app_started", component: "channels", message: `Secondary bot started on internal port ${SECONDARY_INTERNAL_PORT} with ${secondaryMode}`, meta: { port: SECONDARY_INTERNAL_PORT, mode: secondaryMode } });
+        // Proxy: forward /api/messages-secondary on the primary app's Express
+        // to localhost:SECONDARY_INTERNAL_PORT/api/messages.
+        // The SDK's HttpPlugin exposes .post() bound to its Express instance.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const httpPlugin = app.http;
+        httpPlugin.post("/api/messages-secondary", (req, res) => {
+            const body = JSON.stringify(req.body);
+            const proxyReq = http.request({
+                hostname: "127.0.0.1",
+                port: SECONDARY_INTERNAL_PORT,
+                path: "/api/messages",
+                method: "POST",
+                headers: {
+                    ...req.headers,
+                    "content-length": Buffer.byteLength(body).toString(),
+                },
+            }, (proxyRes) => {
+                res.writeHead(proxyRes.statusCode ?? 200, proxyRes.headers);
+                proxyRes.pipe(res);
+            });
+            proxyReq.on("error", (err) => {
+                (0, runtime_1.emitNervesEvent)({ level: "error", event: "channel.proxy_error", component: "channels", message: `secondary proxy error: ${err.message}`, meta: {} });
+                if (!res.headersSent) {
+                    res.writeHead(502);
+                    res.end("Bad Gateway");
+                }
+            });
+            proxyReq.write(body);
+            proxyReq.end();
+        });
+        (0, runtime_1.emitNervesEvent)({ level: "info", event: "channel.proxy_ready", component: "channels", message: "proxy /api/messages-secondary → secondary bot ready", meta: {} });
+    }
+    /* v8 ignore stop */
 }

package/package.json

@@ -1,18 +1,20 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.20",
   "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/"
   ],
   "exports": {
-    ".": "./dist/heart/daemon/ouro-entry.js",
+    ".": "./dist/heart/daemon/daemon-cli.js",
     "./runOuroCli": "./dist/heart/daemon/daemon-cli.js"
   },
   "scripts": {
@@ -20,6 +22,7 @@
     "daemon": "tsc && node dist/heart/daemon/daemon-entry.js",
     "ouro": "tsc && node dist/heart/daemon/ouro-entry.js",
     "teams": "tsc && node dist/senses/teams-entry.js --agent ouroboros",
+    "bluebubbles": "tsc && node dist/senses/bluebubbles-entry.js --agent ouroboros",
     "test": "vitest run",
     "test:coverage:vitest": "vitest run --coverage",
     "test:coverage": "node scripts/run-coverage-gate.cjs",
@@ -31,7 +34,11 @@
     "@anthropic-ai/sdk": "^0.78.0",
     "@microsoft/teams.apps": "^2.0.5",
     "@microsoft/teams.dev": "^2.0.5",
-    "openai": "^4.78.0"
+    "openai": "^6.27.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ouroborosbot/ouroboros"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.18",

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")