@mcrescenzo/opencode-workflows 0.1.0

package/SECURITY.md

@@ -0,0 +1,38 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are handled on the current `main` branch until the first public
+release process defines versioned support windows. Treat unpublished snapshots
+and local plugin checkouts as unsupported outside their owning checkout.
+
+## Reporting A Vulnerability
+
+Report suspected sandbox escapes, authority bypasses, unsafe primary-tree writes,
+secret disclosure, or child-process abuse privately through the
+[GitHub Security Advisory flow](https://github.com/mcrescenzo/opencode-workflows/security/advisories/new)
+for this repository. Include a minimal reproduction, affected commit or version,
+and whether the issue needs a configured extension, a project workflow, or only
+core plugin tools.
+
+Please do not publish exploit details before there is a coordinated fix or a
+mutual disclosure date. Do not open a public GitHub issue for an unpatched
+vulnerability.
+
+## Trust Boundary
+
+Workflow scripts are guest code and run inside the QuickJS sandbox with injected
+workflow globals only. They do not receive Node `fs`, `child_process`, `require`,
+or direct domain-store access.
+
+Configured workflow extensions are different: they are trusted host modules.
+Adding an extension path to opencode config imports and runs that module in the
+plugin's Node process with normal local privileges before exported capabilities
+are structurally validated. The core plugin does not currently enforce extension
+signatures, hash pins, or a module allowlist.
+
+The kernel's authority, path, approval, and live-gate checks protect core guest
+and tool flows. They do not automatically sandbox extension-contributed tools,
+drain adapters, or mutation finalizers. Extension code can call provided guard
+helpers, but that is part of the extension's trusted implementation. Only load
+extensions you trust as local code.

package/commands/repo-bughunt.md

@@ -0,0 +1,94 @@
+---
+description: Run the repo-bughunt read-only review workflow and persist a single-domain report
+---
+
+Mode: read-only review. This command runs only the bundled `repo-bughunt` leaf
+workflow, reads back its result, and persists one report artifact under
+`.repo-review/runs/`. Use the `repo-review-command-protocol` skill for the
+shared wrapper steps; this file supplies the bughunt-specific args, workflow
+name, result fields, and report filename.
+Canonical references: `workflow_list({ format: "json" })` is the
+machine-readable workflow discovery surface; tool mutability and safe readback
+are in `docs/workflow-plugin.md#workflow-tool-reference`; raw run artifact
+handling is in the README source-of-truth section.
+
+## 1. Bughunt Args
+
+Validate `$ARGUMENTS` before touching `workflow_run`.
+
+- If `$ARGUMENTS` is empty, default to the engine's thorough read-only review:
+
+  ```json
+  {}
+  ```
+
+- If `$ARGUMENTS` is non-empty, it MUST parse as valid JSON and resolve to a
+  plain object. If it fails to parse, or parses to a string, number, boolean,
+  array, or null, STOP before `workflow_run` and report the argument error.
+- If present, `depth` MUST be one of `quick`, `normal`, or `thorough`.
+- Optional recognized keys: `paths`, `exclude`, `categories`,
+  `maxReturnFindings`, `recon`. Pass through only what the user supplied.
+
+Carry the validated object forward as `args`.
+
+## 2. Models
+
+Follow the `workflow-model-tiering` skill before invoking `workflow_run`: call
+`workflow_models`, map `fast` (recon + finders) and `deep` (skeptics) to concrete
+models inside the invoking session family, and confirm with the user only when
+the plan deviates from that family. Pass `modelTiers: { fast, deep }`.
+
+## 3. Run, Read, Persist
+
+Invoke the bundled workflow by name only, never by file path:
+`workflow_run({ name: "repo-bughunt", args, modelTiers, format: "json" })`.
+
+```json
+{
+  "name": "repo-bughunt",
+  "args": "<the validated args object from step 1>",
+  "modelTiers": { "fast": "<fast model>", "deep": "<deep model>" },
+  "format": "json"
+}
+```
+
+Use `workflow_run` for launch. If it returns a preview, report `.approvalHash`,
+`.authority.profile` (`read-only-review`), and `.modelPlan`, then re-run with
+`approve: true` and the matching `approvalHash`. If configured autoApprove
+launches immediately, report the `runId` and status from that first call.
+
+After terminal status, read the redacted envelope with:
+
+```json
+{ "runId": "<the run id>", "detail": "result" }
+```
+
+That is `workflow_status({ runId, detail: "result" })`. The leaf envelope is at
+`.result.output`: `status`, `summary`, `counts`, `findings`,
+`truncatedFindings`, and `reportMarkdown`.
+
+Persist exactly one report:
+
+- Directory: `mkdir -p .repo-review/runs`
+- File: `.repo-review/runs/<run-id>-bughunt-report.md`
+- Preferred: write `.result.output.reportMarkdown` when present.
+- Fallback: when `reportMarkdown` is null or omitted for size, synthesize a short
+  fallback summary from returned `summary`, `counts`, and `findings` only. State
+  that full `reportMarkdown` was omitted for size / 256 KiB cap and do not invent
+  findings outside the returned subset.
+- Footer: `Report-only - nothing applied.`
+
+## 4. Boundary
+
+This command is report-only. Avoid `materialize`, `beads-drain`,
+`workflow_apply`, any `git` write, and any `bd` create/update/close/claim. The
+ONLY allowed workspace write is the local
+`.repo-review/runs/<run-id>-bughunt-report.md` report artifact. `.repo-review/`
+is gitignored; do not stage or commit it.
+
+## 5. Report Back
+
+Report the validated args, model plan, `approvalHash` when a preview was shown,
+`runId`, terminal status, envelope `status`/`summary`/`counts`, whether
+`reportMarkdown` was present or the size-fallback summary was rendered,
+`truncatedFindings`, and the absolute report path.

package/commands/repo-review.md

@@ -0,0 +1,148 @@
+---
+description: Run the repo-review exhaustive read-only review workflow and persist the merged eight-domain report
+---
+
+Mode: read-only review. This command runs the bundled `repo-review` META
+workflow over the eight repo-* leaf domains, reads back the unified result, and
+persists one merged report artifact under `.repo-review/runs/`. Use the
+`repo-review-command-protocol` skill for the shared wrapper steps; this file
+supplies the meta-specific args, no-fast-model policy, merged-result fields, and
+materialization offer rule. It is distinct from `/repo-bughunt`, which runs only
+the bughunt leaf.
+Canonical references: `workflow_list({ format: "json" })` is the
+machine-readable workflow discovery surface; tool mutability and safe readback
+are in `docs/workflow-plugin.md#workflow-tool-reference`; raw run artifact
+handling is in the README source-of-truth section.
+
+## 1. Meta Args
+
+Validate `$ARGUMENTS` before touching `workflow_run`.
+
+- If `$ARGUMENTS` is empty, default to an exhaustive full-suite review:
+
+  ```json
+  { "mode": "exhaustive" }
+  ```
+
+- If `$ARGUMENTS` is non-empty, it MUST parse as valid JSON and resolve to a
+  plain object. If it fails to parse, or parses to a string, number, boolean,
+  array, or null, STOP before `workflow_run` and report the argument error.
+- `mode` is `exhaustive` (default) or `bounded`. Exhaustive uses `depth:
+  "thorough"`, high `maxReturnFindings`, and the coverage auditor lane. Bounded
+  uses the legacy normal-depth pass.
+- `depth` is `quick`, `normal`, or `thorough` when supplied.
+- Optional recognized keys: `domains`, `paths`, `exclude`, `maxReturnFindings`,
+  `batchSize`, `recon`, `maxDirs`, `deepMode`.
+- `deepMode` may select `audited-shell` when the caller explicitly wants the
+  command-scoped shell inspection mode and the required gates are verified.
+- `domains` may name any subset of `bughunt`, `security`, `test-gaps`,
+  `cleanup`, `modernize`, `perf`, `complexity`, `deps`, or their `repo-*` leaf
+  names. Unknown domains are rejected rather than falling back to all domains.
+
+Carry the validated object forward as `args`.
+
+## 2. Resolve Model Tiers - NO FAST MODELS
+
+Follow `workflow-model-tiering` to enumerate available models, but this command
+NEVER selects a fast model. The meta's `fast` and `deep` labels are lane intent
+markers, not permission to pick a low-quality model. Resolve one high-quality
+deep model inside the session family and map both tiers to the same deep model:
+
+```json
+{
+  "modelTiers": {
+    "fast": "<the deep model>",
+    "deep": "<the deep model>"
+  }
+}
+```
+
+If the selected model deviates from the session family, confirm explicitly before
+launch. Do NOT set `maxCost` or `maxTokens`; exhaustive mode spares no expense.
+
+## 3. Run, Read, Persist
+
+Invoke the bundled workflow by name only, never by file path:
+`workflow_run({ name: "repo-review", args, modelTiers, format: "json" })`.
+
+```json
+{
+  "name": "repo-review",
+  "args": "<the validated args object from step 1>",
+  "modelTiers": { "fast": "<deep model>", "deep": "<deep model>" },
+  "format": "json"
+}
+```
+
+Use `workflow_run` for launch. If it returns a preview, report `.approvalHash`,
+`.authority.profile` (`read-only-review`), and `.modelPlan`, then re-run with
+`approve: true` and the matching `approvalHash`. If configured autoApprove
+launches immediately, report the `runId` and status from that first call. The
+meta never edits, commits, or writes files; nested leaves share the parent
+`maxAgents:100000, concurrency:16` budget. Each leaf's OWN declared `maxAgents`
+and `concurrency` are ignored at runtime under the meta run.
+
+After terminal status, read the redacted envelope with:
+
+```json
+{ "runId": "<the run id>", "detail": "result" }
+```
+
+That is `workflow_status({ runId, detail: "result" })`. The merged envelope is
+at `.result.output` and includes `domain: "repo-review"`, `status`, `summary`,
+`counts`, ranked `findings`, `truncatedFindings`, `reportMarkdown`,
+`leafOutcomes`, `partialCoverage`, `artifactPaths.reportMarkdownPath`,
+`materializationReady`, `materializationBlockers`, `coverageGrade`,
+`coverageAdvisories`, `coverageAudit`, and `artifactPaths.findingsJson`.
+
+Persist exactly one report:
+
+- Directory: `mkdir -p .repo-review/runs`
+- File: `.repo-review/runs/<run-id>-repo-review-report.md`
+- Preferred: read `artifactPaths.reportMarkdownPath` and use that full ranked cross-domain markdown report.
+- Fallback: if `reportMarkdown` is non-null, treat it as a bounded
+  preview/fallback body.
+- Fallback: when `reportMarkdown` is null or omitted for size, synthesize a short
+  fallback summary from returned `summary`, `counts`, `leafOutcomes`, and
+  `findings` only. State that full `reportMarkdown` was omitted for size /
+  256 KiB cap and do not invent findings outside the returned subset.
+- Footer: `Report-only - nothing applied.`
+
+## 4. Coverage And Materialization
+
+Report `leafOutcomes` and `partialCoverage` so the user sees which domains
+completed or failed. Report materialization readiness separately:
+`materializationReady`, `materializationBlockers`, `coverageGrade`,
+`coverageAdvisories`, and `coverageAudit`.
+
+If `materializationReady` is true and there is at least one finding, first
+confirm the Beads extension has contributed `/review-materialize` in the command
+registry. If that command is absent, report that the command is unavailable and
+do not offer an unavailable action. If available, offer the user the option of
+creating a duplicate-aware Beads epic via separately approved
+`/review-materialize` with the completed review's `runId`. The materialization
+tool validates `domain: "repo-review"`, consumes `artifactPaths.findingsJson`,
+passes the full findings through its `findingsPath` handoff, and derives its
+default program label from review-time provenance rather than current `HEAD`.
+
+If `materializationReady` is false, list every blocker and state that
+materialization is blocked. Do not proceed.
+
+## 5. Boundary
+
+This command is report-only. It must never run `materialize`, `beads-drain`,
+`workflow_apply`, any `git` write, or any `bd` create/update/close/claim. The
+ONLY allowed workspace write is the local
+`.repo-review/runs/<run-id>-repo-review-report.md` report artifact. The
+materialization item above is a question to the user, not a mutation from this
+command. `.repo-review/` is gitignored; do not stage or commit it.
+
+## 6. Report Back
+
+Report the validated args including `mode`, model plan confirming both tiers
+resolved to the same deep model - no fast model, `approvalHash` when a preview
+was shown, `runId`, terminal status, envelope `status`/`summary`/`counts`,
+`leafOutcomes`, `partialCoverage`, `materializationReady`,
+`materializationBlockers`, `coverageGrade`, `coverageAudit`, whether the full
+artifact, bounded `reportMarkdown` preview/fallback, or size-fallback summary
+was used, `truncatedFindings`, and the absolute report path.

package/commands/workflow-live-gates-release-check.md

@@ -0,0 +1,143 @@
+---
+description: Run the opt-in active-runtime workflow live-gate release check
+---
+
+Run the active-runtime workflow live-gate release check only because the user explicitly invoked this command or otherwise approved token/worktree side effects.
+Canonical references: live-gate behavior is summarized in the README live-gates
+section, and `workflow_live_gates` mutability/approval requirements are listed in
+`docs/workflow-plugin.md#workflow-tool-reference`.
+
+Before running probes, state these side effects briefly:
+
+- Session probes can spend model tokens.
+- The concurrency-capacity probe launches `concurrencyProbeLimit` child prompts at once; keep the limit modest unless the user approved a larger burst.
+- Worktree probes can create and remove throwaway worktrees.
+- Background and notification probes can schedule asynchronous OpenCode work.
+- Plugin or command changes require restarting OpenCode before this check reflects them.
+
+Then call `workflow_live_gates` with every behavioral probe enabled and `format: "json"`:
+
+```json
+{
+  "format": "json",
+  "approvalIntent": "probe",
+  "probePermissionEnforcement": true,
+  "probeDeniedBash": true,
+  "probeCommandScopedBash": true,
+  "probeSecretReadDeny": true,
+  "probeStructuredOutput": true,
+  "probeWorktreeApi": true,
+  "probeDirectoryRooting": true,
+  "probeWorktreeEditIsolation": true,
+  "probeIntegrationWorktreeIsolation": true,
+  "probeBackgroundContinuation": true,
+  "probeConcurrencyCapacity": true,
+  "concurrencyProbeLimit": 16,
+  "probeCancellation": true,
+  "probeWorkflowNotification": true
+}
+```
+
+Report the raw JSON evidence in the transcript or point to the exact saved evidence location if the output is too large.
+
+Readiness is reported per capability tier, not as a single all-gates verdict,
+because the non-dry `beads-drain` profile (`drain-autonomous-local`) uses
+integration-worktree isolation and does not require the native edit-mode
+worktree gates. Conflating the tiers overblocks valid Beads readiness.
+
+## Full / native edit-mode readiness
+
+All gates verified. Required for `edit-plan-only` and any workflow that edits through the
+native worktree API.
+
+Pass criteria:
+
+- `configured` is `true`.
+- `verified` is `true`.
+- Every entry in `gates` has `state: "verified"` and `verified: true`, including
+  `worktreeApi` and `worktreeEditIsolation`.
+
+If any gate is `blocked`, `available-unverified`, or `failed-with-evidence`, do not claim
+full/native edit-mode release readiness. Report `[release-gate:blocked]` with the tier
+(`full-edit`), the non-verified gate names, and evidence.
+
+## Non-dry beads-drain readiness
+
+Only the Beads-required gate subset must be verified. This subset mirrors
+`NON_DRY_DRAIN_REQUIRED_GATES` in `workflow-kernel/authority-policy.js`:
+
+- `permissionEnforcement`
+- `commandScopedBash`
+- `secretReadDeny`
+- `structuredOutput`
+- `directoryRooting`
+- `integrationWorktreeIsolation`
+- `cancellation`
+
+The native worktree gates `worktreeApi` and `worktreeEditIsolation` are NOT required for
+non-dry Beads readiness, because Beads profiles use integration-worktree isolation instead.
+`backgroundContinuation` and `workflowNotification` are also not in the Beads subset.
+
+Pass criteria for non-dry Beads readiness:
+
+- `configured` is `true`.
+- Every gate listed in the Beads subset above has `state: "verified"` and `verified: true`.
+
+If a Beads-subset gate is `blocked`, `available-unverified`, or `failed-with-evidence`, do
+not claim non-dry beads-drain release readiness. Report `[release-gate:blocked]` with the
+tier (`beads-non-dry`), only the non-verified Beads-subset gate names, and evidence. Do not
+include native worktree gates in the Beads blocked message.
+
+A `[release-gate:blocked]` for `full-edit` does NOT imply Beads is blocked, and a
+`[release-gate:blocked]` for `beads-non-dry` does NOT imply full/native edit is blocked.
+
+## Evidence-strength caveat (do not overclaim permission or rooting gates)
+
+A verified gate is not always equivalent to directly-observed target behavior. Each
+verified gate carries an `evidenceStrength` field:
+
+- `observed` — the probe directly observed the target behavior (a denied tool part,
+  denial text, a thrown denial, a successful create/remove, a completed sentinel read,
+  etc.). Strong evidence.
+- `no-attempt-fallback` — the probe observed no tool attempt at all (the denied tool
+  appears hidden/unavailable) and verified only that retained deny rules held and no
+  successful tool call occurred. This is a compatibility path for runtimes that hide
+  fully-denied tools, not behavioral enforcement proof. Used only by
+  `permissionEnforcement`.
+- `model-text-only` — the probe observed only model-reported text matching the expected
+  value, without a deterministic tool result. Historically used by `directoryRooting` when
+  the child echoed the assigned directory but did not perform (or did not expose) the
+  sentinel read tool call. The model can echo a directory without being rooted there, so
+  this is not equivalent to an observed tool-anchored rooting proof. As of the R31 fix
+  (`directoryRooting`) and the integration-worktree rooting hardening
+  (`integrationWorktreeIsolation`), neither gate PRODUCES this strength anymore: a text-only
+  echo is reported as `available-unverified` (verified=false), so the required rooting
+  authority cannot be satisfied without a completed `read` tool part returning unique
+  on-disk sentinel content. The strength is retained for the down-ranker's scope lock.
+- `in-process-smoke` — the probe verified only in-process event-loop yield and did not
+  exercise the OpenCode background subsystem. Used by `backgroundContinuation`. Restart
+  survival is not implied; production background continuation across OpenCode restart is
+  out of scope for this gate.
+
+`commandScopedBash` and `secretReadDeny` stay strict: they do not use the
+`no-attempt-fallback` and report `blocked` when no tool attempt is observable.
+
+Before claiming non-dry readiness, inspect each verified gate's `evidenceStrength`:
+
+- If every required gate is `observed`, the readiness verdict above holds as-is.
+- If `permissionEnforcement` is `no-attempt-fallback`, do NOT claim equivalence to an
+  observed denial. Report `[release-gate:weak-evidence]` with the gate name and state
+  that the hidden/no-attempt fallback was accepted only if an explicit policy/operator
+  decision confirms this runtime hides fully-denied tools by design. Without that
+  explicit acceptance, treat the gate as not-yet-proven and do not advance to a non-dry
+  release verdict.
+- If `directoryRooting` or `integrationWorktreeIsolation` is `available-unverified` with
+  "model-reported cwd text" evidence, do NOT claim deterministic runtime/tool rooting
+  evidence. The child echoed the target directory without a completed sentinel `read`, so
+  rooting is unproven. Report `[release-gate:weak-evidence]` and request a runtime/tool-
+  anchored sentinel read before advancing to a non-dry release verdict. (Pre-fix these
+  gates could return `verified` with `evidenceStrength:"model-text-only"`; both now
+  downgrade a text-only echo to `available-unverified`.)
+- `backgroundContinuation` is always `in-process-smoke` in this build. Treat its
+  `verified` state as proof of in-process continuation only and never as restart
+  survival. Restart-surviving background execution is out of scope.