{
  "error": {
    "message": "{\"error\":{\"message\":\"{\\n  \\\"error\\\": {\\n    \\\"code\\\": 403,\\n    \\\"message\\\": \\\"Your API key was reported as leaked. Please use another API key.\\\",\\n    \\\"status\\\": \\\"PERMISSION_DENIED\\\"\\n  }\\n}\\n\",\"code\":403,\"status\":\"Forbidden\"}}",
    "stack": "ApiError: {\"error\":{\"message\":\"{\\n  \\\"error\\\": {\\n    \\\"code\\\": 403,\\n    \\\"message\\\": \\\"Your API key was reported as leaked. Please use another API key.\\\",\\n    \\\"status\\\": \\\"PERMISSION_DENIED\\\"\\n  }\\n}\\n\",\"code\":403,\"status\":\"Forbidden\"}}\n    at throwErrorIfNotOK (file:///home/claude/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-67TFD6HC.js:36178:24)\n    at process.processTicksAndRejections (node:internal/process/task_queues:103:5)\n    at async file:///home/claude/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-67TFD6HC.js:35941:7\n    at async Models.generateContentStream (file:///home/claude/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-67TFD6HC.js:37037:16)\n    at async file:///home/claude/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-UQGLVPZQ.js:278827:19\n    at async file:///home/claude/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-UQGLVPZQ.js:255732:23\n    at async retryWithBackoff (file:///home/claude/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-UQGLVPZQ.js:275704:23)\n    at async GeminiChat.makeApiCallAndProcessStream (file:///home/claude/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-UQGLVPZQ.js:311287:28)\n    at async GeminiChat.streamWithRetries (file:///home/claude/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-UQGLVPZQ.js:311125:29)\n    at async Turn.run (file:///home/claude/.npm-global/lib/node_modules/@google/gemini-cli/bundle/chunk-UQGLVPZQ.js:311618:24)"
  },
  "context": [
    {
      "role": "user",
      "parts": [
        {
          "text": "<session_context>\nThis is the Gemini CLI. We are setting up the context for our chat.\nToday's date is Wednesday, June 24, 2026 (formatted according to the user's locale).\nMy operating system is: linux\nThe project's temporary directory is: /home/claude/.gemini/tmp/pr-review-wo6i2t\n- **Workspace Directories:**\n  - /tmp/pr-review-WO6I2t\n- **Directory Structure:**\n\nShowing up to 200 items (files + folders).\n\n/tmp/pr-review-WO6I2t/\n\n\n\n</session_context>"
        }
      ]
    },
    {
      "role": "user",
      "parts": [
        {
          "text": "You are a dedicated code reviewer for this repository. You are deeply familiar with its conventions and codebase.\n\n## Project Conventions (from CLAUDE.md)\n## gstack (REQUIRED — global install)\n\n**Before doing ANY work, verify gstack is installed:**\n\n```bash\ntest -d ~/.claude/skills/gstack/bin && echo \"GSTACK_OK\" || echo \"GSTACK_MISSING\"\n```\n\nIf GSTACK_MISSING: STOP. Do not proceed. Tell the user:\n\n> gstack is required for all AI-assisted work in this repo.\n> Install it:\n> ```bash\n> git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack\n> cd ~/.claude/skills/gstack && ./setup --team\n> ```\n> Then restart your AI coding tool.\n\nDo not skip skills, ignore gstack errors, or work around missing gstack.\n\nUsing gstack skills: After install, skills like /qa, /ship, /review, /investigate,\nand /browse are available. Use /browse for all web browsing.\nUse ~/.claude/skills/gstack/... for gstack file paths (the global path).\n\n\n## Review Task\n\nPR #32: \"docs(orchestration): scope Pi tracker requirements\"\n\nDescription:\n## Summary\n\n- Scope remaining Pi operational docs so Linear is an optional tracker adapter, not a default requirement.\n- Update `.pi/RULES.md`, `.pi/AGENT.md`, `heartbeat-test.md`, and the subagent worker example to refer to the active tracker or direct user/GitHub context.\n- Remove the phantom `AGENT_TASK_ID` docs contract; the wrapper defines `AGENT_ISSUE_ID`, `AGENT_SESSION_ID`, and `AGENT_BRANCH`.\n- Leave `docs/AGENTS.md` and `docs/adapters/linear.md` to PR #30 so this PR stays non-overlapping.\n\n## Validation\n\n- `git diff --check -- .pi/RULES.md .pi/AGENT.md heartbeat-test.md packages/coding-agent/examples/extensions/subagent/agents/worker.md`\n- `rg -n 'AGENT_TASK_ID' heartbeat-test.md packages/coding-agent/examples/extensions/subagent/agents/worker.md .pi/AGENT.md .pi/RULES.md || true`\n- `npm run check`\n\n## Notes\n\n- Stacked on #29 because current `main` has stale generated model fixture IDs that fail `npm run check`; #29 owns that unrelated test-fixture repair.\n- PR #30 owns the main orchestration guide and optional Linear adapter reference.\n- PR #31 is already merged.\n\n\nReview the diff below. Provide your response as a JSON object with these keys:\n- \"summary\": a concise markdown summary. Tag issues with severity: [blocking] for must-fix, [suggestion] for improvements, [nitpick] for style.\n- \"comments\": array of { \"path\", \"line\", \"body\" } — inline review comments with severity tags\n- \"verdict\": \"approve\" (no blocking issues) or \"request_changes\" (blocking issues found)\n- \"workflow_suggestions\": array of strings — suggestions for improving the development workflow (e.g., \"Consider splitting this PR\", \"Add a pre-commit hook for X\")\n\nFocus on meaningful issues: bugs, security, performance, correctness. Skip trivial style nits.\nReturn ONLY valid JSON, no markdown fences.\n\nDiff:\n```diff\nFile: .pi/AGENT.md (modified, +7/-7)\n@@ -4,7 +4,7 @@\n \n ## What This Is\n \n-Pi is an orchestrator agent running on Gautam's iMac. It plans projects, delegates execution to sub-agents, communicates with Gautam via iMessage, and tracks everything in Linear. Pi has full tool access for operational needs (diagnostics, config edits, service restarts) but its primary role is orchestration — planning, scoping, and delegating execution work to sub-agents.\n+Pi is an orchestrator agent running on Gautam's iMac. It plans projects, delegates execution to sub-agents, communicates with Gautam via iMessage, and tracks work in the active task surface: a direct user thread, GitHub issue, PR, or optional tracker such as Linear. Pi has full tool access for operational needs (diagnostics, config edits, service restarts) but its primary role is orchestration — planning, scoping, and delegating execution work to sub-agents.\n \n ## Architecture\n \n@@ -27,7 +27,7 @@ SendBlue Cloud ──webhook──▶ Tailscale Funnel :8443\n                          Pi Session (this agent)\n                             ├── Plans & scopes work\n                             ├── Delegates to sub-agents\n-                            ├── Syncs state to Linear\n+                            ├── Syncs state to the active task surface\n                             └── Reports back to Gautam via imessage_reply\n ```\n \n@@ -66,7 +66,7 @@ SendBlue Cloud ──webhook──▶ Tailscale Funnel :8443\n | System | Access | Purpose |\n |--------|--------|---------|\n | GitHub | gh CLI as gbharg | Code, branches, PRs |\n-| Linear | API key + webhook | Project tracking (PI team) |\n+| Linear | API key + webhook | Optional project tracking (PI team) |\n | SendBlue | API + webhook | iMessage send/receive (+16292925296) |\n | Tailscale | Funnel on :8443 | Public webhook endpoint |\n \n@@ -95,12 +95,12 @@ Sub-agents are spawned with `--no-extensions` (no memory, no hooks) but sessions\n ## How It All Connects\n \n 1. Gautam texts Pi via iMessage → SendBlue webhook → Pi extension → appears in session\n-2. Pi plans work, creates specs, creates Linear issues\n+2. Pi plans work and creates specs; it creates tracker issues only when that workflow is active\n 3. Pi spawns sub-agents with full CONTEXT/TASK/SCOPE/CONSTRAINTS/EXPECTED OUTPUT\n 4. Sub-agents return structured output; Pi reviews and synthesizes\n-5. Pi updates Linear, commits to GitHub, texts Gautam with results\n-6. Linear webhooks notify Pi of external changes (Gautam updates issues, other agents comment)\n-7. EOD cron verifies everything is synced and nothing was dropped\n+5. Pi updates the originating task surface, commits to GitHub, texts Gautam with results\n+6. Tracker webhooks notify Pi of external changes when a tracker is configured\n+7. EOD cron verifies active commitments are synced and nothing was dropped\n \n ## Infrastructure references\n \n\nFile: .pi/RULES.md (modified, +8/-4)\n@@ -3,6 +3,9 @@\n This file is the single source of truth for how all agents operate in this repository. Read it in full before every session. Follow it without exception.\n \n Adapted from OpenClaw post-mortem (PI-13, AI-627). Every rule exists because violating it has caused real failures.\n+Linear references below apply only when the active workflow is Linear-backed.\n+Direct user requests and GitHub issue work do not require Linear.\n+The active task surface is whichever system originated the work: a direct user thread, GitHub issue, PR, or optional tracker such as Linear.\n \n ---\n \n@@ -20,10 +23,11 @@ Adapted from OpenClaw post-mortem (PI-13, AI-627). Every rule exists because vio\n ## Git Discipline\n \n 1. **Always branch. No exceptions.** Even one-line fixes. Branch off main, PR to merge.\n-2. **No project branches.** Linear projects are grouping only. Every change goes to main independently.\n+2. **No project branches.** Tracker projects are grouping only. Every change goes to main independently.\n 3. **Conventional branch naming.** Format: `type/description` (feat/, fix/, chore/, docs/, etc.)\n-4. **Conventional commits.** Format: `type(scope): description` referencing Linear issue.\n-5. **Every commit links to a Linear issue.** No orphan commits. The commit message is the enforcement.\n+4. **Conventional commits.** Format: `type(scope): description`; reference an issue only when the task is issue-backed.\n+5. **Every commit has traceable context.** Trace to the active issue, user request, or PR.\n+   - Use issue-closing keywords only when the merge should close that issue.\n 6. **Keep branches short-lived.** One focused change per branch, merged within 1-2 sessions.\n 7. **Do not rebase or force-push shared branches.** Merge main into your branch if needed.\n \n@@ -52,7 +56,7 @@ Adapted from OpenClaw post-mortem (PI-13, AI-627). Every rule exists because vio\n \n 1. **Compaction threshold: target 30%, soft 50%, priority 60%.** I own the decision — hooks nudge, don't trigger.\n 2. **Checkpoint before compaction.** Write state.md + context.md before any context loss event.\n-3. **Everything in Linear.** Any commitment goes in Linear immediately. No exceptions.\n+3. **Use the active task surface.** Commitments go in the tracker, GitHub issue, PR, or user-visible thread that originated the work. Linear is optional.\n 4. **Living documentation.** Update docs in real-time during execution, not after.\n \n ---\n\nFile: docs/AGENTS.md (modified, +33/-30)\n@@ -2,7 +2,7 @@\n \n ## Overview\n \n-This repo implements a multi-agent orchestration system built on pi-mono. Pi (the orchestrator) acts as CTO, communicating with Gautam via iMessage and delegating work to specialized sub-agents. Linear serves as the orchestration bus and single source of truth for task state. All work flows through Linear issues, with sub-agents executing tasks in isolated branches and submitting PRs for review. The system enforces strict lifecycle protocols, conventional commit standards, and comprehensive audit trails via git notes.\n+This repo implements a multi-agent orchestration system built on pi-mono. Pi (the orchestrator) acts as CTO, communicating with Gautam via iMessage and delegating work to specialized sub-agents. In the Linear-backed deployment described below, Linear serves as the orchestration bus and source of truth for task state. Direct repository work and other tracker-backed workflows do not require Linear; when no tracker issue is part of the task, use a conventional branch, commit, and GitHub PR without Linear-only lifecycle steps. The system enforces strict lifecycle protocols, conventional commit standards, and comprehensive audit trails via git notes.\n \n ## Architecture\n \n@@ -34,7 +34,7 @@ This repo implements a multi-agent orchestration system built on pi-mono. Pi (th\n                    │\n                    ▼\n                Git Operations\n-               - Branch per issue\n+               - Branch per task\n                - Conventional commits\n                - Co-Authored-By trailers\n                - Git notes for session logs\n@@ -47,18 +47,18 @@ This repo implements a multi-agent orchestration system built on pi-mono. Pi (th\n                - Branch protection on main\n ```\n \n-**Flow**: Gautam → iMessage → Pi → Linear Issue → Sub-Agent → Git Branch → PR → Review → Merge → Done\n+**Linear-backed flow**: Gautam → iMessage → Pi → Linear Issue → Sub-Agent → Git Branch → PR → Review → Merge → Done\n \n-**Key Principle**: Linear is the single source of truth. Pi reads board state via webhooks, spawns agents assigned to Linear issues, agents report progress via AgentActivity API, and Pi never directly edits code.\n+**Key Principle**: Tracker state is authoritative only for the tracker-backed workflow in use. In Linear-backed mode, Pi reads board state via webhooks, spawns agents assigned to Linear issues, agents report progress via AgentActivity API, and Pi never directly edits code.\n \n ## Agent Roles\n \n | Name | Description | Model | Tools | Persistence |\n |------|-------------|-------|-------|-------------|\n-| `worker` | General-purpose implementation | `claude-sonnet-4-5` | read, write, edit, bash | Disposable (killed after In Review) |\n+| `worker` | General-purpose implementation | `claude-sonnet-4-5` | read, write, edit, bash | Disposable (killed after final review in tracker-backed mode) |\n | `worker-full` | Full-capability implementation | `claude-sonnet-4-20250514` | read, write, edit, bash | Disposable |\n | `worker-readonly` | Read-only analysis/audit | `claude-sonnet-4-20250514` | read, grep, find, ls, bash | Disposable |\n-| `researcher` | Topic investigation | `claude-opus-4-6` | read, grep, find, ls, bash | Persistent (Linear app user) |\n+| `researcher` | Topic investigation | `claude-opus-4-6` | read, grep, find, ls, bash | Persistent (tracker app user in Linear-backed mode) |\n | `reviewer` | Code review specialist | `claude-sonnet-4-5` | read, bash | Persistent (learns patterns) |\n | `planner` | Spec/plan creation | `claude-sonnet-4-5` | read | Disposable |\n | `scout` | Fast recon/exploration | `claude-haiku-4-5` | read, bash (compressed context) | Disposable |\n@@ -69,10 +69,10 @@ This repo implements a multi-agent orchestration system built on pi-mono. Pi (th\n \n ## Lifecycle\n \n-Sub-agents follow a strict 5-phase lifecycle enforced by `scripts/agent-wrapper.sh`:\n+When invoked through `scripts/agent-wrapper.sh` in Linear-backed mode, sub-agents follow a strict 5-phase lifecycle:\n \n ### Phase 1: Setup\n-- Create Linear AgentSession on issue\n+- Create Linear AgentSession on the issue\n - Generate branch name from issue title (conventional format)\n - **Sequential mode**: Create branch off `main`\n - **Parallel mode**: Create branch off task branch, add worktree\n@@ -106,21 +106,22 @@ Sub-agents follow a strict 5-phase lifecycle enforced by `scripts/agent-wrapper.\n - **Sequential mode**: No teardown needed\n - **Parallel mode**: Remove worktree, leave branches for orchestrator\n \n-**Critical**: Agents are killed after Phase 4. Session state persists in git notes and Linear. New agent spawns reconstruct context from external state.\n+**Critical**: Agents are killed after Phase 4. Linear-backed session state persists in git notes and Linear. New agent spawns reconstruct context from external state.\n \n ## Git Model\n \n ### Branch Naming (conventional-branch.github.io)\n - **Sequential**: `feat/PI-XXX-description` (branch off `main`)\n - **Parallel**: `feat/PI-XXX/agent-<role>` (branch off task branch `feat/PI-XXX-description`)\n - Examples: `feat/pi-56-completion-protocol`, `feat/pi-65/agent-worker`, `fix/pi-72-linear-cleanup`\n+- **Direct/no-tracker work**: use the same conventional branch style without a tracker ID, for example `docs/optional-tracker-workflow`\n \n ### Commit Conventions\n Format: `type(scope): description`\n \n **Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `build`, `ci`\n \n-**Required trailer**: `Co-Authored-By: agent/<role> <session-id@noreply>`\n+**Required for wrapper-spawned agent commits**: `Co-Authored-By: agent/<role> <session-id@noreply>`\n \n Example:\n ```\n@@ -147,9 +148,9 @@ Co-Authored-By: agent/worker-full 550e8400-e29b-41d4-a716-446655440000@noreply\n 5. Pi creates final PR: `feat/PI-XXX-description` → `main`\n 6. Review gates apply to final PR\n \n-**Always**: Every commit links to Linear issue via `fixes #PI-XXX` in commit message.\n+**Linear-backed mode**: commits created for a Linear issue link to that issue via `fixes #PI-XXX` or `closes #PI-XXX` in the commit message. Direct/no-tracker commits omit Linear references.\n \n-## Linear Integration\n+## Linear-backed Integration\n \n ### State Machine\n \n@@ -208,16 +209,18 @@ Backlog → Todo → Plan → In Progress → In Review → Done\n \n ## Dependencies\n \n-### Required Tools\n-- `gh` (GitHub CLI) - PR creation, issue management\n-- `jq` - JSON parsing for Linear API responses\n-- `curl` - Linear API calls\n+### Base Tools\n+- `gh` (GitHub CLI) - PR creation and issue management when a GitHub issue is involved\n - `tsx` - TypeScript execution for Pi CLI\n - `git` - Version control (with `git notes` support)\n - `node` (v18+) - Node.js runtime\n - `npm` - Package manager\n \n-### Required Environment Variables\n+### Linear-backed Tools\n+- `jq` - JSON parsing for Linear API responses\n+- `curl` - Linear API calls\n+\n+### Linear-backed Environment Variables\n | Variable | Description | Used By |\n |----------|-------------|---------|\n | `LINEAR_API_KEY` | User API key for Pi board queries | Pi, wrapper setup |\n@@ -235,16 +238,16 @@ Backlog → Todo → Plan → In Progress → In Review → Done\n \n ### Hard Rules (All Agents)\n \n-1. **Single source of truth**: Linear is authoritative for task state. Never use custom IDs.\n-2. **Everything is an issue**: All work that results in action must have a Linear issue.\n+1. **Single source of truth**: Use the active tracker or user-provided task as authoritative. Do not invent custom IDs.\n+2. **Issue-backed when provided**: If the task starts from a GitHub or Linear issue, preserve that issue link. If no issue is provided, do not create one unless the user asks.\n 3. **Branch for everything**: No direct commits to `main`. No exceptions. Even one-line fixes.\n 4. **Conventional commits**: All commits use `type(scope): description` format.\n-5. **Co-Authored-By required**: All agent commits must include Co-Authored-By trailer.\n-6. **Link commits to issues**: Include `fixes #PI-XXX` or `closes #PI-XXX` in commit messages.\n-7. **No orphan commits**: Every commit must trace to a Linear issue.\n-8. **Kill after In Review**: Sub-agents are terminated after finalization. Never kept alive.\n+5. **Co-Authored-By required for wrapper-spawned agents**: Wrapper-spawned agent commits must include a Co-Authored-By trailer.\n+6. **Link commits to issues when applicable**: Include issue-closing keywords only when the task should close that issue.\n+7. **No orphan commits**: Every commit must trace to the active issue, user request, or PR context.\n+8. **Kill after In Review in Linear-backed mode**: Sub-agents are terminated after finalization. Never kept alive.\n 9. **No solo scoping**: Always check scope with Gautam before executing.\n-10. **Spec gates execution**: Nothing moves to In Progress without a plan/spec.\n+10. **Spec gates execution**: In tracker-backed workflows, nothing moves to In Progress without a plan/spec.\n \n ### Git Safety (Parallel Agents)\n \n@@ -266,8 +269,8 @@ Multiple agents may work simultaneously. **NEVER**:\n - **Tools**: read, subagent delegation only. NO write, edit, or bash.\n - **Never auto-execute**: Plans must be reviewed by Gautam before execution.\n - **iMessage = synchronous**: Always acknowledge immediately before starting work.\n-- **Linear = async**: Process Linear queue when capacity allows.\n-- **One topic at a time**: Focus on single issue before moving to next.\n+- **Tracker queue = async**: Process the active tracker queue when capacity allows.\n+- **One topic at a time**: Focus on a single task before moving to the next.\n \n ### Sub-Agent Constraints\n \n@@ -283,18 +286,18 @@ Multiple agents may work simultaneously. **NEVER**:\n 1. **First gate**: `reviewer` agent (fast, cheap, learns patterns)\n 2. **Second gate**: 4-agent PR review (Gemini, Codex, Claude, Copilot) on PRs to `main`\n 3. **Branch protection**: `main` requires all 4 approvals\n-4. **Parallel review**: Independent sub-issues reviewed in parallel, connected ones batched\n+4. **Parallel review**: Independent subtasks reviewed in parallel, connected ones batched\n \n ### Communication\n \n - **iMessage**: Synchronous, always respond immediately. Gautam's live line to Pi.\n-- **Linear comments**: Automated, technical, concise. No emojis.\n-- **Linear activities**: Real-time progress streaming via AgentActivity API.\n+- **Tracker comments**: Automated, technical, concise. No emojis.\n+- **Linear activities**: Real-time progress streaming via AgentActivity API in Linear-backed mode.\n - **Git notes**: Full session logs attached to commits for audit trail.\n \n ## Environment Variables\n \n-All environment variables used by the orchestration system:\n+Environment variables used by the Linear-backed orchestration system:\n \n ```bash\n # Required - Linear API Access\n\nFile: heartbeat-test.md (modified, +4/-4)\n@@ -2,13 +2,13 @@\n \n ## Overview\n \n-The agent heartbeat system tracks and monitors worker agent activity during task execution through automatic activity streaming to Linear.\n+The agent heartbeat system tracks and monitors worker agent activity during task execution. Activity streams to the active task surface: a Linear issue when the Linear-backed wrapper is enabled, or the originating thread, issue, or PR otherwise.\n \n ## How It Works\n \n 1. **Session Initialization**: Each worker agent is assigned a unique `AGENT_SESSION_ID` when spawned to handle a delegated task.\n \n-2. **Automatic Streaming**: The agent wrapper automatically streams three types of activity to Linear:\n+2. **Automatic Streaming**: The agent wrapper automatically streams three types of activity to the active task surface:\n    - Tool executions (bash commands, file reads, edits, etc.)\n    - Agent thoughts and reasoning\n    - Task completion status\n@@ -24,8 +24,8 @@ The agent heartbeat system tracks and monitors worker agent activity during task\n ## Environment\n \n - `AGENT_SESSION_ID`: Unique identifier for the agent session\n-- `AGENT_ISSUE_ID`: Linear issue being worked on\n+- `AGENT_ISSUE_ID`: Active GitHub issue or tracker-backed issue being worked on, when present\n - `AGENT_BRANCH`: Git branch for commits\n-- `LINEAR_APP_TOKEN`: Used by wrapper for activity posting\n+- `LINEAR_APP_TOKEN`: Used by the Linear-backed wrapper for activity posting, when enabled\n \n The heartbeat mechanism ensures that parallel agents can work autonomously while maintaining full observability for orchestration and debugging.\n\nFile: packages/coding-agent/examples/extensions/subagent/agents/worker.md (modified, +6/-6)\n@@ -11,15 +11,15 @@ You are a worker agent operating in an isolated context to complete delegated ta\n \n You are running under the agent wrapper with these environment variables available:\n \n-- `AGENT_SESSION_ID` - Your Linear AgentSession ID (for reference only; wrapper handles activity streaming)\n-- `AGENT_ISSUE_ID` - The Linear issue ID you are working on\n+- `AGENT_SESSION_ID` - Your agent session ID (for reference only; wrapper handles activity streaming)\n+- `AGENT_ISSUE_ID` - The active GitHub issue or tracker-backed issue ID you are working on, when present\n - `AGENT_BRANCH` - The git branch you should commit to\n-- `LINEAR_API_KEY` - Linear API key for reading data (if needed)\n-- `LINEAR_APP_TOKEN` - Linear app token (wrapper uses this for activity posting)\n+- `LINEAR_API_KEY` - Linear API key for reading data, when the Linear-backed wrapper is enabled\n+- `LINEAR_APP_TOKEN` - Linear app token, when the Linear-backed wrapper is enabled\n \n-Linear API endpoint: `https://api.linear.app/graphql`\n+Linear API endpoint, when enabled: `https://api.linear.app/graphql`\n \n-**Note:** The wrapper automatically streams your tool executions, thoughts, and completion to Linear. You do not need to manually post activities.\n+**Note:** The wrapper automatically streams your tool executions, thoughts, and completion to the active task surface. You do not need to manually post activities.\n \n # Git Commit Requirements\n \n```\n\n-"
        }
      ]
    },
    {
      "role": "user",
      "parts": [
        {
          "text": "You are a dedicated code reviewer for this repository. You are deeply familiar with its conventions and codebase.\n\n## Project Conventions (from CLAUDE.md)\n## gstack (REQUIRED — global install)\n\n**Before doing ANY work, verify gstack is installed:**\n\n```bash\ntest -d ~/.claude/skills/gstack/bin && echo \"GSTACK_OK\" || echo \"GSTACK_MISSING\"\n```\n\nIf GSTACK_MISSING: STOP. Do not proceed. Tell the user:\n\n> gstack is required for all AI-assisted work in this repo.\n> Install it:\n> ```bash\n> git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack\n> cd ~/.claude/skills/gstack && ./setup --team\n> ```\n> Then restart your AI coding tool.\n\nDo not skip skills, ignore gstack errors, or work around missing gstack.\n\nUsing gstack skills: After install, skills like /qa, /ship, /review, /investigate,\nand /browse are available. Use /browse for all web browsing.\nUse ~/.claude/skills/gstack/... for gstack file paths (the global path).\n\n\n## Review Task\n\nPR #32: \"docs(orchestration): scope Pi tracker requirements\"\n\nDescription:\n## Summary\n\n- Scope remaining Pi operational docs so Linear is an optional tracker adapter, not a default requirement.\n- Update `.pi/RULES.md`, `.pi/AGENT.md`, `heartbeat-test.md`, and the subagent worker example to refer to the active tracker or direct user/GitHub context.\n- Remove the phantom `AGENT_TASK_ID` docs contract; the wrapper defines `AGENT_ISSUE_ID`, `AGENT_SESSION_ID`, and `AGENT_BRANCH`.\n- Leave `docs/AGENTS.md` and `docs/adapters/linear.md` to PR #30 so this PR stays non-overlapping.\n\n## Validation\n\n- `git diff --check -- .pi/RULES.md .pi/AGENT.md heartbeat-test.md packages/coding-agent/examples/extensions/subagent/agents/worker.md`\n- `rg -n 'AGENT_TASK_ID' heartbeat-test.md packages/coding-agent/examples/extensions/subagent/agents/worker.md .pi/AGENT.md .pi/RULES.md || true`\n- `npm run check`\n\n## Notes\n\n- Stacked on #29 because current `main` has stale generated model fixture IDs that fail `npm run check`; #29 owns that unrelated test-fixture repair.\n- PR #30 owns the main orchestration guide and optional Linear adapter reference.\n- PR #31 is already merged.\n\n\nReview the diff below. Provide your response as a JSON object with these keys:\n- \"summary\": a concise markdown summary. Tag issues with severity: [blocking] for must-fix, [suggestion] for improvements, [nitpick] for style.\n- \"comments\": array of { \"path\", \"line\", \"body\" } — inline review comments with severity tags\n- \"verdict\": \"approve\" (no blocking issues) or \"request_changes\" (blocking issues found)\n- \"workflow_suggestions\": array of strings — suggestions for improving the development workflow (e.g., \"Consider splitting this PR\", \"Add a pre-commit hook for X\")\n\nFocus on meaningful issues: bugs, security, performance, correctness. Skip trivial style nits.\nReturn ONLY valid JSON, no markdown fences.\n\nDiff:\n```diff\nFile: .pi/AGENT.md (modified, +7/-7)\n@@ -4,7 +4,7 @@\n \n ## What This Is\n \n-Pi is an orchestrator agent running on Gautam's iMac. It plans projects, delegates execution to sub-agents, communicates with Gautam via iMessage, and tracks everything in Linear. Pi has full tool access for operational needs (diagnostics, config edits, service restarts) but its primary role is orchestration — planning, scoping, and delegating execution work to sub-agents.\n+Pi is an orchestrator agent running on Gautam's iMac. It plans projects, delegates execution to sub-agents, communicates with Gautam via iMessage, and tracks work in the active task surface: a direct user thread, GitHub issue, PR, or optional tracker such as Linear. Pi has full tool access for operational needs (diagnostics, config edits, service restarts) but its primary role is orchestration — planning, scoping, and delegating execution work to sub-agents.\n \n ## Architecture\n \n@@ -27,7 +27,7 @@ SendBlue Cloud ──webhook──▶ Tailscale Funnel :8443\n                          Pi Session (this agent)\n                             ├── Plans & scopes work\n                             ├── Delegates to sub-agents\n-                            ├── Syncs state to Linear\n+                            ├── Syncs state to the active task surface\n                             └── Reports back to Gautam via imessage_reply\n ```\n \n@@ -66,7 +66,7 @@ SendBlue Cloud ──webhook──▶ Tailscale Funnel :8443\n | System | Access | Purpose |\n |--------|--------|---------|\n | GitHub | gh CLI as gbharg | Code, branches, PRs |\n-| Linear | API key + webhook | Project tracking (PI team) |\n+| Linear | API key + webhook | Optional project tracking (PI team) |\n | SendBlue | API + webhook | iMessage send/receive (+16292925296) |\n | Tailscale | Funnel on :8443 | Public webhook endpoint |\n \n@@ -95,12 +95,12 @@ Sub-agents are spawned with `--no-extensions` (no memory, no hooks) but sessions\n ## How It All Connects\n \n 1. Gautam texts Pi via iMessage → SendBlue webhook → Pi extension → appears in session\n-2. Pi plans work, creates specs, creates Linear issues\n+2. Pi plans work and creates specs; it creates tracker issues only when that workflow is active\n 3. Pi spawns sub-agents with full CONTEXT/TASK/SCOPE/CONSTRAINTS/EXPECTED OUTPUT\n 4. Sub-agents return structured output; Pi reviews and synthesizes\n-5. Pi updates Linear, commits to GitHub, texts Gautam with results\n-6. Linear webhooks notify Pi of external changes (Gautam updates issues, other agents comment)\n-7. EOD cron verifies everything is synced and nothing was dropped\n+5. Pi updates the originating task surface, commits to GitHub, texts Gautam with results\n+6. Tracker webhooks notify Pi of external changes when a tracker is configured\n+7. EOD cron verifies active commitments are synced and nothing was dropped\n \n ## Infrastructure references\n \n\nFile: .pi/RULES.md (modified, +8/-4)\n@@ -3,6 +3,9 @@\n This file is the single source of truth for how all agents operate in this repository. Read it in full before every session. Follow it without exception.\n \n Adapted from OpenClaw post-mortem (PI-13, AI-627). Every rule exists because violating it has caused real failures.\n+Linear references below apply only when the active workflow is Linear-backed.\n+Direct user requests and GitHub issue work do not require Linear.\n+The active task surface is whichever system originated the work: a direct user thread, GitHub issue, PR, or optional tracker such as Linear.\n \n ---\n \n@@ -20,10 +23,11 @@ Adapted from OpenClaw post-mortem (PI-13, AI-627). Every rule exists because vio\n ## Git Discipline\n \n 1. **Always branch. No exceptions.** Even one-line fixes. Branch off main, PR to merge.\n-2. **No project branches.** Linear projects are grouping only. Every change goes to main independently.\n+2. **No project branches.** Tracker projects are grouping only. Every change goes to main independently.\n 3. **Conventional branch naming.** Format: `type/description` (feat/, fix/, chore/, docs/, etc.)\n-4. **Conventional commits.** Format: `type(scope): description` referencing Linear issue.\n-5. **Every commit links to a Linear issue.** No orphan commits. The commit message is the enforcement.\n+4. **Conventional commits.** Format: `type(scope): description`; reference an issue only when the task is issue-backed.\n+5. **Every commit has traceable context.** Trace to the active issue, user request, or PR.\n+   - Use issue-closing keywords only when the merge should close that issue.\n 6. **Keep branches short-lived.** One focused change per branch, merged within 1-2 sessions.\n 7. **Do not rebase or force-push shared branches.** Merge main into your branch if needed.\n \n@@ -52,7 +56,7 @@ Adapted from OpenClaw post-mortem (PI-13, AI-627). Every rule exists because vio\n \n 1. **Compaction threshold: target 30%, soft 50%, priority 60%.** I own the decision — hooks nudge, don't trigger.\n 2. **Checkpoint before compaction.** Write state.md + context.md before any context loss event.\n-3. **Everything in Linear.** Any commitment goes in Linear immediately. No exceptions.\n+3. **Use the active task surface.** Commitments go in the tracker, GitHub issue, PR, or user-visible thread that originated the work. Linear is optional.\n 4. **Living documentation.** Update docs in real-time during execution, not after.\n \n ---\n\nFile: docs/AGENTS.md (modified, +33/-30)\n@@ -2,7 +2,7 @@\n \n ## Overview\n \n-This repo implements a multi-agent orchestration system built on pi-mono. Pi (the orchestrator) acts as CTO, communicating with Gautam via iMessage and delegating work to specialized sub-agents. Linear serves as the orchestration bus and single source of truth for task state. All work flows through Linear issues, with sub-agents executing tasks in isolated branches and submitting PRs for review. The system enforces strict lifecycle protocols, conventional commit standards, and comprehensive audit trails via git notes.\n+This repo implements a multi-agent orchestration system built on pi-mono. Pi (the orchestrator) acts as CTO, communicating with Gautam via iMessage and delegating work to specialized sub-agents. In the Linear-backed deployment described below, Linear serves as the orchestration bus and source of truth for task state. Direct repository work and other tracker-backed workflows do not require Linear; when no tracker issue is part of the task, use a conventional branch, commit, and GitHub PR without Linear-only lifecycle steps. The system enforces strict lifecycle protocols, conventional commit standards, and comprehensive audit trails via git notes.\n \n ## Architecture\n \n@@ -34,7 +34,7 @@ This repo implements a multi-agent orchestration system built on pi-mono. Pi (th\n                    │\n                    ▼\n                Git Operations\n-               - Branch per issue\n+               - Branch per task\n                - Conventional commits\n                - Co-Authored-By trailers\n                - Git notes for session logs\n@@ -47,18 +47,18 @@ This repo implements a multi-agent orchestration system built on pi-mono. Pi (th\n                - Branch protection on main\n ```\n \n-**Flow**: Gautam → iMessage → Pi → Linear Issue → Sub-Agent → Git Branch → PR → Review → Merge → Done\n+**Linear-backed flow**: Gautam → iMessage → Pi → Linear Issue → Sub-Agent → Git Branch → PR → Review → Merge → Done\n \n-**Key Principle**: Linear is the single source of truth. Pi reads board state via webhooks, spawns agents assigned to Linear issues, agents report progress via AgentActivity API, and Pi never directly edits code.\n+**Key Principle**: Tracker state is authoritative only for the tracker-backed workflow in use. In Linear-backed mode, Pi reads board state via webhooks, spawns agents assigned to Linear issues, agents report progress via AgentActivity API, and Pi never directly edits code.\n \n ## Agent Roles\n \n | Name | Description | Model | Tools | Persistence |\n |------|-------------|-------|-------|-------------|\n-| `worker` | General-purpose implementation | `claude-sonnet-4-5` | read, write, edit, bash | Disposable (killed after In Review) |\n+| `worker` | General-purpose implementation | `claude-sonnet-4-5` | read, write, edit, bash | Disposable (killed after final review in tracker-backed mode) |\n | `worker-full` | Full-capability implementation | `claude-sonnet-4-20250514` | read, write, edit, bash | Disposable |\n | `worker-readonly` | Read-only analysis/audit | `claude-sonnet-4-20250514` | read, grep, find, ls, bash | Disposable |\n-| `researcher` | Topic investigation | `claude-opus-4-6` | read, grep, find, ls, bash | Persistent (Linear app user) |\n+| `researcher` | Topic investigation | `claude-opus-4-6` | read, grep, find, ls, bash | Persistent (tracker app user in Linear-backed mode) |\n | `reviewer` | Code review specialist | `claude-sonnet-4-5` | read, bash | Persistent (learns patterns) |\n | `planner` | Spec/plan creation | `claude-sonnet-4-5` | read | Disposable |\n | `scout` | Fast recon/exploration | `claude-haiku-4-5` | read, bash (compressed context) | Disposable |\n@@ -69,10 +69,10 @@ This repo implements a multi-agent orchestration system built on pi-mono. Pi (th\n \n ## Lifecycle\n \n-Sub-agents follow a strict 5-phase lifecycle enforced by `scripts/agent-wrapper.sh`:\n+When invoked through `scripts/agent-wrapper.sh` in Linear-backed mode, sub-agents follow a strict 5-phase lifecycle:\n \n ### Phase 1: Setup\n-- Create Linear AgentSession on issue\n+- Create Linear AgentSession on the issue\n - Generate branch name from issue title (conventional format)\n - **Sequential mode**: Create branch off `main`\n - **Parallel mode**: Create branch off task branch, add worktree\n@@ -106,21 +106,22 @@ Sub-agents follow a strict 5-phase lifecycle enforced by `scripts/agent-wrapper.\n - **Sequential mode**: No teardown needed\n - **Parallel mode**: Remove worktree, leave branches for orchestrator\n \n-**Critical**: Agents are killed after Phase 4. Session state persists in git notes and Linear. New agent spawns reconstruct context from external state.\n+**Critical**: Agents are killed after Phase 4. Linear-backed session state persists in git notes and Linear. New agent spawns reconstruct context from external state.\n \n ## Git Model\n \n ### Branch Naming (conventional-branch.github.io)\n - **Sequential**: `feat/PI-XXX-description` (branch off `main`)\n - **Parallel**: `feat/PI-XXX/agent-<role>` (branch off task branch `feat/PI-XXX-description`)\n - Examples: `feat/pi-56-completion-protocol`, `feat/pi-65/agent-worker`, `fix/pi-72-linear-cleanup`\n+- **Direct/no-tracker work**: use the same conventional branch style without a tracker ID, for example `docs/optional-tracker-workflow`\n \n ### Commit Conventions\n Format: `type(scope): description`\n \n **Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `build`, `ci`\n \n-**Required trailer**: `Co-Authored-By: agent/<role> <session-id@noreply>`\n+**Required for wrapper-spawned agent commits**: `Co-Authored-By: agent/<role> <session-id@noreply>`\n \n Example:\n ```\n@@ -147,9 +148,9 @@ Co-Authored-By: agent/worker-full 550e8400-e29b-41d4-a716-446655440000@noreply\n 5. Pi creates final PR: `feat/PI-XXX-description` → `main`\n 6. Review gates apply to final PR\n \n-**Always**: Every commit links to Linear issue via `fixes #PI-XXX` in commit message.\n+**Linear-backed mode**: commits created for a Linear issue link to that issue via `fixes #PI-XXX` or `closes #PI-XXX` in the commit message. Direct/no-tracker commits omit Linear references.\n \n-## Linear Integration\n+## Linear-backed Integration\n \n ### State Machine\n \n@@ -208,16 +209,18 @@ Backlog → Todo → Plan → In Progress → In Review → Done\n \n ## Dependencies\n \n-### Required Tools\n-- `gh` (GitHub CLI) - PR creation, issue management\n-- `jq` - JSON parsing for Linear API responses\n-- `curl` - Linear API calls\n+### Base Tools\n+- `gh` (GitHub CLI) - PR creation and issue management when a GitHub issue is involved\n - `tsx` - TypeScript execution for Pi CLI\n - `git` - Version control (with `git notes` support)\n - `node` (v18+) - Node.js runtime\n - `npm` - Package manager\n \n-### Required Environment Variables\n+### Linear-backed Tools\n+- `jq` - JSON parsing for Linear API responses\n+- `curl` - Linear API calls\n+\n+### Linear-backed Environment Variables\n | Variable | Description | Used By |\n |----------|-------------|---------|\n | `LINEAR_API_KEY` | User API key for Pi board queries | Pi, wrapper setup |\n@@ -235,16 +238,16 @@ Backlog → Todo → Plan → In Progress → In Review → Done\n \n ### Hard Rules (All Agents)\n \n-1. **Single source of truth**: Linear is authoritative for task state. Never use custom IDs.\n-2. **Everything is an issue**: All work that results in action must have a Linear issue.\n+1. **Single source of truth**: Use the active tracker or user-provided task as authoritative. Do not invent custom IDs.\n+2. **Issue-backed when provided**: If the task starts from a GitHub or Linear issue, preserve that issue link. If no issue is provided, do not create one unless the user asks.\n 3. **Branch for everything**: No direct commits to `main`. No exceptions. Even one-line fixes.\n 4. **Conventional commits**: All commits use `type(scope): description` format.\n-5. **Co-Authored-By required**: All agent commits must include Co-Authored-By trailer.\n-6. **Link commits to issues**: Include `fixes #PI-XXX` or `closes #PI-XXX` in commit messages.\n-7. **No orphan commits**: Every commit must trace to a Linear issue.\n-8. **Kill after In Review**: Sub-agents are terminated after finalization. Never kept alive.\n+5. **Co-Authored-By required for wrapper-spawned agents**: Wrapper-spawned agent commits must include a Co-Authored-By trailer.\n+6. **Link commits to issues when applicable**: Include issue-closing keywords only when the task should close that issue.\n+7. **No orphan commits**: Every commit must trace to the active issue, user request, or PR context.\n+8. **Kill after In Review in Linear-backed mode**: Sub-agents are terminated after finalization. Never kept alive.\n 9. **No solo scoping**: Always check scope with Gautam before executing.\n-10. **Spec gates execution**: Nothing moves to In Progress without a plan/spec.\n+10. **Spec gates execution**: In tracker-backed workflows, nothing moves to In Progress without a plan/spec.\n \n ### Git Safety (Parallel Agents)\n \n@@ -266,8 +269,8 @@ Multiple agents may work simultaneously. **NEVER**:\n - **Tools**: read, subagent delegation only. NO write, edit, or bash.\n - **Never auto-execute**: Plans must be reviewed by Gautam before execution.\n - **iMessage = synchronous**: Always acknowledge immediately before starting work.\n-- **Linear = async**: Process Linear queue when capacity allows.\n-- **One topic at a time**: Focus on single issue before moving to next.\n+- **Tracker queue = async**: Process the active tracker queue when capacity allows.\n+- **One topic at a time**: Focus on a single task before moving to the next.\n \n ### Sub-Agent Constraints\n \n@@ -283,18 +286,18 @@ Multiple agents may work simultaneously. **NEVER**:\n 1. **First gate**: `reviewer` agent (fast, cheap, learns patterns)\n 2. **Second gate**: 4-agent PR review (Gemini, Codex, Claude, Copilot) on PRs to `main`\n 3. **Branch protection**: `main` requires all 4 approvals\n-4. **Parallel review**: Independent sub-issues reviewed in parallel, connected ones batched\n+4. **Parallel review**: Independent subtasks reviewed in parallel, connected ones batched\n \n ### Communication\n \n - **iMessage**: Synchronous, always respond immediately. Gautam's live line to Pi.\n-- **Linear comments**: Automated, technical, concise. No emojis.\n-- **Linear activities**: Real-time progress streaming via AgentActivity API.\n+- **Tracker comments**: Automated, technical, concise. No emojis.\n+- **Linear activities**: Real-time progress streaming via AgentActivity API in Linear-backed mode.\n - **Git notes**: Full session logs attached to commits for audit trail.\n \n ## Environment Variables\n \n-All environment variables used by the orchestration system:\n+Environment variables used by the Linear-backed orchestration system:\n \n ```bash\n # Required - Linear API Access\n\nFile: heartbeat-test.md (modified, +4/-4)\n@@ -2,13 +2,13 @@\n \n ## Overview\n \n-The agent heartbeat system tracks and monitors worker agent activity during task execution through automatic activity streaming to Linear.\n+The agent heartbeat system tracks and monitors worker agent activity during task execution. Activity streams to the active task surface: a Linear issue when the Linear-backed wrapper is enabled, or the originating thread, issue, or PR otherwise.\n \n ## How It Works\n \n 1. **Session Initialization**: Each worker agent is assigned a unique `AGENT_SESSION_ID` when spawned to handle a delegated task.\n \n-2. **Automatic Streaming**: The agent wrapper automatically streams three types of activity to Linear:\n+2. **Automatic Streaming**: The agent wrapper automatically streams three types of activity to the active task surface:\n    - Tool executions (bash commands, file reads, edits, etc.)\n    - Agent thoughts and reasoning\n    - Task completion status\n@@ -24,8 +24,8 @@ The agent heartbeat system tracks and monitors worker agent activity during task\n ## Environment\n \n - `AGENT_SESSION_ID`: Unique identifier for the agent session\n-- `AGENT_ISSUE_ID`: Linear issue being worked on\n+- `AGENT_ISSUE_ID`: Active GitHub issue or tracker-backed issue being worked on, when present\n - `AGENT_BRANCH`: Git branch for commits\n-- `LINEAR_APP_TOKEN`: Used by wrapper for activity posting\n+- `LINEAR_APP_TOKEN`: Used by the Linear-backed wrapper for activity posting, when enabled\n \n The heartbeat mechanism ensures that parallel agents can work autonomously while maintaining full observability for orchestration and debugging.\n\nFile: packages/coding-agent/examples/extensions/subagent/agents/worker.md (modified, +6/-6)\n@@ -11,15 +11,15 @@ You are a worker agent operating in an isolated context to complete delegated ta\n \n You are running under the agent wrapper with these environment variables available:\n \n-- `AGENT_SESSION_ID` - Your Linear AgentSession ID (for reference only; wrapper handles activity streaming)\n-- `AGENT_ISSUE_ID` - The Linear issue ID you are working on\n+- `AGENT_SESSION_ID` - Your agent session ID (for reference only; wrapper handles activity streaming)\n+- `AGENT_ISSUE_ID` - The active GitHub issue or tracker-backed issue ID you are working on, when present\n - `AGENT_BRANCH` - The git branch you should commit to\n-- `LINEAR_API_KEY` - Linear API key for reading data (if needed)\n-- `LINEAR_APP_TOKEN` - Linear app token (wrapper uses this for activity posting)\n+- `LINEAR_API_KEY` - Linear API key for reading data, when the Linear-backed wrapper is enabled\n+- `LINEAR_APP_TOKEN` - Linear app token, when the Linear-backed wrapper is enabled\n \n-Linear API endpoint: `https://api.linear.app/graphql`\n+Linear API endpoint, when enabled: `https://api.linear.app/graphql`\n \n-**Note:** The wrapper automatically streams your tool executions, thoughts, and completion to Linear. You do not need to manually post activities.\n+**Note:** The wrapper automatically streams your tool executions, thoughts, and completion to the active task surface. You do not need to manually post activities.\n \n # Git Commit Requirements\n \n```\n\n-"
        }
      ]
    }
  ]
}