@phamvuhoang/otto-core 0.5.0 → 0.6.0

package/dist/watch.js

@@ -4,13 +4,18 @@ import { createLinearClient, resolveLinearAuth, LinearApiError, } from "./linear
 import { runLoop } from "./loop.js";
 import { notifyComplete, notifyError } from "./notify.js";
 import { sleep } from "./pacing.js";
+import { describeScope } from "./task-key.js";
 import { bold, dim, greenOut, boldOut, dimOut, SYM_OUT, USE_COLOR, } from "./stream-render.js";
-/** Poll open issues carrying `label`, via gh. Never throws. */
-export function pollOpenIssues(label, cwd) {
+/**
+ * Poll open issues carrying `label`, via gh. Never throws. When `repo`
+ * (`owner/name`) is given the poll is confined to that repository (watch
+ * scoping) instead of the workspace's default repo.
+ */
+export function pollOpenIssues(label, cwd, repo) {
     try {
-        // execFileSync (no shell) so `label` is passed as a literal argv entry — a
-        // value like `$(rm -rf ~)` can never be shell-evaluated. See SECURITY.md.
-        // stderr is piped (not ignored) so a failure's message can be classified.
+        // execFileSync (no shell) so `label`/`repo` are passed as literal argv
+        // entries — a value like `$(rm -rf ~)` can never be shell-evaluated. See
+        // SECURITY.md. stderr is piped (not ignored) so failures can be classified.
         const out = execFileSync("gh", [
             "issue",
             "list",
@@ -18,6 +23,7 @@ export function pollOpenIssues(label, cwd) {
             "open",
             "--label",
             label,
+            ...(repo ? ["--repo", repo] : []),
             "--json",
             "number",
         ], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
@@ -58,6 +64,7 @@ export async function pollLinearIssues(deps) {
         const issues = await client.listIssues({
             label: deps.label,
             team: deps.team,
+            project: deps.project,
             limit: deps.limit ?? 50,
         });
         return { ok: true, count: issues.length };
@@ -71,7 +78,28 @@ export async function pollLinearIssues(deps) {
 }
 const GH_PROVIDER = { name: "gh", authCmd: "gh auth login" };
 export async function runWatch(opts) {
-    const { stages, iterations, workspaceDir, packageDir, watchIntervalSec, watchLabel, budgetUsd, cooldownMs, maxRetries, reviewLenses, notify = false, bin = "otto-ghafk", pollIssues = pollOpenIssues, provider = GH_PROVIDER, } = opts;
+    const { stages, iterations, workspaceDir, packageDir, watchIntervalSec, watchLabel, budgetUsd, cooldownMs, maxRetries, reviewLenses, notify = false, bin = "otto-ghafk", pollIssues = pollOpenIssues, provider = GH_PROVIDER, scope, scopes, } = opts;
+    // The scopes this daemon rotates through each cycle. Multi-target watch
+    // passes `scopes`; otherwise a single `scope` (or the workspace default,
+    // represented by a lone `undefined`).
+    const scopeList = scopes && scopes.length > 0 ? scopes : [scope];
+    // Derive the gh `--repo` filter from a github scope; other providers (Linear)
+    // carry their scope in the label/team the poller already honors.
+    const ghRepoOf = (s) => s?.provider === "github" && s.owner && s.repo
+        ? `${s.owner}/${s.repo}`
+        : undefined;
+    // The Linear project for a scope. Unlike github (which gets a poll `--repo`
+    // arg), the Linear poller reads OTTO_LINEAR_PROJECT from the env, so the
+    // daemon pins it before each poll/run to confine that scope.
+    const linearProjectOf = (s) => s?.provider === "linear" && s.project ? s.project : undefined;
+    // Human-readable scope prefix for a poll line (e.g. "github acme/web ").
+    const labelOf = (s) => s ? `${describeScope(s)} ` : "";
+    // The banner names every scope so a maintainer sees the exact watch surface.
+    const bannerScope = scopeList
+        .filter((s) => !!s)
+        .map(describeScope)
+        .join(", ");
+    const scopeLabel = bannerScope ? `${bannerScope} ` : "";
     const releaser = acquire({ reason: `${bin} watch` });
     let released = false;
     const releaseOnce = () => {
@@ -92,7 +120,7 @@ export async function runWatch(opts) {
     const onSigterm = onSig(143);
     process.on("SIGINT", onSigint);
     process.on("SIGTERM", onSigterm);
-    process.stderr.write(`${USE_COLOR ? dim("watching") + " " + bold(`label:${watchLabel} every ${watchIntervalSec}s`) : `watching label:${watchLabel} every ${watchIntervalSec}s`}\n`);
+    process.stderr.write(`${USE_COLOR ? dim("watching") + " " + bold(`${scopeLabel}label:${watchLabel} every ${watchIntervalSec}s`) : `watching ${scopeLabel}label:${watchLabel} every ${watchIntervalSec}s`}\n`);
     let cumulativeCost = 0;
     // Track idle state so the "no open issues" line prints only on the
     // idle→busy→idle transition, not on every empty poll — otherwise an
@@ -107,42 +135,69 @@ export async function runWatch(opts) {
                     notifyComplete(0, false);
                 return;
             }
-            const poll = await pollIssues(watchLabel, workspaceDir);
-            if (!poll.ok) {
-                // Broken poll — say *why*, distinctly from an idle queue, and keep
-                // polling (auth may get fixed / a transient failure may clear).
-                wasIdle = false;
-                const suffix = poll.detail ? ` — ${poll.detail}` : "";
-                const why = poll.auth
-                    ? `${provider.name} not authenticated — run '${provider.authCmd}' (label ${watchLabel})${suffix}`
-                    : `${provider.name} issue poll failed (label ${watchLabel})${suffix}`;
-                process.stderr.write(`${dim(why)}\n`);
-            }
-            else if (poll.count > 0) {
-                wasIdle = false;
-                process.stderr.write(`${dim(`${poll.count} open issue(s) labelled ${watchLabel} — running loop`)}\n`);
-                const remaining = budgetUsd != null ? budgetUsd - cumulativeCost : undefined;
-                const outcome = await runLoop({
-                    stages,
-                    inputs: "",
-                    iterations,
-                    workspaceDir,
-                    packageDir,
-                    budgetUsd: remaining,
-                    cooldownMs,
-                    maxRetries,
-                    reviewLenses,
-                    noKeepAlive: true,
-                    signal: daemonAbort.signal,
-                    bin,
-                    cliVersion: opts.cliVersion,
-                });
-                cumulativeCost += outcome.costUsd;
-                process.stderr.write(`${dim(`watch run done — cumulative $${cumulativeCost.toFixed(2)}`)}\n`);
+            // Poll every scope this cycle. Run one loop for the FIRST scope with
+            // work, then break back to the sleep+repoll — one loop at a time, no
+            // parallel mutation of the workspace. A failed poll for one scope is
+            // logged and skipped so it never blocks polling the others.
+            let ran = false;
+            let allIdle = true;
+            for (const s of scopeList) {
+                const sRepo = ghRepoOf(s);
+                const sProject = linearProjectOf(s);
+                const sLabel = labelOf(s);
+                // Pin the Linear project before polling so the poller (which reads it
+                // from the inherited env, not a poll arg) is confined to this scope;
+                // it also stays pinned for the loop run below. GitHub uses the sRepo
+                // poll arg instead and pins OTTO_GITHUB_REPO only on the run.
+                if (sProject)
+                    process.env.OTTO_LINEAR_PROJECT = sProject;
+                const poll = await pollIssues(watchLabel, workspaceDir, sRepo);
+                if (!poll.ok) {
+                    // Broken poll — say *why*, distinctly from an idle queue, and keep
+                    // polling (auth may get fixed / a transient failure may clear).
+                    allIdle = false;
+                    wasIdle = false;
+                    const suffix = poll.detail ? ` — ${poll.detail}` : "";
+                    const why = poll.auth
+                        ? `${sLabel}${provider.name} not authenticated — run '${provider.authCmd}' (label ${watchLabel})${suffix}`
+                        : `${sLabel}${provider.name} issue poll failed (label ${watchLabel})${suffix}`;
+                    process.stderr.write(`${dim(why)}\n`);
+                    continue;
+                }
+                if (poll.count > 0) {
+                    allIdle = false;
+                    wasIdle = false;
+                    process.stderr.write(`${dim(`${sLabel}${poll.count} open issue(s) labelled ${watchLabel} — running loop`)}\n`);
+                    // Confine this loop's `gh` commands (render-time tags + the spawned
+                    // agent) to the selected scope by pinning OTTO_GITHUB_REPO before the
+                    // run; single-target left it set in run-bin, this covers multi-target.
+                    if (sRepo)
+                        process.env.OTTO_GITHUB_REPO = sRepo;
+                    const remaining = budgetUsd != null ? budgetUsd - cumulativeCost : undefined;
+                    const outcome = await runLoop({
+                        stages,
+                        inputs: "",
+                        iterations,
+                        workspaceDir,
+                        packageDir,
+                        budgetUsd: remaining,
+                        cooldownMs,
+                        maxRetries,
+                        reviewLenses,
+                        noKeepAlive: true,
+                        signal: daemonAbort.signal,
+                        bin,
+                        cliVersion: opts.cliVersion,
+                    });
+                    cumulativeCost += outcome.costUsd;
+                    process.stderr.write(`${dim(`${sLabel}watch run done — cumulative $${cumulativeCost.toFixed(2)}`)}\n`);
+                    ran = true;
+                    break;
+                }
             }
-            else if (!wasIdle) {
+            if (!ran && allIdle && !wasIdle) {
                 // First empty poll after activity — announce idle once, then stay quiet
-                // until the queue becomes non-empty (or a poll fails) and idles again.
+                // until a queue becomes non-empty (or a poll fails) and idles again.
                 wasIdle = true;
                 process.stderr.write(`${dim(`no open issues labelled ${watchLabel} — idle, next poll in ${watchIntervalSec}s`)}\n`);
             }

package/dist/watch.js.map

@@ -1 +1 @@
-{"version":3,"file":"watch.js","sourceRoot":"","sources":["../src/watch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../src/watch.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phamvuhoang/otto-core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Claude Code AFK orchestration: iteration loop, native-sandbox runner, template renderer.",
   "type": "module",
   "license": "MIT",

package/templates/apply-review.md

@@ -30,6 +30,16 @@
 
 When every actionable finding has been addressed (fixed, or already fixed in git, or recorded as a follow-up), produce the completion report (see COMPLETION REPORT below), then output `<promise>NO MORE TASKS</promise>`.
 
+# TASK KEY
+
+Per-task artifacts (spec, plan, follow-ups) live together under
+`.otto/tasks/<task-key>/`, so everything Otto knows about a task is in one place.
+Resolve the task key for THIS run from the current git branch: run
+`git branch --show-current` and take the **final path segment** (the part after the
+last `/`) — e.g. `otto/issue-21` → `issue-21`, `feat/gh-acme-web-14` →
+`gh-acme-web-14`. If the branch name has no `/`, use it whole. Use this key in the
+follow-ups path below.
+
 # TRIAGE
 
 Classify each finding (judge from the review's own language — severity labels, "follow-up", "operational", "cosmetic", "low risk"):
@@ -56,7 +66,9 @@ Pick the highest-value actionable finding not yet addressed. Implement the fix.
 
 # RECORD FOLLOW-UPS
 
-For each Deferred / follow-up finding, append a terse entry to `./.otto/review-followups.md` (create it lazily). Use a dated `##` heading for this review, then one bullet per finding with its severity and why it is deferred. This file is git-tracked — commit it WITH the related fix (do not make a separate commit just for it).
+For each Deferred / follow-up finding, append a terse entry to the **task-local** follow-ups file `./.otto/tasks/<task-key>/followups.md` (create it and its parent dir lazily), using the task key resolved above. Use a dated `##` heading for this review, then one bullet per finding with its severity and why it is deferred. Keeping follow-ups beside the task's spec/plan means everything Otto knows about a task is in one place, while staying globally summarizable by globbing `.otto/tasks/*/followups.md`.
+
+Read the task-local file first (it may already hold this task's prior deferrals). The legacy global `./.otto/review-followups.md` is still READ as a fallback for older runs (see `<existing-followups>`) for one release, but do NOT append new entries there. This file is git-tracked — commit it WITH the related fix (do not make a separate commit just for it).
 
 # COMMIT
 
@@ -76,8 +88,9 @@ contract below onto this round:
 - **What Changed / Evidence:** the findings you CONFIRMED and fixed, each with
   its `fix(review):` commit SHA and the review section it came from; the
   feedback loops you ran (tests / typecheck) and their result.
-- **Gaps And Follow-Ups:** findings you DEFERRED to `./.otto/review-followups.md`
-  (with why), and any REJECTED / won't-fix findings with their reason. Verdict
+- **Gaps And Follow-Ups:** findings you DEFERRED to
+  `./.otto/tasks/<task-key>/followups.md` (with why), and any REJECTED / won't-fix
+  findings with their reason. Verdict
   defaults to **Needs human review** when any actionable finding was left
   unfixed.
 

package/templates/ghafk-issue.md

@@ -12,12 +12,14 @@
 
 <issue>
 
-!?`gh issue view "$OTTO_ISSUE" --json number,title,state|||Issue not found`
+!?`gh issue view "$OTTO_ISSUE" ${OTTO_GITHUB_REPO:+--repo "$OTTO_GITHUB_REPO"} --json number,title,state|||Issue not found`
 
-Full issue body + comments spilled to: @spill?:issue.json=`gh issue view "$OTTO_ISSUE" --json number,title,body,comments,state|||[]`
+Full issue body + comments spilled to: @spill?:issue.json=`gh issue view "$OTTO_ISSUE" ${OTTO_GITHUB_REPO:+--repo "$OTTO_GITHUB_REPO"} --json number,title,body,comments,state|||[]`
 
 `Read` that file to get the full body and comments before acting on the issue.
 
+If `$OTTO_GITHUB_REPO` is set (run scoped with `--repo owner/name`), pass `--repo "$OTTO_GITHUB_REPO"` to every `gh` command you run yourself (issue comment, pr create) so completion targets that repo. If unset, `gh` uses the workspace's own repo.
+
 </issue>
 
 # THE TASK

package/templates/ghafk.md

@@ -14,13 +14,13 @@
 
 <issues-summary>
 
-`gh issue list --state open --limit 50 --json number,title,labels`
+`gh issue list ${OTTO_GITHUB_REPO:+--repo "$OTTO_GITHUB_REPO"} --state open --limit 50 --json number,title,labels`
 
 </issues-summary>
 
 <issues-full-file>
 
-Full issue bodies + comments spilled to: @spill?:issues.json=`gh issue list --state open --limit 50 --json number,title,body,labels,comments|||[]`
+Full issue bodies + comments spilled to: @spill?:issues.json=`gh issue list ${OTTO_GITHUB_REPO:+--repo "$OTTO_GITHUB_REPO"} --state open --limit 50 --json number,title,body,labels,comments|||[]`
 
 Read that file with `Read` (use `offset`/`limit` if it is large) to get bodies and comments before picking a task. The `<issues-summary>` block above is the lean index for triage.
 

package/templates/ghprompt.md

@@ -7,6 +7,8 @@ Two views of open GitHub issues are provided at the start of context:
 
 You will work on the AFK issues only, not the HITL ones. Label filtering uses the `labels` field in the summary.
 
+**Repo scope.** If the `$OTTO_GITHUB_REPO` environment variable is set (the run was scoped with `--repo owner/name`), the issue list above is already confined to that repo — work only on those issues, and pass `--repo "$OTTO_GITHUB_REPO"` to every `gh` command you run yourself (e.g. `gh issue comment`, `gh pr create`) so completion targets the same repo. If it is unset, `gh` uses the workspace's own repo as before.
+
 You've also been passed a file containing the last few commits. Review these to understand what work has been done.
 
 If all AFK tasks are complete, output <promise>NO MORE TASKS</promise>.

package/templates/linearprompt.md

@@ -9,7 +9,9 @@ Two views of open Linear issues are provided at the start of context:
   large) once you have picked an issue you want to act on.
 
 Issue selection is already filtered to open Linear issues carrying the `otto`
-label (override via `OTTO_LINEAR_LABEL`, narrow to a team via `OTTO_LINEAR_TEAM`).
+label (override via `OTTO_LINEAR_LABEL`, narrow to a team via `OTTO_LINEAR_TEAM`,
+and narrow to a project via `OTTO_LINEAR_PROJECT`). Work only on the issues the
+list shows — they are already confined to the configured team/project scope.
 
 You've also been passed a file containing the last few commits. Review these to
 understand what work has been done.

package/templates/superpowers.md

@@ -10,29 +10,41 @@ If the `superpowers:brainstorming`, `superpowers:writing-plans`, and
 fuller guidance. If they are not installed, follow the inline protocol below —
 it is self-contained.
 
-## 0. Resolve the task key
+## 0. Resolve the task key and artifact paths
 
 - GitHub issue run → task-key = `issue-<issue number>`.
 - Plan/PRD run → task-key = a stable slug from the primary plan-file basename
   (e.g. `docs/plans/foo.md` → `foo`). If inputs are inline text, use a short
   kebab-case of the task title.
 
-Spec path: `.otto/specs/<task-key>-design.md`
-Plan path: `.otto/plans/<task-key>.md`
+Per-task artifacts live together under one task directory, so everything Otto
+knows about a task is in one place:
+
+- Task dir: `.otto/tasks/<task-key>/`
+- Spec path: `.otto/tasks/<task-key>/spec.md`
+- Plan path: `.otto/tasks/<task-key>/plan.md`
+
+Always **WRITE** the new task-grouped layout. The legacy flat layout
+(`.otto/specs/<task-key>-design.md` + `.otto/plans/<task-key>.md`) is still
+**READ** as a fallback (see the CLARITY GATE), so a task created before this
+layout continues without re-brainstorming.
 
 ## 1. CLARITY GATE
 
-Check whether `.otto/specs/<task-key>-design.md` already exists.
+Check whether the spec already exists — look under the new task dir
+`.otto/tasks/<task-key>/spec.md` first, then fall back to the legacy flat path
+`.otto/specs/<task-key>-design.md`.
 
-- **Spec exists** → skip brainstorming. Read the spec and
-  `.otto/plans/<task-key>.md`, pick the next unchecked task, and go to
+- **Spec exists** → skip brainstorming. Read the spec and its matching plan
+  (`.otto/tasks/<task-key>/plan.md`, or legacy `.otto/plans/<task-key>.md`),
+  pick the next unchecked task, and go to
   TDD IMPLEMENT (section 3). If every plan task is checked AND the feedback
   loops pass, output `<promise>NO MORE TASKS</promise>`.
 - **No spec** → judge the input's clarity. It is UNCLEAR if any of: no
   plan/PRD provided; a vague directive ("make it better"); missing acceptance
   criteria; multiple plausible interpretations; internal contradictions.
   - Clear enough → go straight to TDD IMPLEMENT (section 3). Optionally jot a
-    short plan to `.otto/plans/<task-key>.md` first.
+    short plan to `.otto/tasks/<task-key>/plan.md` first.
   - Unclear → AUTONOMOUS BRAINSTORM (section 2).
 
 ## 2. AUTONOMOUS BRAINSTORM (no human in the loop)
@@ -43,10 +55,10 @@ Play both sides of a brainstorming session:
    scope, constraints, success criteria, edge cases).
 2. Answer each one yourself with the most reasonable default given the repo's
    existing patterns. Prefer the simplest viable option (YAGNI).
-3. Write `.otto/specs/<task-key>-design.md` containing: Problem, Approach, an
+3. Write `.otto/tasks/<task-key>/spec.md` containing: Problem, Approach, an
    **Assumptions** section listing each `question → chosen answer → rationale`,
    and Testing notes.
-4. Write `.otto/plans/<task-key>.md` as an ordered checklist of bite-sized,
+4. Write `.otto/tasks/<task-key>/plan.md` as an ordered checklist of bite-sized,
    testable tasks (one `- [ ]` per task).
 5. Do NOT wait for approval — the written assumptions are the record.
 
@@ -63,7 +75,8 @@ Implement exactly one task, test-first:
 2. Run it; confirm it fails for the right reason.
 3. Write the minimal code to make it pass.
 4. Run the feedback loops described below until green.
-5. Update `.otto/plans/<task-key>.md`: check off the task. If a new durable,
+5. Update the plan you read (`.otto/tasks/<task-key>/plan.md`, or its legacy
+   fallback `.otto/plans/<task-key>.md`): check off the task. If a new durable,
    reusable learning emerged, append it to `.otto/LEARNINGS.md`.
 
 Commit the code, the updated spec/plan, and LEARNINGS together in the single