@kbediako/codex-orchestrator 0.1.33 → 0.1.34

package/README.md

@@ -232,6 +232,19 @@ codex-orchestrator doctor --usage
 ```
 `doctor --usage` prints adoption KPIs (advanced/cloud/rlm/collab/delegation coverage), and per-run `run-summary.json` now includes a `usageKpi` section plus cloud fallback metadata when preflight downgrades to MCP.
 
+Issue bundle logging (downstream dogfooding / repro handoff):
+```bash
+codex-orchestrator doctor --issue-log --issue-title "Observed failure" --issue-notes "what happened"
+```
+`doctor --issue-log` appends `docs/codex-orchestrator-issues.md` (override via `--issue-log-path`) and writes a JSON bundle under `out/<resolved-task>/doctor/issue-bundles/` with doctor/cloud context (latest run context is included when available).
+
+Auto-capture issue bundles when runs fail:
+```bash
+codex-orchestrator start <pipeline> --auto-issue-log
+codex-orchestrator flow --task <task-id> --auto-issue-log
+```
+This captures both post-manifest run failures and setup failures that occur before a run manifest is created (for example strict repo-config enforcement).
+
 Cloud preflight check (without starting a pipeline):
 ```bash
 codex-orchestrator doctor --cloud-preflight
@@ -243,10 +256,13 @@ codex-orchestrator doctor --cloud-preflight
 - Enable required MCP servers with least privilege: `codex-orchestrator mcp enable --servers delegation --yes` (plan with `--format json`; omit `--servers` only when you intentionally want all disabled servers enabled; env/secret values are redacted in displayed command lines)
 - Low-friction docs->implementation guardrails: `codex-orchestrator flow --task <task-id>`
 - Validate + measure adoption locally: `codex-orchestrator doctor --usage --format json`
+- Capture reproducible downstream failures: `codex-orchestrator doctor --issue-log --issue-title "<title>" --issue-notes "<notes>"`
+- Auto-capture failed run issue bundles: `codex-orchestrator start <pipeline> --auto-issue-log` or `codex-orchestrator flow --auto-issue-log`
 - Delegation: `codex-orchestrator doctor --apply --yes`, then enable for a Codex run with: `codex -c 'mcp_servers.delegation.enabled=true' ...`
 - Collab (symbolic RLM subagents): `codex-orchestrator rlm --multi-agent auto "<goal>"` (legacy alias: `--collab auto`; requires Codex `features.multi_agent=true`)
 - Cloud: set `CODEX_CLOUD_ENV_ID` (and optional `CODEX_CLOUD_BRANCH`), then run: `codex-orchestrator start <pipeline> --cloud --target <stage-id>`
 - Cloud fail-fast (avoid fallback reliance): set `CODEX_ORCHESTRATOR_CLOUD_FALLBACK=deny`
+- Repo-config fail-fast (deny packaged config fallback): set `CODEX_ORCHESTRATOR_REPO_CONFIG_REQUIRED=1` or pass `--repo-config-required`
 - Cloud status retry tuning (optional): `CODEX_CLOUD_STATUS_RETRY_LIMIT`, `CODEX_CLOUD_STATUS_RETRY_BACKOFF_MS`
 
 Print DevTools MCP setup guidance:
@@ -256,11 +272,11 @@ codex-orchestrator devtools setup
 
 ## Common commands
 
-- `codex-orchestrator start <pipeline>` — run a pipeline.
-- `codex-orchestrator flow --task <task-id>` — run `docs-review` then `implementation-gate` in sequence.
+- `codex-orchestrator start <pipeline>` — run a pipeline (add `--auto-issue-log` for automatic failure bundle capture; add `--repo-config-required` for strict repo-local config mode).
+- `codex-orchestrator flow --task <task-id>` — run `docs-review` then `implementation-gate` in sequence (supports `--auto-issue-log` and `--repo-config-required`).
 - `codex-orchestrator plan <pipeline>` — preview pipeline stages.
 - `codex-orchestrator exec <cmd>` — run a one-off command with the exec runtime.
-- `codex-orchestrator init codex` — install starter templates (`mcp-client.json`, `AGENTS.md`) into a repo.
+- `codex-orchestrator init codex` — install starter templates (`mcp-client.json`, `AGENTS.md`, `codex.orchestrator.json`) into a repo.
 - `codex-orchestrator setup --yes` — install bundled skills and configure delegation + DevTools wiring (add `--refresh-skills` to overwrite existing skills in `$CODEX_HOME/skills`).
 - `codex-orchestrator init codex --codex-cli --yes --codex-source <path>` — optionally provision a CO-managed Codex CLI binary (build-from-source default; set `CODEX_CLI_SOURCE` to avoid passing `--codex-source` every time, and `CODEX_CLI_USE_MANAGED=1` to route runs to it).
 - `codex-orchestrator init codex --codex-cli --yes --codex-download-url <url> --codex-download-sha256 <sha>` — opt-in to a prebuilt Codex CLI download.

