@jterrats/open-orchestra 1.1.1 → 1.2.0

package/docs/release-inclusion-manifest.md

@@ -0,0 +1,142 @@
+# Release Inclusion Manifest
+
+Open Orchestra stays trunk-based, but release tags use an explicit release
+inclusion manifest to decide which completed work belongs to a version bump.
+
+## Location
+
+The canonical manifest path is:
+
+```text
+.agent-workflow/releases/release-inclusion.json
+```
+
+The manifest is workflow-local state. It is intended to be reviewed with the
+release evidence for a candidate version, not bundled into the published npm
+package as product behavior.
+
+## Schema
+
+`schemaVersion` is currently `1`. Each item must declare:
+
+- `state`: one of `included`, `excluded`, `deferred`, `blocked`, or
+  `already_released`.
+- `taskId`: the Orchestra or GitHub-backed task id.
+- `issueUrl`: the HTTPS issue URL for traceability.
+- `commitReference`: a commit SHA or `start..end` SHA range.
+- `versionTarget`: the semver version the item is evaluated against.
+- `releaseNote`: a category and release-note text.
+- `evidence`: one or more command, file, report, screenshot, trace, or video
+  references.
+- `review`: status and reviewer roles or names.
+- `risk`: risk status, rationale, and accepted-by marker when accepted.
+- `rollback`: rollback note.
+- `owner`: owner role and optional owner name.
+
+## Manual Editing
+
+Keep manual edits deterministic:
+
+- Sort items by `versionTarget`, then state, then `taskId`.
+- Keep all text concise and reviewable in diffs.
+- Prefer stable artifact paths or event ids for evidence references.
+- Do not paste secrets, raw provider prompts, or full sensitive transcripts.
+- Update `schemaVersion` only through a migration story.
+
+## CLI Workflow
+
+Validate and inspect candidate scope for a version:
+
+```sh
+orchestra release inclusion --version 1.1.3
+orchestra release inclusion --version 1.1.3 --json
+```
+
+Generate release notes from `included` items only:
+
+```sh
+orchestra release notes --version 1.1.3
+```
+
+Check tag readiness without creating a tag:
+
+```sh
+orchestra release readiness --version 1.1.3
+```
+
+The readiness gate only evaluates `included` items for the requested version.
+Items marked `excluded`, `deferred`, `blocked`, or `already_released` remain
+visible in the candidate report but are non-release scope for notes and tag
+preparation.
+
+## GitHub and CI Sync
+
+The manifest is the source of truth. GitHub labels, issue comments, project
+fields, and CI artifacts are mirrors that help reviewers find state without
+making GitHub required for local release work.
+
+Recommended GitHub metadata mapping:
+
+| Manifest state | Optional GitHub label | Release behavior |
+| --- | --- | --- |
+| `included` | `release:included` | Eligible for release notes and tag readiness. |
+| `excluded` | `release:excluded` | Reported separately and omitted from notes. |
+| `deferred` | `release:deferred` | Omitted until a later manifest update. |
+| `blocked` | `release:blocked` | Omitted and should keep release review blocked. |
+| `already_released` | `release:already-released` | Omitted from the next bump/tag scope. |
+
+CI runs release inclusion validation in non-publishing mode. When a manifest is
+present, CI should build the package, run `orchestra release inclusion
+--version <package.json version> --json`, and upload the JSON report as a
+review artifact. This check must not create tags or publish packages.
+
+Manual fallback:
+
+- If GitHub metadata is unavailable, reviewers use the manifest and CLI report.
+- If CI cannot access secrets, run the same CLI commands locally and attach the
+  JSON output as release evidence.
+- If GitHub labels drift from the manifest, update labels/comments to match the
+  manifest rather than editing the manifest to match labels.
+
+## Example
+
+```json
+{
+  "schemaVersion": 1,
+  "versionTarget": "1.1.3",
+  "items": [
+    {
+      "state": "included",
+      "taskId": "GH-530",
+      "issueUrl": "https://github.com/jterrats/open-orchestra/issues/530",
+      "commitReference": "82ec5df",
+      "versionTarget": "1.1.3",
+      "releaseNote": {
+        "category": "internal",
+        "text": "Define release inclusion manifest schema."
+      },
+      "evidence": [
+        {
+          "type": "command",
+          "summary": "Release inclusion schema tests passed.",
+          "reference": "node --test test/release-inclusion.test.js"
+        }
+      ],
+      "review": {
+        "status": "approved",
+        "reviewers": ["qa", "release_manager"]
+      },
+      "risk": {
+        "status": "not_required",
+        "rationale": "Schema-only change with no release publishing behavior."
+      },
+      "rollback": {
+        "note": "Revert schema and docs commit before candidate generation."
+      },
+      "owner": {
+        "role": "release_manager"
+      }
+    }
+  ]
+}
+```

