From 574d7c38b6813f799ac385e77a030fc63adcf1b6 Mon Sep 17 00:00:00 2001 From: Matt Jackson Date: Thu, 22 Oct 2026 03:52:59 +0000 Subject: [PATCH 1/2] fix: execute requested Beads command workflows --- CHANGELOG.md | 6 + README.md | 12 +- assets/oc-beads/SKILL.md | 26 ++- assets/oc-beads/resources/CLI_REFERENCE.md | 62 +++++- assets/oc-beads/resources/TROUBLESHOOTING.md | 21 +- assets/oc-beads/resources/WORKTREES.md | 10 +- docs/command-action-evaluation.md | 210 ++++++++++++++++++ .../opus-command-action-source-recheck-wzk.md | 30 +++ .../reviews/opus-command-action-source-wzk.md | 58 +++++ .../.openspec.yaml | 2 + .../design.md | 25 +++ .../proposal.md | 26 +++ .../specs/workflow-access/spec.md | 105 +++++++++ .../tasks.md | 14 ++ openspec/specs/workflow-access/spec.md | 36 ++- scripts/test-package.ts | 18 +- src/guidance.ts | 2 +- src/workflows.ts | 28 +-- tests/docs.test.ts | 23 ++ tests/guidance.test.ts | 2 + tests/host.test.ts | 20 ++ tests/workflows.test.ts | 44 +++- 22 files changed, 744 insertions(+), 36 deletions(-) create mode 100644 docs/command-action-evaluation.md create mode 100644 docs/reviews/opus-command-action-source-recheck-wzk.md create mode 100644 docs/reviews/opus-command-action-source-wzk.md create mode 100644 openspec/changes/archive/2026-10-22-execute-command-intent/.openspec.yaml create mode 100644 openspec/changes/archive/2026-10-22-execute-command-intent/design.md create mode 100644 openspec/changes/archive/2026-10-22-execute-command-intent/proposal.md create mode 100644 openspec/changes/archive/2026-10-22-execute-command-intent/specs/workflow-access/spec.md create mode 100644 openspec/changes/archive/2026-10-22-execute-command-intent/tasks.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 04a0b31..b2e9701 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,12 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/ ## [Unreleased] +### Fixed + +- Render command invocation and requested outcome even without trailing details; sufficient-input actions perform their bounded request, explicit help explains, and missing inputs prompt focused clarification under existing permissions and policy. +- Make ordinary sync request supported `bd sync --no-adopt` with existing configuration and actual executor actor, reporting missing remote or failure without adoption/provisioning. Align affected authority clauses and primary supporting resources while preserving guide artifacts, command inventory and qualification limits. + + ## [1.1.0-beta.2] ### Changed diff --git a/README.md b/README.md index 3470800..19bd4a3 100644 --- a/README.md +++ b/README.md @@ -121,9 +121,19 @@ Published stable 1.0.2 registers no slash commands; `bd setup claude` installs n The commands are workflow prompts, not exact CLI aliases. In particular, init guides human onboarding, prime reuses context or requests a guarded refresh, version reports installed versions and qualification limits, decision records rationale, template discovers formulas, and workflow guides authorized work and recovery. These purposes do not imply native `bd decision`, `bd template` or `bd workflow` commands. +**Unreleased source behavior:** an invocation itself requests the advertised bounded +operation, including bare `/oc-beads:sync`. With sufficient inputs the agent uses +permissioned tools and reports the actual outcome; `/oc-beads:sync explain` +explains without syncing, and missing required inputs prompt focused clarification. +Ordinary sync uses existing configuration and `--no-adopt`; a missing remote blocks +without setup/adoption. Host permissions, project restrictions, actor identity, +explicit modes and parent acceptance still apply. Guide/report commands produce +their advertised artifact. This correction is not in the published beta.2 archive; +the unchanged local package version does not identify that published artifact. + Starting with beta.2, the package-owned `oc-beads:status` is removed without an alias. Use `oc-beads:diagnostics` for integration health and `oc-beads:stats` for the issue-database overview via `bd status` (alias `bd stats`). User-defined old status overrides are untouched and are not migrated; the package does not edit configuration. -`oc-beads:compact` guides semantic issue compaction with `bd admin compact`; `bd compact` squashes Dolt history and is a different operation. Neither is conversation compaction. A bare invocation explains the workflow; action requires explicit operation and authority. See the packaged [compact guidance](assets/oc-beads/resources/TROUBLESHOOTING.md) for mode/actor boundaries and upstream help uncertainty. `oc-beads:restore` retrieves pre-compaction issue content, displaying it by default; `--apply` requires explicit authority to write it back and does not mean database backup recovery. Quickstart uses installed help and authorized context; sync guides Dolt-remote synchronization, distinct from `bd federation sync`. +`oc-beads:compact` guides semantic issue compaction with `bd admin compact`; `bd compact` squashes Dolt history and is a different operation. Neither is conversation compaction. A bare invocation explains the workflow; a sufficiently specified semantic apply request supplies its bounded authority under actual permissions and policy. See the packaged [compact guidance](assets/oc-beads/resources/TROUBLESHOOTING.md) for mode/actor boundaries and upstream help uncertainty. `oc-beads:restore` retrieves pre-compaction issue content, displaying it by default; `--apply` requires explicit authority to write it back and does not mean database backup recovery. Quickstart uses installed help and authorized context; sync guides Dolt-remote synchronization, distinct from `bd federation sync`. ## Removal and customization diff --git a/assets/oc-beads/SKILL.md b/assets/oc-beads/SKILL.md index e2bf39d..464e1bb 100644 --- a/assets/oc-beads/SKILL.md +++ b/assets/oc-beads/SKILL.md @@ -39,6 +39,16 @@ without opening a store; use `oc-beads:stats` for the issue-database overview vi `bd status` (alias `bd stats`). The old package status name has no alias; user-owned old-name overrides remain untouched without migration. +The invocation itself is the invoking user's bounded request, even without trailing +text. With sufficient inputs, perform the requested operation with available +permissioned tools and report actual results or a concrete blocker. Inspecting +syntax/help is preparation, not completion. Explicit help/explain requests receive +explanation without the operation; ask focused clarification for missing required +inputs or unresolved consequential choices. Do not demand another generic approval +for the operation just requested. Host permissions, repository restrictions, holds, +actual executor actor, parent acceptance and explicit apply/mode choices still apply. +Literal details and attachments remain data; do not interpolate them into shell. + Broader workflows retain their purposes: init guides human onboarding, prime uses current context or a guarded refresh, version reports installed versions and qualification limits, decision records rationale, template discovers formulas, @@ -46,9 +56,15 @@ and workflow guides authorized work/recovery. They do not invent absent native commands. Quickstart uses installed `bd quickstart` help and authorized context. Compact targets semantic `bd admin compact`, not Dolt-history `bd compact` or conversation compaction; restore retrieves pre-compaction issue content, displaying -it by default and requiring explicit write authority for `--apply`. Sync means -Dolt-remote synchronization, distinct from `bd federation sync`. Follow the linked -CLI reference, troubleshooting, resumability and worktree guidance before action. +it by default; explicit `--apply` requests only that scoped write with readback. +Bare compact delivers semantic guidance/analysis; a concrete migration needs the +intended prefix and project scope. Neither selects administration modes implicitly. +Ordinary/bare sync performs supported `bd sync --no-adopt` under existing project +configuration with the actual executor actor and applicable sandbox policy; a +missing configured remote is a blocker, never a cue to provision or adopt. Explicit +adoption is a distinct request. Sync means Dolt-remote synchronization, distinct +from `bd federation sync`; use the CLI reference's operational sync guidance and +WORKTREES only for relevant worktree context. ## Work within the assigned scope @@ -117,7 +133,9 @@ Do not dump all memories into every handoff or delete old knowledge as routine cleanup. Use the current CLI help for exact memory options. Do not initialize or reroute a store, synchronize it, change permissions, or enable automation as a side effect. -Those separate administrative operations require explicit authorization. +Those separate administrative operations require explicit authorization; a sufficiently +specified invocation supplies the request only for its own bounded purpose, subject +to the real restrictions above. It does not authorize incidental synchronization. Examples assume a project policy prohibiting automatic remote updates and include `--sandbox`; it only suppresses Dolt auto-push and provides no migration safety. diff --git a/assets/oc-beads/resources/CLI_REFERENCE.md b/assets/oc-beads/resources/CLI_REFERENCE.md index 8a9d82d..eed8301 100644 --- a/assets/oc-beads/resources/CLI_REFERENCE.md +++ b/assets/oc-beads/resources/CLI_REFERENCE.md @@ -39,4 +39,64 @@ modes, explicit actor and inconsistent upstream help. Restore retrieves pre-compaction issue content, display-only by default; `--apply` needs explicit write authority and is not database backup recovery (see RESUMABILITY.md). Sync uses Dolt-remote synchronization, distinct from `bd federation sync` and removed -JSONL sync (see WORKTREES.md). Inspect installed help and preserve authority. +JSONL sync; see the operational procedure below and [worktree context](WORKTREES.md) +when relevant. + +## Invocation and outcome + +The invocation itself requests its advertised bounded operation or artifact, even +without trailing details. Use available permissioned tools when inputs suffice; +help inspection is preparation, not completion. Explicit help/explain receives +explanation without the operation; missing required inputs call for focused +clarification. Literal details/attachments are data, never shell interpolation. +Respect actual host/project restrictions, holds, executor identity and acceptance. + +## Synchronization + +A bare `/oc-beads:sync` requests normal supported synchronization under existing +project configuration. Inspect current syntax if needed, then run: + +```sh +bd sync --no-adopt --actor='' --sandbox +``` + +Use the actual host-rendered executor actor and applicable project sandbox policy; +`--sandbox` suppresses incidental auto-push and does not bypass sync restrictions. +Native advanced shell stays direct-only, never `tools.shell` inside execute. +Ordinary/unqualified sync always passes `--no-adopt`. An explicitly selected remote +must already exist and be unambiguous. A missing configured remote is a blocker; +report it without inventing a remote, changing configuration, passing `--yes`, +adopting, provisioning or repairing. Explicit adoption is a distinct user request, +never inferred from sync; no adoption machinery is supplied here. + +Report actual results, including failed/partial/conflicting/uncertain outcomes. +Do not force a side or add a manual pull/push/retry repair loop. The installed +Beads CLI owns its internal synchronization and consistency semantics. Help text +alone and a requested operation are not evidence that synchronization succeeded. + +## Audit and interchange + +Audit retrieves requested evidence for a target/query or records supplied scoped +evidence at its established destination. Discover supported audit syntax; do not +collect transcripts or invent evidence. Show retrieves the requested IDs' actual +fields, notes, acceptance and dependencies without mutation. + +Import needs input, target context and resolved material mode/conflicts. Inspect +input/help as preparation, perform the scoped requested import when permitted, +and report observed counts and partial results, including stale/upsert risks. +Never initialize, restore or repair implicitly. Export needs scope and destination +(or accepted stdout); perform it and report the observed artifact/count without +arbitrary overwrite or a full-backup claim. See [troubleshooting](TROUBLESHOOTING.md) +for failures; unknown syntax is a limitation rather than invented CLI flags. + +## Onboarding and discovery + +Init and quickstart deliver a usable human-directed guide with current installed +help, relevant project context and concrete next steps/side effects. They do not +initialize a store automatically. Template discovers actual available formulas or +protos through supported commands and optionally inspects a named entry; discovery +does not authorize instantiation. Report actual entries or unavailability. +Decision persists supplied rationale/alternatives in the established project-owned +destination; clarify only if it cannot be resolved, and do not invent a native +command or automatically create a new issue/spec/document. Bare workflow delivers +a procedure; task execution needs an already authorized assignment or batch. diff --git a/assets/oc-beads/resources/TROUBLESHOOTING.md b/assets/oc-beads/resources/TROUBLESHOOTING.md index 72741fc..36a8758 100644 --- a/assets/oc-beads/resources/TROUBLESHOOTING.md +++ b/assets/oc-beads/resources/TROUBLESHOOTING.md @@ -23,9 +23,11 @@ inspected CLI; see [AGENTS.md](AGENTS.md). `oc-beads:compact` guides semantic issue compaction with `bd admin compact`. `bd compact` squashes Dolt history and is a different operation; neither means -conversation compaction. A bare invocation explains the workflow, not authority -to act. Clarify the operation and scope when a request is ambiguous, and inspect -applicable installed help before any explicitly authorized action. +conversation compaction. A bare invocation delivers a useful semantic guide or +analysis artifact. A sufficiently specified semantic apply request supplies its +bounded authority and does not need another generic approval. Clarify missing +scope, targets or consequential choices; preserve actual host/project restrictions +and inspect applicable installed help before action. Prefer the agent-driven analyze/apply path. `--auto` sends issue content to an external AI provider; `--dolt` performs storage garbage collection rather than @@ -69,3 +71,16 @@ owns it or the claim was reclaimed, stop writes and coordinate a deliberate handoff. Never force-reassign yourself or fall back to the human Git identity. Record unresolved acceptance, missing evidence, and the next authorized action in the handoff. + +## Deletion and identifier migration + +A sufficiently specified deletion invocation requests that bounded deletion. +Inspect target/effects and clarify unresolved destructive impact, then perform +only the requested deletion when policy and permissions permit. Do not replace +closure with deletion or silently expand cascades. + +Bare rename-prefix delivers the advertised migration/reference-impact explanation. +A concrete migration requires a desired prefix and project scope; a fully scoped +migration request supplies its bounded authority without another generic approval. +Do not infer a prefix, migration or collateral rewrites. Real restrictions and +missing inputs still block; the invocation never bypasses permission or a hold. diff --git a/assets/oc-beads/resources/WORKTREES.md b/assets/oc-beads/resources/WORKTREES.md index d4db2ae..a75006f 100644 --- a/assets/oc-beads/resources/WORKTREES.md +++ b/assets/oc-beads/resources/WORKTREES.md @@ -18,7 +18,9 @@ safety checks. Inspect local changes before removal, preserve work that is not yours, and remove only a worktree whose cleanup is authorized. This resource does not create or clean up a worktree automatically. -`oc-beads:sync` guides `bd sync` Dolt-remote synchronization, distinct from -`bd federation sync` and removed JSONL sync. Inspect current help and synchronize -only with explicit authority. Report conflicts without forcing a side; the -installed Beads CLI owns synchronization and consistency semantics. +`oc-beads:sync` requests supported Dolt-remote synchronization, distinct from +`bd federation sync` and removed JSONL sync. Follow the focused +[synchronization procedure](CLI_REFERENCE.md#synchronization) for --no-adopt, +existing configuration, actor, permissions and honest outcomes. This resource is +secondary worktree context; the installed Beads CLI owns synchronization and +consistency semantics. diff --git a/docs/command-action-evaluation.md b/docs/command-action-evaluation.md new file mode 100644 index 0000000..b95c818 --- /dev/null +++ b/docs/command-action-evaluation.md @@ -0,0 +1,210 @@ +# Command action correction: bounded evidence + +## Current status + +**Parent accepted the source and bounded behavioral evidence.** The corrected +R1–R5 evaluation produced one valid sample per case, and the parent checked all +five task markers after independent verification. Publication remains unauthorized. + +The first R1 was invalid because a harness false positive rejected `--no-adopt` +before execution; it is neither a pass nor a product failure. The historical +first-attempt status below is superseded by the corrected evaluation and parent +acceptance. Its byte-for-byte original is retained as +`evaluation-corrected/report-original.md` under the raw evidence root. + +## Superseded first attempt: invalid harness rejection + +At the first handoff, source checks passed but semantic acceptance was unverified: +the harness rejected R1 before execution, and R2–R5 had not run. The following +first-attempt sections preserve that historical state, not the current acceptance. + +## Candidate and source evidence + +Baseline: `de2443c2624950dfdda7fdcf98f71d2bad1d3ad3`, branch +`fix/command-action-wzk`, executor `codex:oc-actions-sol`, Bead +`opencode-beads-wzk`. Parent owns verification/acceptance; the Bead remains +in progress and OpenSpec acceptance markers remain unchecked. + +The local source archive retains version `1.1.0-beta.2` but is **not the published +beta.2 archive**. Its SHA-256 is +`bbf302250f6e71878101a458ca2bcad4b18761eb501f8e9faad43500288234c6`. +The owned native host installed that archive through normal plugin configuration +and loaded its public `@snarkipus/opencode-beads/src/plugin.ts` entrypoint without +wrapper or dependency injection. Every installed archive file matched; native +registration exposed 30 commands and the installed skill retained 17 links. +A separate read-only observer captured native hooks/provider requests and tool +selection; it changed no command, model response, prompt or permission decision. + +Raw evidence root: +`/opt/data/cache/scratch/oc-beads-command-action-implementation/`. +The `evaluation/installed-verification.json` file records the exact installed path. + +| Source check | Observed result | +| --- | --- | +| RED/GREEN invocation and real callback slice | 2 expected failures, then 66 tests passed | +| RED/GREEN purpose/resource/authority/docs slice | 4 expected failures, then 91 focused tests passed | +| Typecheck | Passed | +| Full `bun test` | 205 passed, 0 failed | +| Installed package smoke | Passed, including bare sync/explain callbacks and literal native metadata | +| Named/global strict OpenSpec | Passed, 4 total change/spec items | +| Protected source hashes | All 153 matched | + +Logs are in `logs/`; these deterministic checks verify contracts and forwarding, +not genuine model intent or successful remote synchronization. + +## First and only R1 sample + +The exact retained runtime reported OpenCode `2.1.1`; its SHA-256 is +`4595933989548a452e920c971d5931898d7d64e73e039f777ed62c84a18916c9`. +Beads reported `1.3.1 (c1c4b642a: HEAD@c1c4b642ac1c)`. +The genuine native configuration was `openai/gpt-6.1-sol/high`, with observed +provider route `https://chatgpt.com/backend-api/codex`. There was no controlled +provider. Session: `ses_e9ea40308ffeh7DtkDhK6EoHht`; host-rendered actor: +`opencode:action_eval:f071722b7d81`. + +Harness setup created isolated HOME/XDG/store/local-file remote and two replicas, +then seeded unrelated base issue `act-6hl`, local-only issue `act-eon` and +remote-only issue `act-b6x`. Setup/probe writes were separately authorized harness +operations, not product provisioning. The local store and remote genuinely differed +before the bare command; no real project issue database or remote was used. + +The native command endpoint received `name: oc-beads:sync`, empty text and queued +delivery. The submitted prompt retained the invoked name and requested outcome. +The model loaded the packaged skill, discovered the native namespace, read the +focused CLI reference and inspected `bd sync --help`, then selected direct shell: + +```sh +bd sync --no-adopt --actor='opencode:action_eval:f071722b7d81' --sandbox --json +``` + +Its selected cwd was the disposable `evaluation/repo` directory. The real host +permission request reached the harness. The harness's forbidden-word regex matched +`adopt` inside `--no-adopt`, incorrectly replying `reject`. Native denial then +prevented execution and the assistant step ended interrupted, without a final +outcome response. The logging CLI wrapper recorded no actual sync invocation. +This is a harness false positive, not evidence of missing invocation authority, +a broken upstream sync or successful permissioned convergence. + +Before/after issue state, unrelated sentinel files and configured remote were +unchanged. Local readback still contained only the base/local issues; a harness +peer pull/readback still contained only the base/remote issues. Convergence was +not achieved. `evaluation/semantic-result.json`, `permissions.jsonl`, +`R1-tool-selection.json`, `R1-bd-calls.json`, `R1-before.json`, `R1-after.json` and +`R1-peer-readback.json` preserve those outcomes. `R1-command-supplied-prompt.json`, +`R1-model-input.json`, `model-provenance.json` and native traces distinguish the +command prompt from actual model requests and chosen tools. + +## Stop, cleanup and limits + +R2 sync explain, R3 missing-input update, R4 denied sync and R5 bare compact guide +were **not executed** after the first R1 failure. This run proves genuine selection +of the intended action, but does not satisfy the five-case semantic gate. Parent +disposition is required before any corrected-harness evaluation; no rerun is +claimed or implied. + +The supported credential API imported current active native access only into the +isolated host, with an empty noncredential refresh field. No source refresh value +was read, no account refresh/rotation occurred, and no source credential database +was written. The owned foreground host exited, its listener closed, and transient +credential-bearing runtime state was removed. No current-access string remains in +retained evaluation files; operator config/runtime and selected auth fingerprints +matched before/after. See `evaluation/cleanup.json` and operator fingerprint files. + +No commit, push, tracker sync/closure, archive, version change, release, extra agent, +operator service restart or production path expansion occurred. Evidence is bounded +to this source candidate and one interrupted sample on the exact host/model above; +there is no new universal, reliability or other-host qualification claim. + +## Parent-authorized corrected-harness evaluation + +The original interrupted observation above and its `evaluation/` evidence remain +unchanged. Parent explicitly authorized correcting the disposable harness false +positive and making **one valid R1–R5 evaluation**, with no integration/source/ +guidance/prompt changes. The corrected evidence is separate, under +`/opt/data/cache/scratch/oc-beads-command-action-implementation/evaluation-corrected/`. +The five valid samples passed the bounded evidence review; parent acceptance is +still pending. The total history is one invalid interrupted R1 selection plus +one corrected valid R1 execution, followed by one sample each of R2–R5. + +Before model use, `rule-red-old.log` reproduced the old responder's rejection of +the intended command as an expected assertion failure. `rule-green-corrected.log` +passed four deterministic tests: exact no-adopt sync with actual actor/sandbox +was allowed, while adoption flags, administration, unrelated writes, actor +substitution, shell substitution/redirection and compound commands were rejected. +The small fixture tokenizes only enumerated command shapes; it is not a general +permission interpreter. R4 receives no shell override, and actual native deny +rules remain controlling. No product prompt or permission implementation changed. + +The exact candidate SHA-256 remained +`bbf302250f6e71878101a458ca2bcad4b18761eb501f8e9faad43500288234c6` before and after. +The corrected isolated host installed an identical copy of the frozen archive +through its normal public entrypoint, without wrapper/DI; every installed and +packaged source file matched. The retained OpenCode `2.1.1` binary, Beads `1.3.1` +binary and genuine native `openai/gpt-6.1-sol/high` account route were unchanged. +Observed provider route remained `https://chatgpt.com/backend-api/codex`. +There were zero native retry events and no model reruns or fallback executor. + +| Valid sample | Session | Observed outcome | +| --- | --- | --- | +| R1 bare sync | `ses_e9e9bb268ffeUO5mWahu6487kM` | Actual normal CLI sync succeeded; local and remote readback converged; unrelated state unchanged | +| R2 sync explain | `ses_e9e9b6621ffemn5UmE8K524DAN` | Explained the workflow and explicitly reported no sync attempt; no mutation | +| R3 bare update | `ses_e9e9b213fffeJ7m4wJcIqgbosS` | Asked which issue and which fields/notes to change; zero writes | +| R4 bare sync, native shell/execute denied | `ses_e9e9af009ffeRKlZ6uNhMIs1Ii` | Reported blocked capability honestly; no sync or bypass | +| R5 bare compact | `ses_e9e9acec8ffefvgm8SacRSisV1` | Delivered semantic-compaction guidance with mode/actor/recovery limits; no administration mutation | + +R1 ran exactly: + +```sh +bd sync --no-adopt --actor=opencode:action_eval:6f98120839e0 --sandbox --json +``` + +Its actual cwd was `evaluation-corrected/repo`. Native permission requested this +command and received `once`. The real CLI returned exit 0, `status: ok`, +`attempts: 1`, `pulled: true`, `pushed: true`, and `rows_corrected: 0`. +Harness setup had seeded base issue `act-3bm`, local-only `act-adl` and remote-only +`act-lxq` against an existing local disposable file remote. After the selected +sync, local readback and a separately authorized harness peer pull/readback both +contained all three IDs. The unrelated base issue, sentinel files, Git status +and configured remote were unchanged. The harness peer pull was a readback probe +after product success, not a product repair/retry loop. + +R2–R5 each preserved before/after issue, file, remote and Git state exactly. +Their CLI traces contained only ordinary context/version/prime probes, plus +`bd admin compact --help` for R5. No issue-write, sync, initialization, compact +application or other administrative command ran. The actual R4 model requests +contained neither `shell` nor `execute` in their native tool inventories, and the +model selected neither; no permission responder overrode a deny. Normal host +context probes remained visible and were not misreported as absent. +R5's analysis/apply examples were explanatory text and were not executed. + +`semantic-evidence-review.json` records the response review, actual tool choices, +model route, inventories, permission decisions and before/after comparisons. +Per-case `R*-command-supplied-prompt.json`, `R*-model-input.json`, +`R*-tool-selection.json`, `R*-bd-calls.json`, `R*-response.json` and state files +retain the distinction between command prompt, genuine model selection, actual +argv/outcome and readback. `installed-verification.json` records the exact public +installed entrypoint. Script PASS was checked against these observations rather +than treated as the acceptance decision. + +Cleanup verification found the owned foreground host exited, its listener closed, +no owned processes remaining, transient credential-capable state removed, and no +current-access string in retained corrected evidence. The supported isolated +credential import carried current access only, with no refresh capability; +operator config/runtime and selected source-auth fingerprints remained unchanged. +`cleanup-verification.json` records these checks. + +All 172 frozen repository file hashes matched before this sole permitted report +append. The archive, installed content, original interrupted evaluation and prior +handoff hashes also matched. The parent's live `harness-correction-worker.log` +records this correction session and was separately identified as externally +updated; it is not original interrupted-run evidence. Historical raw evidence and +prior handoffs were not overwritten or relabeled. The original report is retained +byte-for-byte as the prefix of this file and in `report-original.md`. + +No source qualification was repeated; the parent's independent source checks are +reused. No integration/source/guidance/test/spec/task acceptance marker changed. +No commit, push, project tracker sync/closure, archive, version/release, owner +store/runtime/auth mutation or extra agent occurred. Evidence remains limited to +these five single samples on the exact frozen host/model/candidate; it establishes +no universal, reliability or other-host qualification. Parent independent evidence +acceptance remains the next gate. diff --git a/docs/reviews/opus-command-action-source-recheck-wzk.md b/docs/reviews/opus-command-action-source-recheck-wzk.md new file mode 100644 index 0000000..3104fbd --- /dev/null +++ b/docs/reviews/opus-command-action-source-recheck-wzk.md @@ -0,0 +1,30 @@ +# Opus command-action implementation review — corrected READY + +Baseline: `de2443c2624950dfdda7fdcf98f71d2bad1d3ad3`. Reviewer: actual Claude Opus 5.5, medium requested; session `8571889e-f5be-4cbe-9a69-7ce2c72ab257`. Parent verified completed/no-error/no-permission-denial result and frozen candidate identities. Review inspection is separate from parent-run 205 tests and the five bounded real-model samples. No publication or runtime authority is conferred. + +Only `docs/command-action-evaluation.md` and the active change task introduction changed after the original review. All other 17 reviewed files were byte-identical. Parent verified the corrected manifest. Canonical archive synchronization and these evidence-only review files are subsequent closeout work, not runtime changes. + +--- + +**Verdict: READY.** Both documentation findings on the `fix/command-action-wzk` candidate are resolved, and the fix doesn't introduce a contradiction that would change the decision. I didn't recheck the corrected-manifest hashes. + +## Spec +- **Finding 1 is resolved.** `docs/command-action-evaluation.md` now opens with "Current status" (lines 3–13). That section says: + - parent accepted the source and the bounded evidence; + - all five task markers were checked after independent verification; + - publication remains unauthorized; + - the first R1 was invalid because of a harness false positive, and was neither a pass nor a product failure; + - the original copy is kept at `report-original.md`. +- Lines 15–19 label the first-attempt sections as superseded history. That covers the old "unverified", "markers remain unchecked" and "not executed" statements at lines 17, 26 and 100. +- **Finding 2 is resolved.** `tasks.md:3` now matches the `[x]` markers and keeps publication and closure as separate gates. + +## Standards/Proportionality +- The correction only touches documentation. There is no change to source, the model prompt or the evidence, and no re-evaluation. That fits a finding that was only about documentation. + +## Not blocking +- Two statements outside the superseded section still say acceptance is pending: + - **Lines 125–126:** "parent acceptance is still pending" + - **Line 210:** "Parent independent evidence acceptance remains the next gate" +- Both were accurate when the worker handed off, and the Current status section at the top takes precedence. Adding "(at worker handoff; see Current status)" to each would remove the remaining ambiguity. + +This READY applies only to whether this source candidate is ready. It isn't new host/model qualification, a reliability claim, or approval to commit, publish, activate or close. \ No newline at end of file diff --git a/docs/reviews/opus-command-action-source-wzk.md b/docs/reviews/opus-command-action-source-wzk.md new file mode 100644 index 0000000..cc0a619 --- /dev/null +++ b/docs/reviews/opus-command-action-source-wzk.md @@ -0,0 +1,58 @@ +# Opus command-action implementation review — original REVISE + +Baseline: `de2443c2624950dfdda7fdcf98f71d2bad1d3ad3`. Reviewer: actual Claude Opus 5.5, medium requested; session `8571889e-f5be-4cbe-9a69-7ce2c72ab257`. Parent verified completed/no-error/no-permission-denial result and frozen candidate identities. Review inspection is separate from parent-run 205 tests and the five bounded real-model samples. No publication or runtime authority is conferred. + +Reviewed tracked-plus-new diff SHA-256: `0ea3ba41e4492fbbe29bc261778656d27ded1785b0af1f1f905c762e7ead339a`. The report below is retained verbatim; its documentation findings were subsequently corrected and independently rechecked. + +--- + +**Verdict for this candidate: REVISE, for documentation honesty only.** The candidate is the uncommitted `fix/command-action-wzk` branch on baseline `de2443c`: the 19-path manifest, `candidate.diff`, and installed archive `bbf30225…`. Source, guidance, tests, the spec delta and the evaluation evidence all meet the accepted plan and Matt's intent. Two committed docs state an acceptance status that the rest of the candidate contradicts. Neither fix needs a source change, test change or re-evaluation. My earlier plan verdicts stand: the first review was REVISE with F1–F3, and the recheck was READY. + +## Spec/Behavior + +**Material findings** + +1. **The evaluation report opens with an outdated status** (`docs/command-action-evaluation.md`, diff lines 487–490, 497, 570–574). Its first lines still say "Semantic acceptance remains **unverified**… No… R2–R5 sample followed" and "OpenSpec acceptance markers remain unchecked." The corrected R1–R5 results only appear after line 589. + - **Consequence:** anyone reading this committed doc from the top gets the wrong current status. That conflicts with `tasks.md` (all `[x]`) and with `parent-acceptance.json`, which accepts R1–R5. + - **Smallest fix:** add a 2–3 line current-status header. It should say: + - the first R1 was invalid, caused by a harness false positive; + - the one corrected R1–R5 run gave valid single samples; + - parent accepted the evidence, and release is not authorized. + - Retitle the original section "Superseded first attempt: invalid harness rejection." `report-original.md` already keeps the byte-for-byte copy, so the committed doc doesn't need to lead with outdated status. +2. **`tasks.md` contradicts itself** (diff line 877). The prose says "all acceptance markers remain unchecked until parent verification", but every box is `[x]`. + - **Fix:** reword it to say parent checked the markers after independent verification. + +**Checked and correct** +- **Rendering:** `src/workflows.ts` puts `Invoked command` and `Requested outcome` first. `Literal user details` appears only when text is present, so bare invocations no longer end in an empty `User request:` label. There is no parser or executor. The `diagnostics` command is unchanged. +- **F1 authority wording:** the sync, delete, import, restore, rename-prefix and compact purpose strings and `guidance.ts:37` are reconciled. Restore `--apply`, compact `--auto`/`--dolt` plus the explicit `--actor`, the concrete rename prefix, and parent acceptance are all kept. No admin action is quietly broadened. +- **F2 `--no-adopt`:** it is unconditional in the sync purpose, in CLI_REFERENCE's Synchronization section, in SKILL.md and in the spec delta. A missing remote is a blocker. +- **Resources:** all seven remaps match the plan. CLI_REFERENCE gets concise sections. WORKTREES is now a secondary link and no longer contradicts the sync guidance. The other mappings are unchanged, with 30 names and 17 links. +- **Spec delta:** the three MODIFIED requirements carry their full original scenarios plus additive ones, consistent with canonical compact/restore. +- **README and CHANGELOG:** both clearly separate unreleased source behavior from the published beta.2 archive. +- **Evidence:** + - `R1-bd-calls.json` shows exactly one `sync --no-adopt --actor=… --sandbox --json` call, exit 0, `pulled`/`pushed`, after help was inspected as a preparation step. + - R2 explained and stated that no sync was attempted. + - R3 asked for the missing issue and fields, with no writes. + - The invalid first R1 is labeled honestly and is not counted as either a pass or a product failure. + +## Standards/Proportionality +- No machinery was added. The tests check the changed contracts: every stem renders correctly whether details are empty, help text, or hostile-looking text; resources are pinned; and the installed package callbacks check bare and explain sync. The tests explicitly say fixtures don't prove model behavior. Changing the purpose check from `toBe` to `toContain` is acceptable because the full purpose is asserted through `startsWith`. +- Adding `tests/guidance.test.ts`, outside the planned test paths, is justified by the `guidance.ts` change. + +## Optional observations (not blocking) +- **Model resolved a precedence question:** in R1, `bd prime` said "local-only/no-remote… no push, pull, or remote sync". That was detected from the missing Git remote, even though the context showed a configured Dolt remote. The model chose to sync anyway. Treating the explicit invocation as taking priority matches AGENTS.md, but this was the model's judgment on a single sample, not something the guidance spells out. A deliberate project-level no-sync policy still depends on the model honoring it. +- **Actor wording:** the spec delta (line 827) says "actor identity… remain controlling". On the direct-shell path, actor attribution is guidance; only typed tools derive it deterministically. Consider adding "(host-enforced where applicable)". +- **Ambiguous sentence:** in SKILL.md (diff line 72), "a concrete migration needs the intended prefix" doesn't name rename-prefix and sits next to compact text. +- **Long descriptions:** purposes double as command descriptions, and the sync description is now about 480 characters in the picker. +- **R4 scope:** R4 tested capability that was absent from the tool inventory, not a deny issued mid-flow. Existing deterministic tests cover typed denials. +- **Scratch paths:** the evaluation doc points to scratch paths that won't last. + +## What I inspected vs. what parent ran +- **Inspected (read-only):** + - `candidate.diff` in full, including the new docs and OpenSpec files + - `manifest.json` + - baseline `src/workflows.ts`, `guidance.ts`, SKILL.md and the canonical spec + - `R1-bd-calls.json`, the R2 and R3 responses, and `parent-acceptance.json` +- **Not verified by me:** hashes, the 205 tests, typecheck, package smoke, OpenSpec validation, whitespace checks, and the R4/R5/cleanup raw files. + +READY after these two doc fixes would cover this candidate only. It is not new host/model qualification, a reliability claim, or approval to commit, publish, activate or close. \ No newline at end of file diff --git a/openspec/changes/archive/2026-10-22-execute-command-intent/.openspec.yaml b/openspec/changes/archive/2026-10-22-execute-command-intent/.openspec.yaml new file mode 100644 index 0000000..7cc41bb --- /dev/null +++ b/openspec/changes/archive/2026-10-22-execute-command-intent/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-22 diff --git a/openspec/changes/archive/2026-10-22-execute-command-intent/design.md b/openspec/changes/archive/2026-10-22-execute-command-intent/design.md new file mode 100644 index 0000000..69c1c9d --- /dev/null +++ b/openspec/changes/archive/2026-10-22-execute-command-intent/design.md @@ -0,0 +1,25 @@ +# Design + +## Context + +See proposal.md for the failure. Ordinary native callbacks forward to session.prompt; the current purpose-first text leaves the bare invocation implicit. Diagnostics already obtains an observed report and stays intact. Owner accepted F1 invocation authority, F2 unconditional no-adopt for ordinary sync and F3 bounded validation in the operative Bead. + +## Goals / Non-Goals + +Expose invocation and requested outcome directly while retaining native metadata, overrides, disposal, permissions and actual executor identity. Preserve 30 names and 17 links. No keyword intent parser, hidden authority token, deterministic executor, manager/router, raw plugin spawn or shell interpolation. No upstream repair or routing/confinement framework. + +## Decisions + +- Keep prompt-first callbacks: render invoked name and outcome before optional literal details; instruct contextual interpretation of explicit help/explain, focused missing-input clarification and meaningful guide/report artifacts. Help inspection prepares action rather than completing it. A special sync executor would expand responsibilities and is excluded. +- Rewrite sync/delete/import/restore/rename-prefix/compact authority clauses as well as common text and the shared incidental-sync restriction. Explicit invocation requests only its bounded purpose; actual host/repository restrictions, holds, parent acceptance, restore --apply, compact modes, concrete migration prefix and no unrelated writes still apply. +- Ordinary sync uses existing project configuration and supported --no-adopt, actual executor actor and applicable sandbox policy. Missing remote is a blocker; no --yes, adoption/provisioning, manual pull/push repair loops or force resolution. Explicit adoption is a distinct request; no machinery is added. +- Remap sync/audit/show/import/init/quickstart to CLI_REFERENCE and epic to DEPENDENCIES. Keep WORKTREES secondary and CLI_REFERENCE concise. Preserve onboarding and bare compact/migration explanation purposes. +- Use small RED/GREEN rendering, purpose/resource and actual callback slices, retaining logs. Reuse existing guard/actor/permission/result tests. Fixtures establish contracts, never genuine model intent. + +## Risks / Trade-offs + +Prompt interpretation remains model-dependent → record one genuine named configuration on one exact admitted host. R1 bare sync must converge seeded nonconflicting divergence on a local disposable remote with --no-adopt/actor; R2 explain makes no sync; R3 missing update inputs clarifies with zero writes; R4 denied sync blocks/pends without bypass; R5 bare compact or init gives a guide without admin/store mutation. Preserve first R1 failure and stop semantic remediation; no retry-until-pass or executor fallback. Missing runtime/current native access leaves semantic acceptance unexecuted while source work continues. + +## Migration Plan + +Validate this packet before runtime edits. Implement allowed files, run focused/full/type/package and named/global strict checks, then return source and semantic evidence separately for parent verification. Use normal public installed entrypoint and record distinct local archive checksum despite unchanged beta.2 version. Evaluation owns transient HOME/XDG/store/remote/server and current-access-only credential import; no refresh capability or operator writes. Clean owned processes/listeners/credentials and verify nonsecret operator fingerprints. No commits, release, archive, closure or tracker sync. Rollback is reverting the bounded uncommitted changes. diff --git a/openspec/changes/archive/2026-10-22-execute-command-intent/proposal.md b/openspec/changes/archive/2026-10-22-execute-command-intent/proposal.md new file mode 100644 index 0000000..6c78fa3 --- /dev/null +++ b/openspec/changes/archive/2026-10-22-execute-command-intent/proposal.md @@ -0,0 +1,26 @@ +# Proposal + +## Why + +A bare `/oc-beads:sync` returned help without attempting synchronization. The accepted correction makes the invoked workflow itself a bounded user request, including when no trailing details are supplied. + +## What Changes + +- Put invoked name and requested outcome before optional literal details in native prompts. +- Reconcile affected purpose and guidance authority clauses; retain real permissions, holds, inputs, modes, actor attribution and parent acceptance. +- Make ordinary sync use supported `bd sync --no-adopt` with existing configuration and honest outcomes; add concise operational guidance and seven approved primary resource remaps. +- Verify deterministic contracts and one admitted host/one genuine model through five disposable single-sample cases, reporting source and semantic gates separately. + +## Capabilities + +### New Capabilities + +None. + +### Modified Capabilities + +- `workflow-access`: bare invocation, sufficient-input action outcomes, explanation/input exceptions and bounded invocation authority. + +## Impact + +Only workflows/shared authority wording, selected packaged guidance, associated tests/package smoke, brief README/Unreleased notes and this packet. No executor, parser, host/runner/guard changes, adoption machinery, admission changes, version bump or historical spec edits. Beads `opencode-beads-wzk` owns progress and parent acceptance. diff --git a/openspec/changes/archive/2026-10-22-execute-command-intent/specs/workflow-access/spec.md b/openspec/changes/archive/2026-10-22-execute-command-intent/specs/workflow-access/spec.md new file mode 100644 index 0000000..f5d6750 --- /dev/null +++ b/openspec/changes/archive/2026-10-22-execute-command-intent/specs/workflow-access/spec.md @@ -0,0 +1,105 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: Discoverable selected workflows + +The package-owned `oc-beads` skill, all 15 corpus resources plus CODE_MODE and ADR rationale and all 29 `oc-beads:` entries plus `oc-beads:diagnostics` (including documented replacements) SHALL have a documented native entry point that exposes its purpose and relevant supporting guidance. Advertised command and skill behavior SHALL match the installed implementation and available tools rather than assume absent MCP tools or unreachable resources. + +#### Scenario: User invokes a selected command + +- **WHEN** a user discovers and invokes an installed selected command with or without trailing details +- **THEN** the advertised workflow receives the invoked name, requested outcome and any literal details through its documented native entry point +- **AND** uses available execution tools without inventing a Beads MCP tool + +#### Scenario: Task requires deeper guidance + +- **WHEN** a selected workflow directs an agent to a supporting resource +- **THEN** that resource is reachable from the installed guidance's documented base +- **AND** SKILL.md explicitly links all 15 corpus resources plus CODE_MODE and ADR rather than relying on the host’s ten-file auto-listing +- **AND** its presence alone is not reported as evidence that the model used it + +#### Scenario: Installed resource requires external access + +- **WHEN** an installed resource outside the workspace encounters external-directory ask or deny +- **THEN** the integration respects approval/rejection and reports unreachable guidance honestly without bypassing permission + +#### Scenario: Package diagnostic name is replaced + +- **WHEN** the package registers its command surface +- **THEN** exactly 30 package commands include the original 29 workflow stems and `oc-beads:diagnostics`, with `stats` retained and no package-owned `oc-beads:status` alias +- **AND** documentation directs integration-health users to diagnostics and issue-overview users to stats; user-owned old-name overrides remain untouched without configuration migration + +#### Scenario: Workflow purpose differs from native argv + +- **WHEN** a user invokes a selected workflow +- **THEN** guidance explains that workflow prompts guide permitted operations rather than act as exact CLI aliases, including broader init, prime, version, decision, template and workflow purposes +- **AND** quickstart uses neutral installed-help wording without an unsupported deprecation claim, and sync distinguishes Dolt-remote synchronization from `bd federation sync` and removed JSONL sync + +#### Scenario: Bare invocation retains the request + +- **WHEN** a user invokes a command without trailing details +- **THEN** the command name and advertised bounded operation or artifact remain the user request +- **AND** supporting guidance addresses that workflow rather than only syntax discovery + +### Requirement: Coherent context and authority + +The integration SHALL preserve applicable user and repository authority across injected workflow, skills, commands and delegated guidance. It SHALL distinguish missing or failed context from context withheld by an explicit hold, and SHALL NOT recommend bypassing a hold through manual fallback. + +#### Scenario: Migration hold conflicts with prime-first advice + +- **WHEN** workflow context is withheld because store access is not authorized +- **THEN** skill, command and worker recovery guidance preserves that restriction +- **AND** reports the reason and required owner action without opening the store + +#### Scenario: Context is already available + +- **WHEN** current applicable workflow context has already been supplied +- **THEN** discovery guidance does not require another prime solely because the skill was loaded +- **AND** distinct applicable local constraints remain available when duplicate guidance is reduced + +#### Scenario: Explicit invocation and incidental automation + +- **WHEN** a user invokes a sufficiently specified workflow +- **THEN** the invocation carries that invoking user's authority for its bounded purpose without redundant generic authorization +- **AND** actual host permissions, repository restrictions, holds, actor identity, parent acceptance and required inputs or explicit modes remain controlling +- **AND** unrelated writes, incidental synchronization and inferred remote adoption remain unauthorized + +### Requirement: Scope-preserving execution and visible failure + +Selected workflows SHALL preserve the user's requested execution scope, distinguish inspection from mutation, and report unsuccessful or partial operations accurately. Optional extensions SHALL expose their scope and constraints without silently replacing base workflows or authorizing unrelated actions. + +#### Scenario: Graph analysis is read-only + +- **WHEN** the user requests an issue-graph overview without authorizing task execution +- **THEN** the workflow returns the analysis without claiming, editing or closing issues + +#### Scenario: Single atomic operation + +- **WHEN** the user authorizes one issue operation +- **THEN** the workflow completes or reports failure of that operation without automatically starting unrelated ready work + +#### Scenario: Optional worker limit interrupts work + +- **WHEN** a selected bounded worker or permission constraint stops before completion +- **THEN** the result identifies the incomplete work, relevant context and next action +- **AND** does not claim that the task or durable write succeeded + +#### Scenario: Sufficient inputs request an action + +- **WHEN** an action workflow has the required inputs and available permissioned capabilities +- **THEN** it performs the requested operation and reports actual results or an identified blocker +- **AND** help inspection alone does not complete the action + +#### Scenario: Explanation or missing required inputs + +- **WHEN** the user explicitly requests help/explanation or required action inputs are missing +- **THEN** it explains without performing the advertised mutation or asks focused clarification for the missing inputs respectively +- **AND** advertised guide/report workflows deliver their useful artifact, including bare compact or init without administration/store initialization + +#### Scenario: Bare synchronization with existing configuration + +- **WHEN** the user invokes ordinary or bare sync +- **THEN** it attempts supported bd sync --no-adopt under existing project configuration, actual executor actor and applicable sandbox policy +- **AND** a missing configured remote or denied permission is reported honestly without adoption, provisioning, --yes, force resolution, unrelated writes or manual pull/push repair loops +- **AND** explicit adoption remains a distinct request never inferred from synchronization diff --git a/openspec/changes/archive/2026-10-22-execute-command-intent/tasks.md b/openspec/changes/archive/2026-10-22-execute-command-intent/tasks.md new file mode 100644 index 0000000..2508f77 --- /dev/null +++ b/openspec/changes/archive/2026-10-22-execute-command-intent/tasks.md @@ -0,0 +1,14 @@ +# Tasks + +Progress and evidence live in `opencode-beads-wzk`. The parent checked these acceptance markers after independent source and bounded behavioral-evidence verification; worker readiness alone did not complete them. Publication and closure remain separately gated. + +## 1. Invocation contract + +- [x] 1.1 Render invoked name/outcome on bare and detailed calls, preserve literal text/files/native metadata and real callback behavior; retain RED/GREEN logs and focused workflows/host checks. +- [x] 1.2 Reconcile affected purpose/shared authority clauses and seven resource remaps; verify purpose/resource tests and 30 names/17 links with corresponding packaged operational guidance. +- [x] 1.3 Document source-only invocation/action/help behavior separately from published beta.2 and add factual Unreleased notes; verify docs and installed package callback assertions. + +## 2. Bounded evaluation and integration + +- [x] 2.1 Record one genuine named model/configuration on one exact admitted host, five single-sample disposable cases R1–R5 and exact archive/entrypoint/permission/tool/state evidence; preserve first R1 failure or exact prerequisite blocker and cleanup evidence. +- [x] 2.2 Run focused tests, typecheck, full bun test, package smoke, named/global strict OpenSpec validation and diff hygiene including new files; verify protected hashes and provide separate source/semantic parent handoff. diff --git a/openspec/specs/workflow-access/spec.md b/openspec/specs/workflow-access/spec.md index d0c8155..f18fc7e 100644 --- a/openspec/specs/workflow-access/spec.md +++ b/openspec/specs/workflow-access/spec.md @@ -13,8 +13,8 @@ The package-owned `oc-beads` skill, all 15 corpus resources plus CODE_MODE and A #### Scenario: User invokes a selected command -- **WHEN** a user discovers and invokes an installed selected command with arguments -- **THEN** the advertised workflow receives the intended arguments through its documented native entry point +- **WHEN** a user discovers and invokes an installed selected command with or without trailing details +- **THEN** the advertised workflow receives the invoked name, requested outcome and any literal details through its documented native entry point - **AND** uses available execution tools without inventing a Beads MCP tool #### Scenario: Task requires deeper guidance @@ -41,6 +41,12 @@ The package-owned `oc-beads` skill, all 15 corpus resources plus CODE_MODE and A - **THEN** guidance explains that workflow prompts guide permitted operations rather than act as exact CLI aliases, including broader init, prime, version, decision, template and workflow purposes - **AND** quickstart uses neutral installed-help wording without an unsupported deprecation claim, and sync distinguishes Dolt-remote synchronization from `bd federation sync` and removed JSONL sync +#### Scenario: Bare invocation retains the request + +- **WHEN** a user invokes a command without trailing details +- **THEN** the command name and advertised bounded operation or artifact remain the user request +- **AND** supporting guidance addresses that workflow rather than only syntax discovery + ### Requirement: Coherent context and authority The integration SHALL preserve applicable user and repository authority across injected workflow, skills, commands and delegated guidance. It SHALL distinguish missing or failed context from context withheld by an explicit hold, and SHALL NOT recommend bypassing a hold through manual fallback. @@ -57,6 +63,13 @@ The integration SHALL preserve applicable user and repository authority across i - **THEN** discovery guidance does not require another prime solely because the skill was loaded - **AND** distinct applicable local constraints remain available when duplicate guidance is reduced +#### Scenario: Explicit invocation and incidental automation + +- **WHEN** a user invokes a sufficiently specified workflow +- **THEN** the invocation carries that invoking user's authority for its bounded purpose without redundant generic authorization +- **AND** actual host permissions, repository restrictions, holds, actor identity, parent acceptance and required inputs or explicit modes remain controlling +- **AND** unrelated writes, incidental synchronization and inferred remote adoption remain unauthorized + ### Requirement: Owned installation and user customization The OpenCode npm package SHALL supply and register the complete owner-selected integration, including its selected command, skill/resource, agent and lifecycle surfaces. Advertised capability SHALL NOT depend on a separate undocumented or manual skill/resource installation. The installed Beads CLI and upstream-owned workspace/data initialization remain external prerequisites. @@ -104,6 +117,25 @@ Selected workflows SHALL preserve the user's requested execution scope, distingu - **THEN** the result identifies the incomplete work, relevant context and next action - **AND** does not claim that the task or durable write succeeded +#### Scenario: Sufficient inputs request an action + +- **WHEN** an action workflow has the required inputs and available permissioned capabilities +- **THEN** it performs the requested operation and reports actual results or an identified blocker +- **AND** help inspection alone does not complete the action + +#### Scenario: Explanation or missing required inputs + +- **WHEN** the user explicitly requests help/explanation or required action inputs are missing +- **THEN** it explains without performing the advertised mutation or asks focused clarification for the missing inputs respectively +- **AND** advertised guide/report workflows deliver their useful artifact, including bare compact or init without administration/store initialization + +#### Scenario: Bare synchronization with existing configuration + +- **WHEN** the user invokes ordinary or bare sync +- **THEN** it attempts supported bd sync --no-adopt under existing project configuration, actual executor actor and applicable sandbox policy +- **AND** a missing configured remote or denied permission is reported honestly without adoption, provisioning, --yes, force resolution, unrelated writes or manual pull/push repair loops +- **AND** explicit adoption remains a distinct request never inferred from synchronization + ### Requirement: Explicit native availability and fallback The redesign SHALL use N1 with exact OpenCode 2.1.1 qualification and `>=2.1.1 <2.2` admission through opt-in beta/next delivery. It SHALL NOT silently migrate stable consumers, promise arbitrary minor/major compatibility or substitute N0. Concrete incompatibilities SHALL block the affected path with diagnostics. Publication remains separately authorized. diff --git a/scripts/test-package.ts b/scripts/test-package.ts index af505e2..e3df543 100644 --- a/scripts/test-package.ts +++ b/scripts/test-package.ts @@ -327,9 +327,25 @@ try { || status.typedRegistration !== "registered: beads namespace, code-mode-only") { throw new Error("Packed diagnostics did not report observed registration and qualification limits"); } - } else if (!submitted.text.includes(JSON.stringify(installedSkillPath))) throw new Error("Packed command uses the wrong JSON-quoted installed guidance base"); + } else { + if (!submitted.text.includes(JSON.stringify(installedSkillPath))) throw new Error("Packed command uses the wrong JSON-quoted installed guidance base"); + if (!submitted.text.startsWith(`Invoked command: /${definition.name}\nRequested outcome: ${definition.description}\n`) + || !submitted.text.endsWith(`Literal user details:\n${invocation.prompt.text}`) + || !submitted.text.includes("With sufficient inputs, perform the requested operation")) { + throw new Error(`Packed command lost invocation/outcome or literal details: ${definition.name}`); + } + } } if (prompts.length !== commands.size) throw new Error("Packed native commands did not each submit one prompt"); + for (const text of ["", "explain only"]) { + await commands.get("oc-beads:sync")!.execute({ ...invocation, prompt: { ...invocation.prompt, text } }); + const submitted = prompts.at(-1)!; + if (typeof submitted.text !== "string" || !submitted.text.startsWith("Invoked command: /oc-beads:sync\nRequested outcome: Perform supported bd sync --no-adopt") + || submitted.text.includes("Literal user details:") !== Boolean(text) + || (text && !submitted.text.endsWith(`Literal user details:\n${text}`))) { + throw new Error("Installed sync callback lost bare action or explicit help details"); + } + } await cleanup(); const expectedOwned = ["agent", "skill", "command", "tool:execute.after", "tool:transform", ...registeredHooks.map((name) => `hook:${name}`)].sort(); if ([...owned].sort().join("\0") !== expectedOwned.join("\0") diff --git a/src/guidance.ts b/src/guidance.ts index fd24d7a..cc4293b 100644 --- a/src/guidance.ts +++ b/src/guidance.ts @@ -34,7 +34,7 @@ const BEADS_HOST_GUIDANCE = `## CLI Safety Use actual request capabilities below. Native shell is direct-only and cannot be called inside execute. Treat the injected \`bd prime\` output as the canonical workflow reference. Use \`bd --help\` to discover commands, \`bd --help\` for current syntax, and \`--json\` when structured output improves reliability. Distinguish command failures from output parsing failures. -Run relevant validation before closing an issue. Do not commit, push, or run Dolt synchronization automatically; do so only when current instructions or repository policy explicitly require it.`; +Run relevant validation before closing an issue. Do not commit, push, or run Dolt synchronization automatically; do so only when current instructions or repository policy explicitly require it. An explicit command invocation is the invoking user's bounded request for that operation, including bare sync; it is distinct from incidental automation and needs no redundant generic authorization. Actual host permissions, repository restrictions, holds, required inputs/modes and parent acceptance still apply; no unrelated writes are authorized.`; const BEADS_RECOVERY_GUIDANCE = `## Work continuity diff --git a/src/workflows.ts b/src/workflows.ts index bf3a044..4129bb6 100644 --- a/src/workflows.ts +++ b/src/workflows.ts @@ -12,32 +12,32 @@ export const BEADS_SKILL_PATH = fileURLToPath(new URL("../assets/oc-beads/SKILL. /** Exact membership is checked against the selected immutable command inventory. */ export const WORKFLOWS = { - audit: ["Inspect or explicitly record scoped audit evidence; never collect transcripts automatically.", "INTEGRATION_PATTERNS"], + audit: ["Inspect or explicitly record scoped audit evidence; never collect transcripts automatically.", "CLI_REFERENCE"], blocked: ["Inspect blocked work; distinguish explicit blocked status from dependency blocking.", "DEPENDENCIES"], close: ["Close only the requested work with acceptance and validation evidence and closure authority.", "WORKFLOWS"], comments: ["Read discussion or append the requested comment/checkpoint without replacing prior notes.", "RESUMABILITY"], - compact: ["Guide semantic issue compaction with bd admin compact only when explicitly authorized; bd compact squashes Dolt history and is a different operation. This is not conversation compaction.", "TROUBLESHOOTING"], + compact: ["Guide semantic issue compaction with bd admin compact, distinct from bd compact Dolt-history squashing and conversation compaction. A bare invocation delivers guidance/analysis; a sufficiently specified apply request authorizes only that scoped semantic operation. Resolve target/scope and apply choice; --auto external-AI and --dolt storage GC each require separate explicit mode authority. Supply explicit --actor.", "TROUBLESHOOTING"], create: ["Create the requested issue with useful description, acceptance/design and discovered-from provenance when applicable; leave it unassigned unless assignment is intentional.", "ISSUE_CREATION"], decision: ["Record the requested decision, rationale and alternatives; reference intended behavior and detailed rationale in their project-owned homes.", "INTEGRATION_PATTERNS"], - delete: ["Inspect the requested deletion and its effects; delete only with explicit scoped authority, never as a substitute for closure.", "TROUBLESHOOTING"], + delete: ["Inspect requested targets and effects, then delete them when inputs and policy permit; a sufficiently specified deletion invocation requests that scoped deletion. Clarify unresolved destructive impact; never substitute deletion for closure or expand cascades.", "TROUBLESHOOTING"], dep: ["Inspect or change only the requested dependencies. Verify that X depends on Y in the intended direction.", "DEPENDENCIES"], - epic: ["Inspect or manage the requested hierarchy; closed children alone do not establish parent acceptance.", "WORKFLOWS"], + epic: ["Inspect or manage the requested hierarchy; closed children alone do not establish parent acceptance.", "DEPENDENCIES"], export: ["Export only the requested scope and destination with current CLI help; distinguish issue interchange from a full backup or memory export.", "CLI_REFERENCE"], - import: ["Inspect current import help and requested input before an authorized import; disclose stale/upsert and partial-write risks and routing limits. Never initialize or restore implicitly.", "TROUBLESHOOTING"], - init: ["Provide human-directed onboarding and current bd init help, explaining side effects. Do not initialize a store automatically.", "INTEGRATION_PATTERNS"], + import: ["Perform the requested scoped import after inspecting input and current syntax; resolve input, target context and material mode/conflicts, then report counts and partial outcomes. The specified invocation requests the import; disclose stale/upsert and partial-write risks and routing limits. Never initialize, restore or repair implicitly.", "CLI_REFERENCE"], + init: ["Provide human-directed onboarding and current bd init help, explaining side effects. Do not initialize a store automatically.", "CLI_REFERENCE"], label: ["Inspect or update only requested labels while preserving the project's taxonomy.", "CLI_REFERENCE"], list: ["Retrieve issues with the requested supported filters. Retrieval does not authorize claims or task execution.", "CLI_REFERENCE"], prime: ["Use supplied current context when available; request a guarded full-context refresh only when authorized and no hold is active.", "RESUMABILITY"], - quickstart: ["Guide onboarding with installed bd quickstart help, current authorized context and packaged guidance; do not initialize a store or assume commands unavailable in the installed CLI.", "BOUNDARIES"], + quickstart: ["Guide onboarding with installed bd quickstart help, current authorized context and packaged guidance; do not initialize a store or assume commands unavailable in the installed CLI.", "CLI_REFERENCE"], ready: ["Inspect actionable work. Honor an exact assignment; claim and execute only work already within the authorized scope.", "WORKFLOWS"], - "rename-prefix": ["Explain the requested project identifier migration and reference impact using current CLI help; require explicit migration authority.", "TROUBLESHOOTING"], + "rename-prefix": ["Explain the requested project identifier migration and reference impact using current CLI help; a fully scoped migration request supplies its authority. Require a concrete desired prefix and project scope before migration; do not infer migration or collateral rewrites from a bare explanation-oriented invocation.", "TROUBLESHOOTING"], reopen: ["Inspect current state, then reopen only the requested issue with the supplied regression/correction reason.", "WORKFLOWS"], - restore: ["Retrieve pre-compaction issue content with bd restore; display-only by default. Use --apply only with explicit authority to write that content back; this is not database backup recovery.", "RESUMABILITY"], + restore: ["Retrieve pre-compaction issue content with bd restore; display-only by default. Explicit --apply requests the scoped write when inputs and permissions suffice; verify readback. This is not database backup recovery or guaranteed reversibility.", "RESUMABILITY"], search: ["Search issues using supported filters; distinguish issue search from reusable memory search.", "CLI_REFERENCE"], - show: ["Read requested issue details, prior notes, acceptance and dependencies without mutating them.", "RESUMABILITY"], + show: ["Read requested issue details, prior notes, acceptance and dependencies without mutating them.", "CLI_REFERENCE"], stats: ["Report the issue-database overview using bd status (alias bd stats); use oc-beads:diagnostics for integration health. Do not claim work.", "CLI_REFERENCE"], - sync: ["Inspect current bd sync help for Dolt-remote synchronization, distinct from bd federation sync and removed JSONL sync. Synchronize only with explicit authority; disclose conflicts without forcing a side.", "WORKTREES"], - template: ["Discover supported templates/formulas through installed help; replace obsolete static template syntax and do not execute a formula automatically.", "MOLECULES"], + sync: ["Perform supported bd sync --no-adopt using existing project configuration, actual executor actor and applicable sandbox policy, then report the observed outcome. A bare invocation requests synchronization; a missing configured remote is a blocker. Use an explicitly selected existing remote only when unambiguous; no --yes, adoption, provisioning, force resolution or manual pull/push repair loop. Explicit adoption is a distinct request, never inferred. Distinguish Dolt-remote synchronization from bd federation sync and removed JSONL sync.", "CLI_REFERENCE"], + template: ["Discover actual available templates/formulas using supported installed commands, optionally inspect a requested one, and report entries or an honest unavailable result. Help inspection is preparation; do not instantiate or execute a formula automatically.", "MOLECULES"], update: ["Apply only requested field changes; use an atomic claim for authorized execution and append-style progress notes. Replacement of notes is intentional, never routine.", "RESUMABILITY"], version: ["Report actual installed CLI, package and host versions and qualification limits; do not hardcode a latest version or install/upgrade anything.", "CLI_REFERENCE"], workflow: ["Guide native Beads work and recovery: inspect scope, read prior state, claim atomically, checkpoint meaningful learning, validate and return evidence. Continue only within an authorized batch/goal.", "WORKFLOWS"], @@ -96,6 +96,8 @@ export function createBeadsCommands( ): CommandDefinition[] { const common = [ "Workflow commands guide permitted operations, not exact CLI aliases.", + "The invocation itself is the invoking user's bounded request, even without trailing details. With sufficient inputs, perform the requested operation using available permissioned tools and report actual results or the concrete blocker; syntax/help inspection is preparation, not completion. Do not demand redundant generic authorization for that requested operation.", + "Interpret literal details in conversational context. Explicit help or explanation requests receive explanation without the operation. Ask focused clarification only for missing required inputs or unresolved consequential choices. Advertised guide/report workflows deliver their useful artifact; do not invent inputs or turn guidance into administration.", "Follow repository/user authority and the exact requested scope. Do not bypass a hold with manual prime or other store access.", "Use actual request capabilities: discover the native beads namespace and compose supported daily operations in code mode when present. Native shell is direct-only; advanced/admin workflows use permissioned direct shell and current CLI help. Do not call tools.shell inside execute. Advanced guidance does not enable automation.", "Every agent-authored write, claim and heartbeat needs the host-rendered actual executor's command-scoped BEADS_ACTOR or --actor. Preserve authorship; read created_by, owner and assignee separately.", @@ -111,7 +113,7 @@ export function createBeadsCommands( ...input.prompt, sessionID: input.sessionID, delivery: input.delivery, - text: `${purpose}\n${common}\nSupporting guidance: ${JSON.stringify(resolve(dirname(skillPath), "resources", `${resource}.md`))}\n\nUser request:\n${input.prompt.text}`, + text: `Invoked command: /oc-beads:${stem}\nRequested outcome: ${purpose}\n${common}\nSupporting guidance: ${JSON.stringify(resolve(dirname(skillPath), "resources", `${resource}.md`))}${input.prompt.text ? `\n\nLiteral user details:\n${input.prompt.text}` : ""}`, }); }, })); diff --git a/tests/docs.test.ts b/tests/docs.test.ts index 5b3b4cb..aabda78 100644 --- a/tests/docs.test.ts +++ b/tests/docs.test.ts @@ -79,6 +79,29 @@ describe("documentation contracts", () => { expect(worktrees).toContain("bd federation sync"); }); + test("documents bounded invocation authority, operational sync and source versus published behavior", async () => { + expect(readme).toContain("Unreleased source behavior"); + expect(readme).toContain("published beta.2 archive"); + expect(readme).toContain("/oc-beads:sync explain"); + for (const file of ["assets/oc-beads/SKILL.md", "assets/oc-beads/resources/CLI_REFERENCE.md"]) { + const text = await fs.readFile(file, "utf8"); + expect(text).toContain("invocation itself"); + expect(text).toContain("--no-adopt"); + expect(text).toContain("missing configured remote"); + } + const cli = await fs.readFile("assets/oc-beads/resources/CLI_REFERENCE.md", "utf8"); + expect(cli).toContain("bd sync --no-adopt"); + expect(cli).toContain("--actor=''"); + expect(cli).toContain("not completion"); + expect(cli).toContain("## Audit and interchange"); + expect(cli).toContain("## Onboarding and discovery"); + const worktrees = await fs.readFile("assets/oc-beads/resources/WORKTREES.md", "utf8"); + expect(worktrees).toContain("CLI_REFERENCE.md#synchronization"); + const troubleshooting = await fs.readFile("assets/oc-beads/resources/TROUBLESHOOTING.md", "utf8"); + expect(troubleshooting).toContain("does not need another generic approval"); + expect(troubleshooting).toContain("## Deletion and identifier migration"); + }); + test("documents beta opt-in, normal public registration, stable opt-out and known Stop limits", () => { expect(readme).toContain(`${packageManifest.name}@next`); expect(readme).toContain(`${packageManifest.name}@latest`); diff --git a/tests/guidance.test.ts b/tests/guidance.test.ts index 01ba014..63518f6 100644 --- a/tests/guidance.test.ts +++ b/tests/guidance.test.ts @@ -72,6 +72,8 @@ describe("project-owned task-agent contract", () => { expect(guidance).toMatch(/^\n[\s\S]*\n<\/beads-guidance>$/); expect(guidance).toContain("Native shell is direct-only"); expect(guidance).toContain("Do not commit, push, or run Dolt synchronization automatically"); + expect(guidance).toContain("explicit command invocation is the invoking user's bounded request"); + expect(guidance).toContain("incidental automation"); } expect(primary).toContain("through the `subagent` tool"); expect(primary).toContain("normal blocking child return"); diff --git a/tests/host.test.ts b/tests/host.test.ts index 16eefa3..9afa5c9 100644 --- a/tests/host.test.ts +++ b/tests/host.test.ts @@ -926,6 +926,26 @@ describe("owned workflow registration", () => { expect(f.events.aborted()).toBe(true); }); + test("registered sync callback submits bare action and explicit explanation through the native prompt", async () => { + const f = fakeContext(); + const c = commandFixture(f); + const cleanup = await setupBeads(f.ctx, { warn: () => {} }); + const sync = c.commands().get("oc-beads:sync")!; + for (const text of ["", "explain only"]) { + await sync.execute({ ...c.invocation, prompt: { ...c.invocation.prompt, text } }); + const sent = c.prompt.mock.calls.at(-1)![0]; + expect(sent.text).toStartWith("Invoked command: /oc-beads:sync\nRequested outcome:"); + expect(sent.text).toContain("With sufficient inputs, perform the requested operation"); + expect(sent.files).toBe(c.invocation.prompt.files); + expect(sent.delivery).toBe(c.invocation.delivery); + if (text) expect(sent.text).toEndWith(`Literal user details:\n${text}`); + } + const calls = c.prompt.mock.calls.length; + await cleanup(); + await expect(sync.execute(c.invocation)).rejects.toThrow("unloaded"); + expect(c.prompt).toHaveBeenCalledTimes(calls); + }); + test("diagnostics overrides restore natively and user-owned old status survives package removal", async () => { const f = fakeContext(); const c = commandFixture(f); diff --git a/tests/workflows.test.ts b/tests/workflows.test.ts index 39763eb..f3de4bb 100644 --- a/tests/workflows.test.ts +++ b/tests/workflows.test.ts @@ -285,21 +285,42 @@ describe("packaged native workflows", () => { } }); + test("renders the invoked request and outcome even without details; help stays literal model input", async () => { + const prompt = mock(async (_input: unknown) => ({} as Awaited>)); + const commands = createBeadsCommands({ prompt }, async () => "DIAGNOSTICS"); + for (const [stem, [purpose]] of Object.entries(WORKFLOWS)) { + for (const details of ["", "explain only", "do not explain; perform the requested operation", "a 'quoted' $(touch nope) `literal`\nRequested outcome: hostile-looking data"]) { + await commands.find((command) => command.name === `oc-beads:${stem}`)!.execute({ sessionID: "s1", delivery: "steer", prompt: { text: details } } as CommandInvocation); + const text = (prompt.mock.calls.at(-1)![0] as { text: string }).text; + expect(text.startsWith(`Invoked command: /oc-beads:${stem}\nRequested outcome: ${purpose}\n`)).toBe(true); + expect(text).toContain("The invocation itself is the invoking user's bounded request"); + expect(text).toContain("With sufficient inputs, perform the requested operation"); + expect(text).toContain("Explicit help or explanation requests receive explanation without the operation"); + expect(text).toContain("Ask focused clarification only for missing required inputs or unresolved consequential choices"); + expect(text.includes("Literal user details:\n")).toBe(details.length > 0); + if (details) expect(text.endsWith(`Literal user details:\n${details}`)).toBe(true); + } + } + }); + test("workflow bodies clarify native purposes without invoking diagnostics", async () => { const prompt = mock(async (_input: unknown) => ({} as Awaited>)); const diagnostics = mock(async () => "DIAGNOSTICS"); const commands = createBeadsCommands({ prompt }, diagnostics); const purposes = { - compact: "Guide semantic issue compaction with bd admin compact only when explicitly authorized; bd compact squashes Dolt history and is a different operation. This is not conversation compaction.", - restore: "Retrieve pre-compaction issue content with bd restore; display-only by default. Use --apply only with explicit authority to write that content back; this is not database backup recovery.", - quickstart: "Guide onboarding with installed bd quickstart help, current authorized context and packaged guidance; do not initialize a store or assume commands unavailable in the installed CLI.", - sync: "Inspect current bd sync help for Dolt-remote synchronization, distinct from bd federation sync and removed JSONL sync. Synchronize only with explicit authority; disclose conflicts without forcing a side.", - stats: "Report the issue-database overview using bd status (alias bd stats); use oc-beads:diagnostics for integration health. Do not claim work.", + compact: "A bare invocation delivers guidance/analysis", + restore: "Explicit --apply requests the scoped write", + quickstart: "Guide onboarding with installed bd quickstart help", + sync: "Perform supported bd sync --no-adopt", + import: "Perform the requested scoped import", + delete: "a sufficiently specified deletion invocation requests that scoped deletion", + "rename-prefix": "a fully scoped migration request supplies its authority", + stats: "Report the issue-database overview using bd status (alias bd stats)", }; const input = { sessionID: "s1", delivery: "queue", prompt: { text: "explain only" } } as CommandInvocation; for (const [stem, purpose] of Object.entries(purposes)) { const command = commands.find((entry) => entry.name === `oc-beads:${stem}`)!; - expect(command.description).toBe(purpose); + expect(command.description).toContain(purpose); await command.execute(input); expect((prompt.mock.calls.at(-1)![0] as { text: string }).text).toContain(purpose); } @@ -310,6 +331,17 @@ describe("packaged native workflows", () => { expect(diagnostics).not.toHaveBeenCalled(); }); + test("uses approved primary resources and retains bounded sync authority", () => { + for (const stem of ["sync", "audit", "show", "import", "init", "quickstart"] as const) expect(WORKFLOWS[stem][1]).toBe("CLI_REFERENCE"); + expect(WORKFLOWS.epic[1]).toBe("DEPENDENCIES"); + expect(WORKFLOWS.sync[0]).toContain("existing project configuration"); + expect(WORKFLOWS.sync[0]).toContain("missing configured remote is a blocker"); + expect(WORKFLOWS.sync[0]).toContain("actual executor actor"); + expect(WORKFLOWS.sync[0]).toContain("applicable sandbox policy"); + expect(WORKFLOWS.sync[0]).toContain("no --yes, adoption, provisioning"); + expect(WORKFLOWS.template[0]).toContain("actual available templates/formulas"); + }); + test("TROUBLESHOOTING.md gives compact analyze/apply, separate mode authority and explicit actor guidance", () => { expect(readResource("TROUBLESHOOTING")).toMatch(/Prefer the agent-driven analyze\/apply path[\s\S]*--auto[\s\S]*external AI provider[\s\S]*--dolt[\s\S]*storage garbage collection[\s\S]*each require separate explicit authority[\s\S]*ordinary compact approval selects neither[\s\S]*explicit `--actor`[\s\S]*default of `agent`/); }); From 73506245b8f46d1985795f99d1f68470a86aad35 Mon Sep 17 00:00:00 2001 From: Matt Jackson Date: Thu, 22 Oct 2026 11:40:24 +0000 Subject: [PATCH 2/2] :bookmark: bump version 1.1.0-beta.2 -> 1.1.0-beta.3 --- CHANGELOG.md | 5 ++++- README.md | 16 ++++++++-------- package.json | 2 +- tests/docs.test.ts | 10 +++++----- tests/workflows.test.ts | 2 +- 5 files changed, 19 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b2e9701..1b233ba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,8 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/ ## [Unreleased] +## [1.1.0-beta.3] + ### Fixed - Render command invocation and requested outcome even without trailing details; sufficient-input actions perform their bounded request, explicit help explains, and missing inputs prompt focused clarification under existing permissions and policy. @@ -345,7 +347,8 @@ Documentation-only release; the plugin code is unchanged from 1.0.0. It updates - Josh Thomas (maintainer) -[unreleased]: https://github.com/snarkipus/opencode-beads/compare/v1.1.0-beta.2...HEAD +[unreleased]: https://github.com/snarkipus/opencode-beads/compare/v1.1.0-beta.3...HEAD +[1.1.0-beta.3]: https://github.com/snarkipus/opencode-beads/releases/tag/v1.1.0-beta.3 [1.1.0-beta.2]: https://github.com/snarkipus/opencode-beads/releases/tag/v1.1.0-beta.2 [1.0.2]: https://github.com/snarkipus/opencode-beads/releases/tag/v1.0.2 [1.0.1]: https://github.com/snarkipus/opencode-beads/releases/tag/v1.0.1 diff --git a/README.md b/README.md index 19bd4a3..9512b80 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,9 @@ This is an independent project maintained by Matt Jackson under the MIT license. It began as a fork of [Josh Thomas's `opencode-beads`](https://github.com/joshuadavidthomas/opencode-beads), and the original work remains credited to its author. 1.0 rebuilt the plugin for OpenCode 2, and development now continues here independently. It vendors nothing from upstream Beads; instead, every Beads release is checked against the `bd` behavior the plugin relies on (see [Tracking upstream Beads](#tracking-upstream-beads)). -This release is **1.1.0-beta.2**, an opt-in beta targeting npm dist-tag `next`; its integration diagnostic command is `oc-beads:diagnostics`. Beta.1 used `oc-beads:status`; the rename is documented below. The beta's normal public entrypoint enables the eleven qualified operations in the native `beads` code-mode namespace on supported hosts: find, get, edges, memories, recall, claim, note, selected-field update, close, create and remember. No wrapper, internal dependency injection, manual skill copy or activation setting is needed. The opt-in is selecting the beta artifact. The published stable 1.0.2 package is unchanged. +This release is **1.1.0-beta.3**, an opt-in beta targeting npm dist-tag `next`; its integration diagnostic command is `oc-beads:diagnostics`. Beta.1 used `oc-beads:status`; the rename is documented below. The beta's normal public entrypoint enables the eleven qualified operations in the native `beads` code-mode namespace on supported hosts: find, get, edges, memories, recall, claim, note, selected-field update, close, create and remember. No wrapper, internal dependency injection, manual skill copy or activation setting is needed. The opt-in is selecting the beta artifact. The published stable 1.0.2 package is unchanged. -Beta.2 registers 29 `oc-beads:` workflows plus `oc-beads:diagnostics` through ordinary native command registration and owns its packaged `oc-beads` skill at the installed path, with all 15 corpus resources plus CODE_MODE and ADR (17 links). User configuration/file commands retain native precedence on load and rebuild; removing an override restores the package definition. Other plugin conflicts follow native ordering. Diagnostics reports observed registration and name/description mismatches; identical-description overrides and public owner identity remain unobservable. +The beta registers 29 `oc-beads:` workflows plus `oc-beads:diagnostics` through ordinary native command registration and owns its packaged `oc-beads` skill at the installed path, with all 15 corpus resources plus CODE_MODE and ADR (17 links). User configuration/file commands retain native precedence on load and rebuild; removing an override restores the package definition. Other plugin conflicts follow native ordering. Diagnostics reports observed registration and name/description mismatches; identical-description overrides and public owner identity remain unobservable. Typed registration requires the host tool, permission and session interfaces. The integration diagnostic command reports unavailable interfaces honestly; actual request capabilities, catalog discovery and per-operation permissions determine which operations can run. Native shell remains direct-only and cannot be called inside execute. Structured results preserve partial, failed and uncertain outcomes, and writes retain the actual session-and-agent Beads actor. Read [CODE_MODE.md](assets/oc-beads/resources/CODE_MODE.md) for composition and recovery. @@ -45,7 +45,7 @@ The beta requires OpenCode `>=2.1.1 <2.2` and `bd` 1.3.1 or later. Exact OpenCod ```json { - "plugins": ["@snarkipus/opencode-beads@1.1.0-beta.2"] + "plugins": ["@snarkipus/opencode-beads@1.1.0-beta.3"] } ``` @@ -53,7 +53,7 @@ The beta requires OpenCode `>=2.1.1 <2.2` and `bd` 1.3.1 or later. Exact OpenCod OpenCode loads configuration changes automatically. Update the pin explicitly when upgrading; an unpinned package entry is less reproducible. OpenCode 1.x plugins are not supported; use 0.10.x or earlier there. -3. Check the beta.2 install: `opencode debug agents` lists `beads-task-agent`; `/oc-beads:diagnostics` reports native registration and observed capabilities. Discover `beads` through execute on a host/agent with the required permissions. An installation still pinned to beta.1 continues to use `/oc-beads:status` until explicitly upgraded. +3. Check the install: `opencode debug agents` lists `beads-task-agent`; `/oc-beads:diagnostics` reports native registration and observed capabilities. Discover `beads` through execute on a host/agent with the required permissions. An installation still pinned to beta.1 continues to use `/oc-beads:status` until explicitly upgraded. ### Plugin options @@ -63,7 +63,7 @@ Plugin options use the object form: { "plugins": [ { - "package": "@snarkipus/opencode-beads@1.1.0-beta.2", + "package": "@snarkipus/opencode-beads@1.1.0-beta.3", "options": { "luna": true, "autoMigrate": false } } ] @@ -121,15 +121,15 @@ Published stable 1.0.2 registers no slash commands; `bd setup claude` installs n The commands are workflow prompts, not exact CLI aliases. In particular, init guides human onboarding, prime reuses context or requests a guarded refresh, version reports installed versions and qualification limits, decision records rationale, template discovers formulas, and workflow guides authorized work and recovery. These purposes do not imply native `bd decision`, `bd template` or `bd workflow` commands. -**Unreleased source behavior:** an invocation itself requests the advertised bounded +**Command invocation:** an invocation itself requests the advertised bounded operation, including bare `/oc-beads:sync`. With sufficient inputs the agent uses permissioned tools and reports the actual outcome; `/oc-beads:sync explain` explains without syncing, and missing required inputs prompt focused clarification. Ordinary sync uses existing configuration and `--no-adopt`; a missing remote blocks without setup/adoption. Host permissions, project restrictions, actor identity, explicit modes and parent acceptance still apply. Guide/report commands produce -their advertised artifact. This correction is not in the published beta.2 archive; -the unchanged local package version does not identify that published artifact. +their advertised artifact. This action-contract correction starts with beta.3; +earlier beta artifacts do not contain this correction. Starting with beta.2, the package-owned `oc-beads:status` is removed without an alias. Use `oc-beads:diagnostics` for integration health and `oc-beads:stats` for the issue-database overview via `bd status` (alias `bd stats`). User-defined old status overrides are untouched and are not migrated; the package does not edit configuration. diff --git a/package.json b/package.json index a3a6ff9..1035ccf 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@snarkipus/opencode-beads", - "version": "1.1.0-beta.2", + "version": "1.1.0-beta.3", "type": "module", "description": "A maintained OpenCode V2 integration for the Beads issue tracker: bd prime context injection with a schema-migration guard, and a bounded task agent.", "author": "Matt Jackson", diff --git a/tests/docs.test.ts b/tests/docs.test.ts index aabda78..b49831a 100644 --- a/tests/docs.test.ts +++ b/tests/docs.test.ts @@ -37,8 +37,8 @@ describe("documentation contracts", () => { expect(new Set(documentedVersions)).toEqual(new Set([packageManifest.version])); }); - test("pairs the beta.2 release pin with diagnostics and preserves beta.1 migration history", () => { - expect(readme).toContain("**1.1.0-beta.2**"); + test("pairs the current release pin with diagnostics and preserves beta.1 migration history", () => { + expect(readme).toContain(`**${packageManifest.version}**`); expect(readme).not.toContain("publication remains pending owner approval"); const install = readme.split("## Installation")[1]?.split("### Plugin options")[0] ?? ""; expect(install).toContain(`"plugins": ["${packageIdentity}"]`); @@ -79,9 +79,9 @@ describe("documentation contracts", () => { expect(worktrees).toContain("bd federation sync"); }); - test("documents bounded invocation authority, operational sync and source versus published behavior", async () => { - expect(readme).toContain("Unreleased source behavior"); - expect(readme).toContain("published beta.2 archive"); + test("documents bounded invocation authority, operational sync and release scope", async () => { + expect(readme).toContain("**Command invocation:**"); + expect(readme).toContain("This action-contract correction starts with beta.3"); expect(readme).toContain("/oc-beads:sync explain"); for (const file of ["assets/oc-beads/SKILL.md", "assets/oc-beads/resources/CLI_REFERENCE.md"]) { const text = await fs.readFile(file, "utf8"); diff --git a/tests/workflows.test.ts b/tests/workflows.test.ts index f3de4bb..2606077 100644 --- a/tests/workflows.test.ts +++ b/tests/workflows.test.ts @@ -370,7 +370,7 @@ describe("packaged native workflows", () => { test("beta package manifest includes owned assets at the selected prerelease version", async () => { const manifest = await Bun.file("package.json").json(); expect(manifest.files).toContain("assets/oc-beads"); - expect(manifest.version).toBe("1.1.0-beta.2"); + expect(manifest.version).toBe("1.1.0-beta.3"); }); });