package/codex.orchestrator.json

@@ -0,0 +1,448 @@
+{
+  "stageSets": {
+    "build-lint-test": [
+      {
+        "kind": "command",
+        "id": "build",
+        "title": "npm run build",
+        "command": "npm run build"
+      },
+      {
+        "kind": "command",
+        "id": "lint",
+        "title": "npm run lint",
+        "command": "npm run lint"
+      },
+      {
+        "kind": "command",
+        "id": "test",
+        "title": "npm run test",
+        "command": "npm run test"
+      }
+    ],
+    "delegation-guard-stage": [
+      {
+        "kind": "command",
+        "id": "delegation-guard",
+        "title": "Run delegation guard",
+        "command": "node \"$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/orchestrator/src/cli/utils/delegationGuardRunner.js\""
+      }
+    ],
+    "diagnostics-spec-guard": [
+      {
+        "kind": "command",
+        "id": "spec-guard",
+        "title": "node scripts/spec-guard.mjs --dry-run",
+        "command": "node \"$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/orchestrator/src/cli/utils/specGuardRunner.js\" --dry-run"
+      }
+    ],
+    "docs-review-checks": [
+      {
+        "kind": "command",
+        "id": "docs-check",
+        "title": "npm run docs:check",
+        "command": "npm run docs:check"
+      },
+      {
+        "kind": "command",
+        "id": "docs-freshness",
+        "title": "npm run docs:freshness",
+        "command": "npm run docs:freshness"
+      }
+    ],
+    "design-artifacts": [
+      {
+        "kind": "command",
+        "id": "design-spec-guard",
+        "title": "Validate specs via spec-guard",
+        "command": "node \"$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/orchestrator/src/cli/utils/specGuardRunner.js\" --dry-run",
+        "env": {
+          "DESIGN_PIPELINE": "1"
+        },
+        "summaryHint": "Ensures design specs are fresh before artifact write"
+      },
+      {
+        "kind": "command",
+        "id": "design-artifact-writer",
+        "title": "Persist design artifact manifests",
+        "command": "node \"$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/write-artifacts.js\"",
+        "env": {
+          "DESIGN_PIPELINE": "1"
+        }
+      }
+    ]
+  },
+  "pipelines": [
+    {
+      "id": "diagnostics",
+      "title": "Diagnostics Pipeline",
+      "description": "Build, lint, test, and spec-guard the repository with grouped runner support.",
+      "tags": [
+        "diagnostics-primary",
+        "diagnostics-secondary"
+      ],
+      "stages": [
+        {
+          "kind": "stage-set",
+          "ref": "delegation-guard-stage"
+        },
+        {
+          "kind": "stage-set",
+          "ref": "build-lint-test"
+        },
+        {
+          "kind": "stage-set",
+          "ref": "diagnostics-spec-guard"
+        }
+      ]
+    },
+    {
+      "id": "rlm",
+      "title": "RLM Runner",
+      "description": "Runs the recursive language model loop with validator gating.",
+      "tags": [
+        "rlm"
+      ],
+      "guardrailsRequired": false,
+      "stages": [
+        {
+          "kind": "command",
+          "id": "rlm-runner",
+          "title": "Run RLM loop",
+          "command": "node \"$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/orchestrator/src/cli/rlmRunner.js\"",
+          "summaryHint": "RLM loop completed"
+        }
+      ]
+    },
+    {
+      "id": "implementation-gate",
+      "title": "Implementation Complete Gate",
+      "description": "Runs the required implementation validations (spec-guard, build, lint, test, docs:check, docs:freshness, diff-budget) and launches the Codex review handoff, writing a single manifest for evidence.",
+      "tags": [
+        "implementation-gate"
+      ],
+      "stages": [
+        {
+          "kind": "stage-set",
+          "ref": "delegation-guard-stage"
+        },
+        {
+          "kind": "stage-set",
+          "ref": "diagnostics-spec-guard"
+        },
+        {
+          "kind": "stage-set",
+          "ref": "build-lint-test"
+        },
+        {
+          "kind": "stage-set",
+          "ref": "docs-review-checks"
+        },
+        {
+          "kind": "command",
+          "id": "diff-budget",
+          "title": "node scripts/diff-budget.mjs",
+          "command": "node scripts/diff-budget.mjs"
+        },
+        {
+          "kind": "command",
+          "id": "review",
+          "title": "npm run review",
+          "command": "npm run review",
+          "env": {
+            "DIFF_BUDGET_STAGE": "1",
+            "CODEX_REVIEW_NON_INTERACTIVE": "1",
+            "NOTES": "Goal: implementation gate review handoff | Summary: automated prompt with manifest evidence + scope hints | Risks: review output depends on local Codex CLI capabilities"
+          }
+        }
+      ]
+    },
+    {
+      "id": "docs-review",
+      "title": "Docs Review Gate",
+      "description": "Pre-implementation docs review: spec-guard, docs:check, docs:freshness, and review (diff budget skipped).",
+      "tags": [
+        "docs-review"
+      ],
+      "stages": [
+        {
+          "kind": "stage-set",
+          "ref": "delegation-guard-stage"
+        },
+        {
+          "kind": "stage-set",
+          "ref": "diagnostics-spec-guard"
+        },
+        {
+          "kind": "stage-set",
+          "ref": "docs-review-checks"
+        },
+        {
+          "kind": "command",
+          "id": "review",
+          "title": "npm run review",
+          "command": "npm run review",
+          "env": {
+            "SKIP_DIFF_BUDGET": "1",
+            "CODEX_REVIEW_NON_INTERACTIVE": "1",
+            "NOTES": "Goal: docs review gate review handoff | Summary: automated prompt with manifest evidence + scope hints | Risks: review output depends on local Codex CLI capabilities"
+          }
+        }
+      ]
+    },
+    {
+      "id": "frontend-testing",
+      "title": "Frontend Testing",
+      "description": "Runs the frontend testing runner (DevTools off by default).",
+      "tags": [
+        "frontend-testing"
+      ],
+      "guardrailsRequired": false,
+      "stages": [
+        {
+          "kind": "command",
+          "id": "frontend-testing",
+          "title": "Run frontend testing",
+          "command": "node \"$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/orchestrator/src/cli/frontendTestingRunner.js\"",
+          "env": {
+            "CODEX_NON_INTERACTIVE": "1"
+          }
+        }
+      ]
+    },
+    {
+      "id": "diagnostics-with-eval",
+      "title": "Diagnostics Pipeline (with Eval Harness)",
+      "description": "Build, lint, test, run evaluation harness, and verify specs for guardrail evidence capture.",
+      "stages": [
+        {
+          "kind": "stage-set",
+          "ref": "delegation-guard-stage"
+        },
+        {
+          "kind": "stage-set",
+          "ref": "build-lint-test"
+        },
+        {
+          "kind": "command",
+          "id": "eval-test",
+          "title": "npm run eval:test",
+          "command": "npm run eval:test"
+        },
+        {
+          "kind": "stage-set",
+          "ref": "diagnostics-spec-guard"
+        }
+      ]
+    },
+    {
+      "id": "design-reference",
+      "title": "Design Reference Pipeline",
+      "description": "Extracts design reference assets, stages Storybook-ready components, and records manifest evidence.",
+      "tags": [
+        "design",
+        "reference"
+      ],
+      "stages": [
+        {
+          "kind": "stage-set",
+          "ref": "delegation-guard-stage"
+        },
+        {
+          "kind": "command",
+          "id": "design-config",
+          "title": "Resolve design configuration",
+          "command": "node \"$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/prepare.js\"",
+          "env": {
+            "DESIGN_PIPELINE": "1"
+          }
+        },
+        {
+          "kind": "command",
+          "id": "design-extract",
+          "title": "Run Playwright design extractor",
+          "command": "node \"$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/extract.js\"",
+          "env": {
+            "DESIGN_PIPELINE": "1"
+          }
+        },
+        {
+          "kind": "command",
+          "id": "design-reference",
+          "title": "Build motherduck reference page",
+          "command": "node \"$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/reference.js\"",
+          "env": {
+            "DESIGN_PIPELINE": "1"
+          }
+        },
+        {
+          "kind": "command",
+          "id": "design-componentize",
+          "title": "Componentize artifacts via packages/design-system",
+          "command": "node \"$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/componentize.js\"",
+          "env": {
+            "DESIGN_PIPELINE": "1"
+          }
+        },
+        {
+          "kind": "command",
+          "id": "design-advanced-assets",
+          "title": "Generate advanced design assets",
+          "command": "node \"$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/advanced-assets.js\"",
+          "env": {
+            "DESIGN_PIPELINE": "1"
+          },
+          "allowFailure": true,
+          "summaryHint": "Optional Framer Motion and FFmpeg assets"
+        },
+        {
+          "kind": "command",
+          "id": "design-visual-regression",
+          "title": "Run visual regression tests",
+          "command": "node \"$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/visual-regression.js\"",
+          "env": {
+            "DESIGN_PIPELINE": "1"
+          },
+          "allowFailure": true,
+          "summaryHint": "Visual regression diffs stored under design/visual-regression/"
+        },
+        {
+          "kind": "stage-set",
+          "ref": "design-artifacts"
+        }
+      ]
+    },
+    {
+      "id": "hi-fi-design-toolkit",
+      "title": "Hi-Fi Design Toolkit",
+      "description": "Runs the hi-fi design toolkit pipeline to extract, tokenize, self-correct, and publish design artifacts.",
+      "tags": [
+        "design",
+        "hi-fi"
+      ],
+      "stages": [
+        {
+          "kind": "stage-set",
+          "ref": "delegation-guard-stage"
+        },
+        {
+          "kind": "command",
+          "id": "design-config",
+          "title": "Resolve design configuration",
+          "command": "node \"$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/prepare.js\"",
+          "env": {
+            "DESIGN_PIPELINE": "1",
+            "DESIGN_TOOLKIT": "1"
+          }
+        },
+        {
+          "kind": "command",
+          "id": "design-toolkit-extract",
+          "title": "Wrap external toolkit extractor",
+          "command": "node \"$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/toolkit/extract.js\"",
+          "env": {
+            "DESIGN_PIPELINE": "1",
+            "DESIGN_TOOLKIT": "1"
+          }
+        },
+        {
+          "kind": "command",
+          "id": "design-toolkit-tokens",
+          "title": "Generate tokens and style guides",
+          "command": "node \"$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/toolkit/tokens.js\"",
+          "env": {
+            "DESIGN_PIPELINE": "1",
+            "DESIGN_TOOLKIT": "1"
+          }
+        },
+        {
+          "kind": "command",
+          "id": "design-toolkit-reference",
+          "title": "Build reference pages + self-correction",
+          "command": "node \"$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/toolkit/reference.js\"",
+          "env": {
+            "DESIGN_PIPELINE": "1",
+            "DESIGN_TOOLKIT": "1"
+          }
+        },
+        {
+          "kind": "command",
+          "id": "design-advanced-assets",
+          "title": "Generate advanced design assets",
+          "command": "node \"$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/advanced-assets.js\"",
+          "env": {
+            "DESIGN_PIPELINE": "1",
+            "DESIGN_TOOLKIT": "1"
+          },
+          "allowFailure": true,
+          "summaryHint": "Optional motion capture via Framer Motion + FFmpeg"
+        },
+        {
+          "kind": "command",
+          "id": "design-toolkit-publish",
+          "title": "Publish toolkit outputs to packages/design-system",
+          "command": "node \"$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/toolkit/publish.js\"",
+          "env": {
+            "DESIGN_PIPELINE": "1",
+            "DESIGN_TOOLKIT": "1"
+          }
+        },
+        {
+          "kind": "stage-set",
+          "ref": "design-artifacts"
+        }
+      ]
+    },
+    {
+      "id": "tfgrpo-learning",
+      "title": "TF-GRPO Learning Loop",
+      "description": "Run three TF-GRPO epochs (~100 samples, train temp 0.7, eval temp 0.3, G>=2) and capture guardrail evidence.",
+      "tags": [
+        "tfgrpo-learning",
+        "tfgrpo-learning-secondary"
+      ],
+      "stages": [
+        {
+          "kind": "stage-set",
+          "ref": "delegation-guard-stage"
+        },
+        {
+          "kind": "command",
+          "id": "tfgrpo-loop",
+          "title": "tfgrpo learning schedule (3 epochs, 100 samples)",
+          "command": "TFGRPO_GROUP_SIZE=2 TFGRPO_REWARDERS=gt,relative TFGRPO_EPOCHS=3 TFGRPO_SAMPLE_SIZE=100 TFGRPO_TRAIN_TEMP=0.7 TFGRPO_EVAL_TEMP=0.3 node --loader ts-node/esm evaluation/harness/scripts/tfgrpo-runner.ts"
+        },
+        {
+          "kind": "stage-set",
+          "ref": "diagnostics-spec-guard"
+        }
+      ]
+    },
+    {
+      "id": "pause-eval",
+      "title": "Pause/Resume Eval",
+      "description": "Utility pipeline for long pause/resume evaluations (sleep + resume marker).",
+      "tags": [
+        "eval",
+        "pause-resume"
+      ],
+      "guardrailsRequired": false,
+      "stages": [
+        {
+          "kind": "command",
+          "id": "pause-window",
+          "title": "Sleep to allow pause",
+          "command": "sleep 120",
+          "summaryHint": "Pause window elapsed"
+        },
+        {
+          "kind": "command",
+          "id": "resume-marker",
+          "title": "Resume marker",
+          "command": "node -e \"console.log('resume-ok')\"",
+          "summaryHint": "Resume marker written"
+        }
+      ]
+    }
+  ]
+}