package/docs/runtime-adapters.md

@@ -501,8 +501,11 @@ agent path and records that choice in phase provenance.
 
 When no task or role executor is configured and the default executor is
 `generic-runtime`, `auto` and strict `subagents` mode infer the active runtime
-from `.agent-workflow/active-runtime.json`, then from `OPEN_ORCHESTRA_ACTIVE_RUNTIME`
-as a final fallback for non-hook environments (CI, scripts).
+from `OPEN_ORCHESTRA_ACTIVE_RUNTIME`, then from
+`.agent-workflow/active-runtime.json`. The environment value accepts either the
+runtime target (`claude`, `codex`, `cursor`) or the executor id
+(`claude-cli`, `codex-cli`, `cursor-cli`) and wins over a stale or mismatched
+persisted record so a parent runtime can correct cross-project/session drift.
 
 `.agent-workflow/active-runtime.json` is the truthful signal of which AI runtime
 is currently driving the conversation. It is written by the active runtime's
@@ -515,8 +518,9 @@ pattern that must run at session start. Each hook overwrites the file with its
 own runtime id, so "last writer wins" matches "current parent runtime".
 
 The persisted record has a 24h TTL. Records older than that are ignored and
-inference falls through to the next signal. Codex maps to `codex-cli`, Claude
-maps to `claude-cli`, Cursor maps to `cursor-cli`, Windsurf maps to
+inference falls through to the default when no environment override is present.
+Codex maps to `codex-cli`, Claude maps to `claude-cli`, Cursor maps to
+`cursor-cli`, Windsurf maps to
 `windsurf-agent`, and VS Code maps to `vscode-agent`.
 
 Explicit selections always take precedence in this order: `--runtime` flag,

package/docs/security-env-vars.md

@@ -18,6 +18,7 @@ or local secret files.
 - `OPENAI_API_KEY_FILE`: optional OpenAI credential file path.
 - `OPEN_ORCHESTRA_CLAUDE_NATIVE_CALLBACK`: local Claude native callback marker.
 - `OPEN_ORCHESTRA_CLAUDE_NATIVE_CHILD_ID`: Claude native child id marker.
+- `OPEN_ORCHESTRA_COMMAND_MANIFEST_OUT`: optional command manifest check output path.
 - `ORCHESTRA_GITLEAKS_BIN`: optional absolute gitleaks binary override.
 - `ORCHESTRA_SECRET_SCAN_FORCE_FALLBACK`: forces fallback secret scanning.
 - `ORCHESTRA_SKIP_UPDATE_CHECK`: disables package update checks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jterrats/open-orchestra",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "type": "module",
   "workspaces": [
     "extensions/vscode-open-orchestra",
@@ -30,7 +30,11 @@
     "validate:workflow": "node scripts/validate-workflow.js",
     "release:matrix": "node scripts/release-test-matrix.js",
     "performance:bench": "npm run build && node scripts/performance-benchmark.js",
-    "precommit": "npm run lint && npm run typecheck && npm run secret-scan && npm run security:audit && npm test && npm run validate:workflow",
+    "check:commands": "npm run build && node scripts/check-command-manifest.js",
+    "precheck": "npm run check:commands",
+    "precommit": "npm run precheck",
+    "prepush": "npm run precheck",
+    "ci:quality": "npm run lint && npm run typecheck && npm run secret-scan && npm run security:audit && npm test && npm run validate:workflow",
     "package:build": "npm run build && npm run site:build",
     "package:validate": "node scripts/validate-package-contents.js",
     "prepack": "npm run package:build && npm run package:validate",