feat: implement multi-step orchestrator pipeline

- Overhaul orchestrator.js to manage a multi-step PR state machine (DEV -> REVIEW -> HUMAN_REVIEW -> MERGE).
- Integrate native GitHub PR UI human review approval gates.
- Support auto-merge label to bypass human review.
- Refactor opencode-post-step.js to correctly propagate agent refusal/triage states and override existing PR labels.
- Update orchestrator.yml triggers for pull_request_review events and configure required PR write permissions.
- Document the new phase transitions and state object schemas in AGENTS.md.
- Expand jnode-issue-resolver skill taxonomy and protocols to support PR feedback loops natively.
- Introduce unit test coverage for orchestrator and post-step scripts using Node's native test runner.

Author: LSantha

.github/AGENTS.md

@@ -37,18 +37,23 @@ CI infrastructure, agent automation, and label conventions for JNode.
                   +--------------------+   /oc "Please proceed"   +-------------------------+
    /orchestrate->| orchestrator (js)  |------------------------->| next child task in queue |
                   +--------------------+                          +-------------------------+
+                            ^   |
+         pull_request_review|   | /oc review | /oc fix
+                            |   v
+                  +--------------------+
+                  |    PR feedback     |
+                  +--------------------+
 ```
 
 - **opencode** is the worker. It runs the agent once per trigger, posts a result, and exits.
-- **orchestrator** is the foreman. It holds a JSON state in the master issue body, picks the next child task from the queue, and triggers it by posting `/oc Please proceed with this task.` on the child issue.
-- `orchestrator.yml` listens for `workflow_run` from `opencode`. When a child finishes, the orchestrator advances the queue and triggers the next child via a comment (which loops back into opencode).
-- The trigger is one-way: orchestrator triggers opencode by comment; opencode does NOT call orchestrator.
+- **orchestrator** is the foreman. It holds a JSON state in the master issue body, picks the next child task from the queue, and tracks its phase (DEV, REVIEW, HUMAN_REVIEW, FEEDBACK, MERGE).
+- `orchestrator.yml` listens for `workflow_run` from `opencode` and `pull_request_review`. It advances the phase, loops back via `/oc fix` or `/oc review`, or merges the PR.
 
-A child task is "complete" in the orchestrator's eyes when EITHER:
+For single-step tasks, a child task is "complete" in the orchestrator's eyes when EITHER:
 - the child issue is closed on GitHub, OR
 - the child has one of: `agent/done`, `agent/investigated`, `agent/skip`, `agent/blocked`, `agent/needs-info`.
 
-The `agent/failed` label does NOT count as completion; it triggers a retry (max 3 attempts).
+For multi-step PR tasks, completion requires reaching the `MERGE` phase (or short-circuiting on skip labels).
 
 ## Orchestrator State Machine
 
@@ -57,7 +62,7 @@ State lives in the master issue body as a hidden HTML comment:
 ```html
 <!-- ORCHESTRATOR_STATE:
 { "status": "IDLE|IN_PROGRESS|COMPLETED",
-  "current_task": 487,
+  "current_task": { "issue": 487, "pr": null, "phase": "DEV", "turn": 0, "max_turns": 3, "retries": 0 },
   "queue": [488, 489],
   "completed": [485, 486],
   "failed": [],
@@ -70,14 +75,22 @@ State lives in the master issue body as a hidden HTML comment:
 | Field | Meaning |
 |-------|---------|
 | `status` | IDLE (initial) / IN_PROGRESS (after first trigger) / COMPLETED (queue empty) |
-| `current_task` | Task the agent is working on; `null` when idle |
+| `current_task` | Object representing task state, or task number (for older one-shot tasks) |
 | `queue` | Pending task numbers, in execution order |
-| `completed` | Tasks that finished with a completion label or were closed |
-| `failed` | Tasks that hit 3 retries without success |
+| `completed` | Tasks that finished completely (merged, or short-circuited) |
+| `failed` | Tasks that hit 3 retries without success, or max_turns |
 | `retries` | Attempt counter for `current_task`; resets on advance |
 | `history` | Append-only event log with ISO timestamps |
 | `order` | Original task order from the markdown checklist; rendered top-to-bottom in the status table |
 
+### Phases
+
+- **DEV**: Initial agent run. Agent creates a PR. Transition to `REVIEW`.
+- **REVIEW**: Agent reviews the PR. If approved and no `auto-merge` label, transition to `HUMAN_REVIEW`. If `auto-merge`, transition to `MERGE`. If changes requested, transition to `FEEDBACK`.
+- **FEEDBACK**: Agent addresses review comments. Transition to `REVIEW`.
+- **HUMAN_REVIEW**: Orchestrator waits for native GitHub PR review from a human maintainer. Approval → `MERGE`, Request changes → `FEEDBACK`.
+- **MERGE**: Orchestrator squashes the PR and deletes the branch inline.
+
 Initialization: on first run, the orchestrator parses the master issue's markdown checklist (`- [ ] #N`, `- [x] #N`, `- [FAIL] #N`) and builds initial state. Subsequent runs load from the hidden JSON block. If `state.order` is empty (older master), it is backfilled from status-grouped arrays.
 
 Self-healing guard: if the orchestrator wakes up and the `current_task` is already complete (closed or has completion label), it advances immediately and exits. This handles the case where the agent finished but the orchestrator was locked out.
@@ -160,3 +173,11 @@ node .github/scripts/sync-labels.js
 ```
 
 The `opencode-post-step.js` and `orchestrator.js` modules export a single async function taking `{ github, context, core }`. They are normally invoked from `actions/github-script@v7` and not run standalone.
+
+### Running tests
+
+Unit tests for the `.github/scripts/` logic use the native `node:test` framework (requires Node.js v18+). They do not require any external dependencies.
+
+```bash
+node --test .github/scripts/tests/
+```

.github/scripts/opencode-post-step.js

@@ -56,21 +56,21 @@ function decideAgentLabel({ existing, conclusion, latestComment, labels, isPR })
   if (conclusion === 'failure' || conclusion === 'cancelled') {
     return { label: 'agent/failed', reason: 'run concluded: ' + conclusion };
   }
-  if (existing && existing !== 'agent/failed') {
-    return { label: existing, reason: 'existing agent/* label respected' };
-  }
   if (isRefusalComment(latestComment)) {
     return { label: 'agent/skip', reason: 'refusal detected in comment' };
   }
   if (isNeedsInfoComment(latestComment)) {
     return { label: 'agent/needs-info', reason: 'needs-info detected in comment' };
   }
-  if (isPR) {
-    return { label: 'agent/done', reason: 'PR context' };
-  }
   if (isInvestigationReport(latestComment)) {
     return { label: 'agent/investigated', reason: 'investigation report heading detected (verb-override)' };
   }
+  if (existing && existing !== 'agent/failed') {
+    return { label: existing, reason: 'existing agent/* label respected' };
+  }
+  if (isPR) {
+    return { label: 'agent/done', reason: 'PR context' };
+  }
   if (isInvestigationKind(labels)) {
     return { label: 'agent/investigated', reason: 'investigation kind, comment absent' };
   }
@@ -127,6 +127,17 @@ module.exports = async ({ github, context, core }) => {
   });
   core.info('Decision: ' + decision.label + ' (' + decision.reason + ')');
 
+  if (existingAgent && existingAgent !== decision.label) {
+    try {
+      await github.rest.issues.removeLabel({
+        owner, repo, issue_number: number, name: existingAgent,
+      });
+      core.info('Removed old label: ' + existingAgent);
+    } catch (err) {
+      core.warning('Failed to remove old label: ' + err.message);
+    }
+  }
+
   try {
     await github.rest.issues.addLabels({
       owner, repo, issue_number: number, labels: [decision.label],