OrcAI.Tool 0.9.0

This package has no dependencies.

`provider:` YAML field — selects the issue/project tracking backend for a job.
`type: github` (default; omitting `provider:` entirely preserves current behaviour, no change needed to existing YAMLs).
`type: local` — tracks project/issue state as YAML + Markdown files on disk instead of calling the GitHub API. Useful for trying out a job's fan-out behaviour without touching GitHub, or for tracking work in a repo synced via git rather than the GitHub API.
`root:` (optional, `local` only) — where the local store is written, resolved relative to the YAML file's directory (same convention as `issue.template`). Defaults to `.orcai-local` next to the YAML file.
A job using `provider: local` never requires or resolves GitHub authentication — `orcai run`/`generate`/etc. work with no `GH_TOKEN`, PAT, App credentials, or `gh` CLI login at all.
Known limitations: `provider: local` has no PR tracking or bulk repo inspection. `orcai nudge`'s closed-PR handling and `orcai info`'s PR summary always show zero PRs for local jobs, and any `dependsOn` condition needing bulk repo state is unavailable.
`--provider local` flag on `orcai generate` — scaffolds a job YAML with the `provider: { type: local }` block instead of the default (GitHub).
`action:` YAML field — typed, explicit action to execute after issue creation. Supported types:
`assign-copilot` (default when `action:` is absent) — assigns `@copilot`, with an optional trigger comment.
`assign` — assigns any GitHub user or bot (`to` required, `comment` optional).
`comment` — posts a comment only, no assignment (`comment` required).
`comment-and-assign` — posts a comment then assigns (`to` and `comment` required).
`cmd` — runs a shell command or script per repo (`execute` for a script path, `run` for an inline command; mutually exclusive). Supports `args` and `cwd`. Template variables use `{{var}}` syntax: `{{repo}}`, `{{org}}`, `{{issue_number}}`, `{{issue_url}}`, `{{job_title}}`, `{{issue_text}}`, `{{issue_hash}}`, `{{yaml_hash}}`, `{{project_number}}`, `{{run_datetime}}`.
`noop` — skip the action step entirely (replaces `job.skipCopilot: true`).
`cmd-checkout` — clones the target repo (bare, `--depth 1`) and runs the command inside it. Worktrees are reused when the same repo appears across multiple jobs. Extra template variables: `{{checkout_path}}` and `{{job_title_slug}}`.
`cmd-to-github` — checkout → run → commit all changes → push branch → open PR. Supports three write-back modes: `open-pr` (default), `push-branch`, and `fork-and-pr`. Optional fields: `branch`, `commitMessage`, `prTitle`, `prBody`, `errorIfNoDiff`.
`open-pr`/`fork-and-pr` append a `Closes #{{issue_number}}` line to the PR body by default (unless the body already references the issue), so GitHub links the PR to the issue and auto-closes it on merge.
The push (`open-pr`/`push-branch`/`fork-and-pr`) always uses `git push --force`. The orcai-owned branch is always force-pushed by design, and every run starts from a fresh clone with no local remote-tracking ref for it, so `--force-with-lease` would reject the push as stale as soon as any prior run had already pushed to that branch.
Per-step failures (`CmdToGithubCheckoutFailed`/`CmdToGithubNoDiff`/`CmdToGithubPushFailed`/`CmdToGithubOpenPrFailed`) are persisted in the lock file and cleared again the next time the step succeeds, so a one-off failure doesn't get reported forever.
`copy:` list on `cmd`, `cmd-checkout`, and `cmd-to-github` actions — Docker-`COPY`-style staging of input files (e.g. a helper script or prompt file) from where `orcai` is invoked into the command's working directory before it runs. Each entry has `from` (static path or glob; zero matches is a hard error), `to` (exact file path on a single match, destination directory on a glob match), and `keep` (default `false` — deletes the copied file(s) again after the command finishes; for `cmd-to-github` this happens before the commit, so scratch files never leak into the PR diff).
New global config fields (`~/.config/orcai/config.json` / `.orcai/config.json`):
`checkoutRoot` — override the directory where repos are cloned for `cmd-checkout` and `cmd-to-github`. Defaults to an OS temp directory scoped to the run.
`action.writeBack` — global default write-back mode for `cmd-to-github` (`open-pr` | `push-branch` | `fork-and-pr`). Nested under `action` in the config JSON. Overridden by `writeBack` in the job YAML.
`action.onClosedPr` — global default for `cmd-to-github`'s `onClosedPr` (`skip` | `recreate` | `reopen` | `fail`). Nested under `action` in the config JSON. Overridden by `onClosedPr` in the job YAML.
`cmd-to-github` (`open-pr`/`fork-and-pr` write-back modes) is now idempotent by design instead of only by accident of a clean lock file. Before cloning, `orcai run` checks live GitHub state (a PR linked to the issue via `closingPullRequests`, and whether the branch already exists on the remote) — never the lock file, so behaviour is identical whether or not one is present:
An **open** PR with unchanged YAML/template hashes is left alone entirely — no clone, no re-run of `execute`, no push. This holds even with no lock file present at all (deleted, or a fresh checkout on CI): with no prior lock to compare against, the content is assumed unchanged rather than treated as changed, so a missing lock file never forces a redo/force-push of an already-open PR.
A **merged** PR is always left alone, regardless of hash changes.
A **closed** (unmerged) PR is handled per the new `onClosedPr` field (see below).
When no PR is found but the branch already exists on the remote and hashes are unchanged, only `gh pr create` is retried against the existing branch — still no clone/execute/push.
`onClosedPr` field on `cmd-to-github` (job YAML, mirrors `job.onClosedIssue`'s shape) — controls what happens when the only PR found for the branch is closed without merging. Values: `skip` (default — treat as an intentional decision, do nothing), `recreate` (redo the full run and open a brand-new PR), `reopen` (`gh pr reopen` plus a force-push of fresh content to the existing branch, no new PR), `fail` (record a failure requiring manual intervention). Has no effect with `writeBack: push-branch`, which never creates a PR.
**GitHub App permission**: The **Contents** permission on the GitHub App must now be set to **Read & write** (instead of Read) to support push-based action types (`cmd-to-github` with `open-pr` or `push-branch`). OrcAI injects the resolved App/PAT token into the checkout git/PR subprocesses automatically — no separate credential setup is required.
`dependsOn` YAML field — gates a downstream job on the completion state of one or more upstream jobs. Each entry specifies a `job` (relative path), `condition` (`pr_merged` | `issue_closed`), `scope` (`per_repo` | `all_repos`), and `untrackedRepos` (`include` | `skip`). Multiple entries use AND logic.
`orcai run` now resolves `dependsOn` chains in topological order before executing. Passing a downstream YAML is sufficient — upstream dependencies are discovered and run automatically. The `scope: all_repos` option blocks the entire downstream run when any upstream repo has not met the condition; `scope: per_repo` (default) filters the downstream repo list individually.
`orcai graph <yaml>` — new command that renders the `dependsOn` dependency tree as an ASCII diagram. File-system only; no GitHub API calls. Supports `--json` output.
`orcai validate` now detects circular `dependsOn` references and missing upstream files, reporting them as configuration errors.
`orcai nudge --on-closed-pr` — controls what happens when the only PRs found for an issue are closed without merging. Values: `skip` (default — don't nudge), `nudge` (re-trigger the assignee anyway), `fail` (report as a failure). Merged PRs are always treated as done and never trigger this flag.
`orcai migrate <yaml>` — upgrades a job YAML and its sibling `.lock.json` in place to the current schema version, preserving old runtime behaviour (e.g. `assign:`/`skipCopilot` → the equivalent `action:` block, `onClosedIssue` default preserved explicitly). The lock file step is purely local — no GitHub calls — so migrating never forces a job's repos back onto the live lookup path the way deleting the lock file would. Supports `--dryrun` and `--json`; always backs up any file it changes to `<file>.bak` first. Designed to extend to future schema hops (v2→v3, etc.) without restructuring — each hop is an independent step.
**BREAKING**: Issue and project identifiers are now opaque strings instead of GitHub-shaped integers (internal groundwork for supporting non-GitHub providers in the future). User-visible effects:
**Lock files**: the `.lock.json` format has changed. Existing lock files fail to load with a message pointing at `orcai migrate <yaml>` (upgrades the lock file in place, no GitHub calls) as the recommended fix; deleting the file and re-running `orcai run` still works but re-fetches state from GitHub for every repo.
**`--json` output**: issue and project numbers in `orcai run --json`, `orcai info --json`, and `orcai cleanup --json` are now emitted as JSON strings instead of numbers (e.g. `"issueNumber": "42"` instead of `"issueNumber": 42`). Human-readable console output (e.g. `#42`) is unchanged.
**BREAKING**: `onClosedIssue` default changed from `create` to `skip`. Previously, when a closed issue with a matching title was found, OrcAI would open a new issue alongside it. Now it treats the closed issue as already done and skips the repo. To restore the old behaviour, add `onClosedIssue: create` to the `job:` block in your YAML. The `redoOnClosed` YAML field and config option (added as a workaround for the wrong default on checkout actions) have been removed; use `onClosedIssue: create` instead.
**BREAKING**: `assign:` YAML block removed. Validation fails with a migration message when `assign:` is present. Migrate to `action: { type: assign-copilot, ... }` or the appropriate action type.
**BREAKING**: `job.skipCopilot` removed. Validation fails with a migration message when present. Use `action: { type: noop }` to skip assignment, or omit `action:` to assign `@copilot`.
**BREAKING**: `--skip-copilot` CLI flag removed from `orcai run` and `orcai generate`. Use `action: { type: noop }` in the YAML instead.
**BREAKING**: `skipCopilot` and `assign` fields removed from the global/local JSON config (`~/.config/orcai/config.json`). `action:` is per-job only.
**BREAKING**: Top-level `writeBack` config key moved to `action.writeBack`. Update config files from `"writeBack": "..."` to `"action": { "writeBack": "..." }`.
`orcai generate` no longer generates a `skipCopilot` comment line; generates an `action:` comment block instead.
`orcai generate` now scaffolds a `version: 2` field at the top of every generated job YAML, so newly-created files self-declare their schema version the same way `orcai migrate` stamps it onto upgraded ones. The field is inert today (ignored by the parser) but lets future schema migrations detect a file's version without a structural heuristic.
`orcai nudge` and `orcai notify` derive the `{assignee}` template variable from the job's `action:` type rather than `assign.to`.
`orcai nudge` now surfaces PR state when checking for existing PRs. The `state` field (`OPEN`, `CLOSED`, `MERGED`) is stored on PR entries in the lock file; old lock files without the field default to `OPEN` on load.
`orcai nudge` no longer treats a closed PR in the lock file as "PR exists — skip". Only open PRs in the lock suppress the live check. Closed PR entries (e.g. written by `orcai info --save-lock`) are now ignored by the lock-file fast-path, so nudge correctly proceeds to a live GitHub check for those issues.
`orcai nudge --save-lock` now persists all discovered PRs with their state to the lock file, so closed PRs are visible via `orcai info`.