@julioborges/gantry 1.0.6 → 1.1.0

package/.agents/skills/gantry/reference/plan-workflow.md

@@ -57,6 +57,19 @@ python3 "$skillDir/scripts/roadmap.py" check
 The last command must exit 0 before the Run recomputes the frontier. Planning approval does not permit
 silent issue additions, splits, merges or dependency changes.
 
+## Codex Host Orchestration and Hybrid Dispatch
+
+When Codex CLI operates as the Host Harness:
+1. **Instruction Ingestion**: Codex reads repository policy and instructions from `AGENTS.md` (configured by `gantry-setup`), respecting all Gantry invariants (no direct commits to `main`, no manual edits to `ROADMAP.md` or Issue statuses).
+2. **Phase Orchestration**: The host drives the planning sequence:
+   - Structural validation (`spec.py --check`)
+   - Requirement Critic invocation via bounded subprocess dispatch
+   - Parallel research and vertical-slice drafting
+   - Plan Critic adversarial refutation
+   - Halting for mandatory operator approval before transitioning issues (`roadmap.py status <ref> ready-for-agent`, `roadmap.py waves`, `roadmap.py check`)
+3. **Bounded Subprocess Execution**: Roles are dispatched via `python3 "$skillDir/scripts/execution.py" dispatch --role <role> --cwd <dir>`. If a role uses Codex, it executes bounded `codex exec "<prompt>" --model <model>`. If a role is delegated to an external harness (such as Claude Code or Antigravity), cross-harness dispatch is invoked.
+4. **Contract Verification**: Every role result is parsed through `result.extract_json()` and validated against its schema contract (`result.py`). Delimiters and markdown code fences (` ```json `) are handled robustly, and protocol failures trigger bounded retries.
+
 ## Executable Claude Code Workflow
 
 The following is the executable Workflow script. Other harnesses execute the same prompt functions and

package/.agents/skills/gantry/reference/round-workflow.md

@@ -137,6 +137,41 @@ continuation) can pick it up. "Blocked" here names a Run-log fact about this att
 projection — status authority stays in Issue files, per this Issue's contract, and only `roadmap.py done`
 (after Critic acceptance) ever changes an Issue's `Status:` line.
 
+## Dashboard lifecycle hooks
+
+Before the `Implement` phase begins in any round, the workflow queries `dashboard.py status --json`:
+- If inactive, it prompts the operator asking whether to start the dashboard (`dashboard.py start --daemon`). If approved, it launches the daemon and displays the URL; if declined, it proceeds without prompting again.
+- If already active, it logs the active URL without prompting.
+
+Immediately after the `Integrate` step completes at the end of each round:
+- The workflow queries `dashboard.py status --json`. If active, it prompts the operator asking whether to terminate the dashboard (`dashboard.py stop`). If approved, it terminates the server daemon.
+
+## Codex Host Orchestration and Hybrid Dispatch
+
+When Codex CLI serves as the Host Harness:
+1. **Instruction Ingestion**: Codex reads repository policy and guidance from the marked Gantry section of `AGENTS.md`, adhering to immutable workflow invariants:
+   - Feature branches only (`feat/*`, `fix/*`, `docs/*`); never commit directly to `main`.
+   - Never manually edit `ROADMAP.md`, issue statuses, or criteria checkboxes; only `roadmap.py done` updates them upon verified Critic acceptance.
+2. **Lifecycle and Round Orchestration**:
+   - The host queries dashboard status before implementation (`dashboard.py status --json`) and offers daemon activation.
+   - For each issue in the frontier round, Codex isolates work in a dedicated worktree and branch (`common.issue_branch()`).
+   - Telemetry is recorded via `runlog.py` CLI events (`run.started`, `round.started`, `phase.started`, `phase.finished`, `subagent.started`, `subagent.stopped`, `issue.done`, `round.finished`).
+3. **Bounded Role Invocations**:
+   - Roles are invoked through bounded CLI processes via `execution.py dispatch --role <role> --cwd <worktree>`.
+   - When configured for Codex, role execution invokes `codex exec "<prompt>" --model <model> [--effort <effort>]`.
+   - When configured for cross-harness execution (e.g. an adversarial Critic powered by Claude Code or Antigravity), bounded dispatch invokes the respective CLI (`claude -p`, `agy --print`).
+   - Execution runners enforce process timeouts, error isolation, and model fallback detection.
+4. **Result Contract Enforcement**:
+   - All role outputs (Implementer, Reviewer, Critic, Learner) must conform to schemas bundled in `schemas/<role>.json`.
+   - Parsers robustly extract JSON payloads from markdown fences (` ```json `, ` ``` `, ` ````json `) and handle conversational commentary.
+   - Any schema mismatch triggers a Protocol Failure and bounded retry.
+5. **Defense in Depth**:
+   - Because Codex CLI does not expose native pre-tool hooks, guardrails are enforced through layered defense:
+     - Clear prompt invariants injected into `AGENTS.md`.
+     - Git hooks (`pre-commit`, `pre-push`) configured in `.git/hooks` enforcing fast-forward updates and preventing test-skips.
+     - Independent adversarial Critic running differential gates (`gates.py`) and acceptance verification (`acceptance.py`), refuting unverified claims or prompt violations.
+   - Branches integrate serially only after Critic acceptance and clean gate runs.
+
 ## Executable Claude Code Workflow
 
 This Workflow script is the executable chain. It creates one Implementer chain per Issue; `pipeline`
@@ -671,6 +706,30 @@ async function implement(issue, feedback, previous) {
   return result && result.worktree === assigned.worktree && result.branch === assigned.branch ? result : null
 }
 
+// Pre-implementation dashboard check
+if (typeof prompt === 'function' && !A.skipDashboardPrompt) {
+  const dashCheck = await runCommand(`python3 "${scripts}/dashboard.py" status --json`, { cwd: A.repoRoot })
+  let dashStatus = null
+  if (dashCheck && dashCheck.exitCode === 0 && dashCheck.stdout && dashCheck.stdout.trim()) {
+    try { dashStatus = JSON.parse(dashCheck.stdout) } catch (e) {}
+  }
+  if (dashStatus && dashStatus.running) {
+    log(`Dashboard active at ${dashStatus.url}`)
+  } else if (dashStatus && !dashStatus.running) {
+    const askStart = await prompt('The dashboard is currently inactive. Would you like to start it in the background (dashboard.py start --daemon)? (yes/no)')
+    if (askStart && askStart.toLowerCase().trim() === 'yes') {
+      const startRes = await runCommand(`python3 "${scripts}/dashboard.py" start --daemon`, { cwd: A.repoRoot })
+      if (startRes && startRes.exitCode === 0) {
+        const recheck = await runCommand(`python3 "${scripts}/dashboard.py" status --json`, { cwd: A.repoRoot })
+        try {
+          const recheckStatus = JSON.parse(recheck.stdout)
+          log(`Dashboard started at ${recheckStatus.url}`)
+        } catch (e) {}
+      }
+    }
+  }
+}
+
 const results = await pipeline(
   A.issues,
   issue => implement(issue, null, null),
@@ -906,11 +965,23 @@ let integrationStopped = false
 let cancelReason = null
 for (const delivery of deliveries) {
   if (delivery.outcome !== 'accepted') continue
+  if (A.unitId && A.runId && A.waitGate) {
+    const stateRootArg = A.stateRoot ? ` --state-root "${A.stateRoot}"` : ''
+    await runWorkflowCommand(`python3 "${scripts}/wait_gate.py" ${delivery.ref} --unit "${A.unitId}" --run "${A.runId}"${stateRootArg}`)
+  }
   if (integrationStopped) {
     delivery.outcome = 'integration_pending'
     continue
   }
-  if (A.isolate) {
+  const strategy = (A.policy && A.policy.delivery && A.policy.delivery.strategy) || 'branch-merge'
+  if (strategy === 'pull-request') {
+    const target = (A.policy && A.policy.git && A.policy.git.target) || 'main'
+    try {
+      await runWorkflowCommand(`gh pr view "${delivery.branch}" --json state -q .state`)
+    } catch {
+      await runWorkflowCommand(`git merge-base --is-ancestor "${delivery.branch}" "${target}"`)
+    }
+  } else if (A.isolate) {
     if (!delivery.branch) {
       delivery.outcome = 'integration_failed'
       integrationStopped = true
@@ -937,13 +1008,30 @@ for (const delivery of deliveries) {
     await runWorkflowCommand(`git add -- ROADMAP.md "${delivery.issuePath}"`)
     await runWorkflowCommand(`git commit -m "gantry: complete ${delivery.ref}"`)
     delivery.outcome = 'done'
-    await appendRunEvent('issue.done', delivery.ref, undefined, { worktree: delivery.worktree })
+    await appendRunEvent('issue.done', delivery.ref, undefined, { worktree: delivery.worktree, strategy })
   } catch {
     delivery.outcome = 'integration_failed'
     integrationStopped = true
     cancelReason = { issue: delivery.ref, reason: 'integration_commit_failed' }
   }
 }
+
+// Post-integration dashboard check
+if (typeof prompt === 'function' && !A.skipDashboardPrompt) {
+  const postDashCmd = await runCommand(`python3 "${scripts}/dashboard.py" status --json`, { cwd: A.repoRoot })
+  let postDashStatus = null
+  if (postDashCmd && postDashCmd.exitCode === 0 && postDashCmd.stdout && postDashCmd.stdout.trim()) {
+    try { postDashStatus = JSON.parse(postDashCmd.stdout) } catch (e) {}
+  }
+  if (postDashStatus && postDashStatus.running) {
+    const askStop = await prompt('Integration complete. Would you like to shut down the background dashboard server (dashboard.py stop)? (yes/no)')
+    if (askStop && askStop.toLowerCase().trim() === 'yes') {
+      await runCommand(`python3 "${scripts}/dashboard.py" stop`, { cwd: A.repoRoot })
+      log('Dashboard stopped.')
+    }
+  }
+}
+
 await appendRunEvent('round.finished', undefined, undefined, { round: A.round })
 if (integrationStopped) {
   await appendRunEvent('run.cancelled', cancelReason && cancelReason.issue, undefined, {

package/.agents/skills/gantry/scripts/common.py

@@ -25,6 +25,9 @@ DEFAULT_POLICY = {
         "prefix": "gantry/",
         "issueBranch": "{prefix}{spec}-{number:02d}",
     },
+    "delivery": {
+        "strategy": "branch-merge",
+    },
     "hooks": {"record": [], "deny": []},
     "budget": {"corrections": 2, "contextShare": 0.15},
     "dashboard": {"staleAfterSeconds": 900},