feat: add Terra task agent and upstream-aligned Beads guidance for 2.1.0

.github/workflows/beads-contract.yml

@@ -1,6 +1,6 @@
 name: beads-contract
 
-# Nothing is vendored from upstream Beads. This checks the latest stable bd release against the
+# Project-owned guidance contains attributed excerpts; no upstream executable or sync-managed vendor tree is shipped. This checks the latest stable bd release against the
 # plugin's contract daily, and fails when a newer release has not been reviewed yet.
 # Independent MAIN source comparison is informational; unavailable evidence fails only its job.
 on:

AGENTS.md

@@ -59,7 +59,7 @@ its repository-specific tools, architecture and style rules do not apply here.
 
 ## Notes
 - This is an OpenCode V2 plugin integrating the beads issue tracker
-- Nothing is vendored from upstream Beads; see `docs/beads-artifact-policy.md`. Review each Beads release's upgrade notes against the surfaces listed there
+- Project-owned guidance contains attributed excerpts; no upstream executable, host integration or sync-managed vendor tree is shipped; see `docs/beads-artifact-policy.md`. Review each Beads release's upgrade notes against the surfaces listed there
 
 ## Upstream responsibility boundary
 
@@ -76,6 +76,12 @@ This project-owned policy applies to commands in generated integration blocks to
 - Give a substantive independently owned review one bounded review Bead linked to its planning work and exact candidate. Reuse it through correction/recheck cycles; do not create a ticket per document, invocation, transient retry or minor nit. Record the actual reviewer actor/session, verdict, findings and evidence. Do not invent retroactive claims or timestamps for reviews already performed.
 - Ownership of behavior, rationale/evidence and execution status follows [Where truth lives](#where-truth-lives). Close planning/review from their own evidence and owner acceptance, not from implementation completion. Their closure does not authorize implementation, release or deployment. Readiness alone is never dispatch permission.
 
+## Native harness onboarding
+
+- Codex uses the shared `.agents/skills/beads` skill, `.codex/hooks.json` and the enabled native hooks feature. Review/trust the exact repo hook hashes through Codex's normal trust mechanism; do not use a blanket hook-trust bypass. For ordinary orchestrated work, retain user config so its hash-scoped trust records load, while selecting model/effort and assignment authority explicitly. `--ignore-user-config` is for deliberately isolated runs, not proof of complete native hook onboarding.
+- Claude Code uses its installed Beads plugin for the skill, command resources and lifecycle context. When authentication HOME differs from plugin-install HOME, pass `--plugin-dir` for the verified existing plugin directory; do not copy credentials, install duplicate hooks or infer loading from `bd setup claude --check` alone.
+- Verify actual hook/context delivery and one scoped CLI operation in a fresh harness run. Setup checks prove file/config presence, not execution. Full Beads capability remains available; task-specific read/write/claim/closure limits come from the assigned Bead and dispatch. Native hook output and historical memories do not expand those limits or transfer parent acceptance.
+
 ## Releasing a New Version
 
 **Triggers**: User says "bump the version", "cut a new release", "release a new version", "let's do a release", or similar.

CHANGELOG.md

@@ -18,6 +18,18 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 
 ## [Unreleased]
 
+## [2.1.0]
+
+### Added
+
+- Optional `terra: true` profile registers `beads-task-agent-terra` on `openai/gpt-6.1-terra#medium`, with the same scope-bounded guidance, permissions, step cap, actor attribution and Beads context eligibility as the existing task agents. The default agent still inherits its model; Luna Max is unchanged and both optional profiles can coexist. Provider access remains external; no silent fallback or model-quality guarantee is added.
+
+### Changed
+
+- Align issue-writing and deliberate handoff guidance with attributed Beads excerpts; monitor the upstream license alongside the existing source inventory.
+- Document native Claude Code and Codex Beads onboarding for orchestrated work: retain verified native integration, confirm actual context delivery and bind execution authority to the assigned Bead.
+- Reconcile the validated Beads CLI baseline to 1.3.4 while preserving minimum 1.3.1, and add independent daily/manual advisory upstream-source comparison. These maintenance changes were already delivered on main; they do not introduce runtime repair or automatic adoption.
+
 ## [2.0.0]
 
 ### Changed
@@ -378,7 +390,8 @@ Documentation-only release; the plugin code is unchanged from 1.0.0. It updates
 
 - Josh Thomas <josh@joshthomas.dev> (maintainer)
 
-[unreleased]: https://github.com/snarkipus/opencode-beads/compare/v2.0.0...HEAD
+[unreleased]: https://github.com/snarkipus/opencode-beads/compare/v2.1.0...HEAD
+[2.1.0]: https://github.com/snarkipus/opencode-beads/releases/tag/v2.1.0
 [2.0.0]: https://github.com/snarkipus/opencode-beads/releases/tag/v2.0.0
 [1.1.0-beta.5]: https://github.com/snarkipus/opencode-beads/releases/tag/v1.1.0-beta.5
 [1.1.0-beta.4]: https://github.com/snarkipus/opencode-beads/releases/tag/v1.1.0-beta.4

README.md

@@ -18,11 +18,11 @@ The installed `bd` CLI stays authoritative for issues, project initialization, s
 
 ## Supported versions
 
-Version **2.0.0** is the stable line.
+Version **2.1.0** targets the stable line.
 
 | Component | Supported | Evidence |
 | --- | --- | --- |
-| OpenCode | `>=2.2.6 <2.3` | Exact 2.2.6 native-host qualification plus one genuine model workflow |
+| OpenCode | `>=2.2.6 <2.3` | Base integration: exact 2.2.6 native-host qualification plus one genuine model workflow; one read-only Terra Medium child dispatch on 2.2.6 |
 | `bd` CLI | 1.3.1 through 1.x | 1.3.4 contract baseline |
 
 A compatible range is admission, not proof that every future patch was tested. The plugin refuses to register on hosts outside the range. Older hosts: see [Compatibility](docs/user-guide.md#compatibility).
@@ -44,18 +44,20 @@ A compatible range is admission, not proof that every future patch was tested. T
 
    ```json
    {
-     "plugins": ["@snarkipus/opencode-beads@2.0.0"]
+     "plugins": ["@snarkipus/opencode-beads@2.1.0"]
    }
    ```
 
-   OpenCode reloads configuration automatically. Update the pin explicitly when upgrading. Options such as `luna`, `stealth` and `autoMigrate` use the [object form](docs/user-guide.md#plugin-options).
+   OpenCode reloads configuration automatically. Update the pin explicitly when upgrading. Options such as `luna`, `terra`, `stealth` and `autoMigrate` use the [object form](docs/user-guide.md#plugin-options).
 
 3. Check the install: `opencode debug agents` lists `beads-task-agent`, and `/oc-beads:diagnostics` reports native registration and observed capabilities.
 
-### Upgrading to 2.0.0
+### Upgrading to 2.1.0
 
 Upgrade OpenCode before changing the plugin pin: 2.0.0 requires `>=2.2.6 <2.3` and has no 2.1 compatibility layer. Then replace the existing plugin entry, not add a second one, and check `/oc-beads:diagnostics`. Existing exact 1.x and beta pins remain available; installations are not upgraded automatically. Staying on OpenCode 2.1? Keep the exact `1.1.0-beta.5` pin, which retains its `>=2.1.1 <2.2` range. Other migration notes are in the [user guide](docs/user-guide.md#upgrading).
 
+From plugin 2.0.0, the host range and existing options are unchanged. To add the optional `beads-task-agent-terra` profile, enable `terra: true` in the object form. It uses `openai/gpt-6.1-terra#medium`; the default agent still inherits its model, Luna Max remains available, and both optional profiles can coexist. Enabling a profile does not authorize work or change the parent route.
+
 ## First use
 
 In an initialized project:
@@ -89,7 +91,7 @@ The agent claims the issue atomically and appends checkpoints under the actual s
 
 ## Authorship and license
 
-This is an independent project maintained by Matt Jackson. 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. It vendors nothing from upstream Beads; the daily/manual maintenance workflow checks tagged CLI compatibility and independently compares reviewed upstream integration sources with current MAIN. Completed source changes are informational; adoption remains a human decision.
+This is an independent project maintained by Matt Jackson. 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. Its project-owned guidance includes attributed MIT-licensed excerpts; it redistributes no upstream executable, host integration or sync-managed vendor tree. See the [notice](assets/oc-beads/THIRD_PARTY_NOTICES.md). The daily/manual maintenance workflow checks tagged CLI compatibility and independently compares reviewed upstream integration sources with current MAIN. Completed source changes are informational; adoption remains a human decision.
 
 opencode-beads is licensed under the MIT license. See [`LICENSE`](LICENSE).
 

assets/oc-beads/SKILL.md

@@ -98,6 +98,10 @@ WORKTREES only for relevant worktree context.
   evidence expected, actor, and stop condition. There is no required
   command-count threshold or one-issue-per-invocation loop.
 
+## Issue fields
+
+Title identifies the outcome; description explains why and context; design records the approach and may change; acceptance states stable, verifiable outcomes; notes hold evolving state. Lifecycle progress alone does not change objectives or acceptance; authorized factual corrections and genuine clarifications remain legitimate. This package-owned `oc-beads` skill is distinct from the shared `beads` skill that `bd init` may create.
+
 ## Keep useful progress
 
 At a meaningful change in direction, record what was attempted, what happened,
@@ -108,8 +112,13 @@ the issue's notes so useful earlier learning remains available:
 bd update '<id>' --append-notes="Tried …; result …; because …; blocker …; next …" --actor='<executor-actor>' --sandbox --json
 ```
 
-Use `--append-notes` for checkpoints. Replacing notes is a deliberate edit, not
-the routine checkpoint path. Keep records concise and evidence-based; do not
+Use `--append-notes` for checkpoints. For a deliberate current-state handoff, replace working notes while carrying forward relevant decisions, rejected approaches and reasons, blockers and the next action:
+
+```sh
+bd update '<id>' --notes="Current state; decisions; blockers; next action" --actor='<executor-actor>' --sandbox --json
+```
+
+The typed `note` operation is append-only. If only typed operations are available, append a labelled handoff and report the typed-only limitation; replacement requires an available, permissioned direct shell. Keep records concise and evidence-based; do not
 store credentials, raw dumps, or guesses as facts. Do not write just to meet a
 count or frequency target when nothing material changed. If a write fails or its
 result is uncertain, report that state and inspect before retrying.

assets/oc-beads/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,25 @@
+# Third-party notices
+
+The following MIT license covers attributed Beads excerpts from revision `5ac194105c138ca799bc2f6534c8f92712d8d782` in ISSUE_CREATION, RESUMABILITY and WORKFLOWS, and earlier project adaptations from revision `4a67d0d0288c1b4ee23e17fc896f47616931ba2d`.
+
+MIT License
+
+Copyright (c) 2025 Beads Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

assets/oc-beads/resources/BOUNDARIES.md

@@ -53,5 +53,6 @@ only within the authority already granted.
 
 For a tracked item, preserve its execution identity and history. Claim
 atomically when authorized, use an explicit actor on writes, and append material
-progress rather than replacing previous notes. A task record does not own the
+progress; a deliberate current-state handoff may replace working notes while
+preserving relevant learning. A task record does not own the
 Beads database or authorize sync, setup, permission changes, or Git operations.

assets/oc-beads/resources/ISSUE_CREATION.md

@@ -1,6 +1,6 @@
 # Creating useful issues
 
-> Adapted from [Beads marketplace-main `ISSUE_CREATION.md`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/resources/ISSUE_CREATION.md).
+> Adapted from Beads [`ISSUE_CREATION.md`](https://github.com/gastownhall/beads/blob/5ac194105c138ca799bc2f6534c8f92712d8d782/plugins/beads/skills/beads/resources/ISSUE_CREATION.md) at `5ac194105c138ca799bc2f6534c8f92712d8d782`; see [third-party notices](../THIRD_PARTY_NOTICES.md).
 
 Create a durable issue when work needs its own assignment, dependencies,
 multi-session history, or acceptance record, and only when the existing authority
@@ -14,7 +14,7 @@ not authorize the new issue.
 - **Description:** why the work exists, relevant context, and boundaries.
 - **Design:** the intended approach and important constraints.
 - **Acceptance:** observable conditions that define completion.
-- **Notes:** current progress and later checkpoints, appended as work proceeds.
+- **Notes:** evolving progress, incremental checkpoints and deliberate current-state handoffs.
 
 Do not treat a proposed approach as an acceptance test. Avoid secrets, copied
 logs, vague “investigate” titles without a question, and unsupported promises.
@@ -43,3 +43,117 @@ bd create "Clarify retry behavior" --type=task --priority=2 \
 Before creating linked work, inspect the parent and verify dependency direction.
 Keep planning and implementation ownership distinct when the project assigns
 them to different people.
+
+
+### Verbatim upstream excerpt: ISSUE_CREATION, When to Ask First vs Create Directly and Issue Quality
+
+## When to Ask First vs Create Directly {#when-to-ask}
+
+### Ask the user before creating when:
+- Knowledge work with fuzzy boundaries
+- Task scope is unclear
+- Multiple valid approaches exist
+- User's intent needs clarification
+
+### Create directly when:
+- Clear bug discovered during implementation
+- Obvious follow-up work identified
+- Technical debt with clear scope
+- Dependency or blocker found
+
+**Why ask first for knowledge work?** Task boundaries in strategic/research work are often unclear until discussed, whereas technical implementation tasks are usually well-defined. Discussion helps structure the work properly before creating issues, preventing poorly-scoped issues that need immediate revision.
+
+## Issue Quality {#quality}
+
+Use clear, specific titles and include sufficient context in descriptions to resume work later.
+
+### Field Usage
+
+**Use --design flag for:**
+- Implementation approach decisions
+- Architecture notes
+- Trade-offs considered
+
+**Use --acceptance flag for:**
+- Definition of done
+- Testing requirements
+- Success metrics
+
+**OpenCode adaptation:** Follow the existing assignment and permissions; quoted commands are historical illustrations, not copyable local commands. Use the actor-scoped examples above.
+
+
+### Verbatim upstream excerpt: ISSUE_CREATION, Design vs Acceptance Criteria
+
+## Design vs Acceptance Criteria (Critical Distinction) {#design-vs-acceptance}
+
+Common mistake: Putting implementation details in acceptance criteria. Here's the difference:
+
+### DESIGN field (HOW to build it):
+- "Use two-phase batchUpdate approach: insert text first, then apply formatting"
+- "Parse with regex to find * and _ markers"
+- "Use JWT tokens with 1-hour expiry"
+- Trade-offs: "Chose batchUpdate over streaming API for atomicity"
+
+### ACCEPTANCE CRITERIA (WHAT SUCCESS LOOKS LIKE):
+- "Bold and italic markdown formatting renders correctly in the Doc"
+- "Solution accepts markdown input and creates Doc with specified title"
+- "Returns doc_id and webViewLink to caller"
+- "User tokens persist across sessions and refresh automatically"
+
+### Why this matters:
+- Design can change during implementation (e.g., use library instead of regex)
+- Acceptance criteria should remain stable across sessions
+- Criteria should be **outcome-focused** ("what must be true?") not **step-focused** ("do these steps")
+- Each criterion should be **verifiable** - you can definitively say yes/no
+
+### The pitfall
+
+Writing criteria like "- [ ] Use batchUpdate approach" locks you into one implementation.
+
+Better: "- [ ] Formatting is applied atomically (all at once or not at all)" - allows flexible implementation.
+
+### Test yourself
+
+If you rewrote the solution using a different approach, would the acceptance criteria still apply? If not, they're design notes, not criteria.
+
+### Example of correct structure
+
+✅ **Design field:**
+```
+Two-phase Docs API approach:
+1. Parse markdown to positions
+2. Create doc + insert text in one call
+3. Apply formatting in second call
+Rationale: Atomic operations, easier to debug formatting separately
+```
+
+✅ **Acceptance criteria:**
+```
+- [ ] Markdown formatting renders in Doc (bold, italic, headings)
+- [ ] Lists preserve order and nesting
+- [ ] Links are clickable
+- [ ] Large documents (>50KB) process without timeout
+```
+
+❌ **Wrong (design masquerading as criteria):**
+```
+- [ ] Use two-phase batchUpdate approach
+- [ ] Apply formatting in second batchUpdate call
+```
+
+**OpenCode adaptation:** Follow the existing assignment and permissions; quoted commands are historical illustrations, not copyable local commands. Use the actor-scoped examples above.
+
+
+### Verbatim upstream excerpt: ISSUE_CREATION, Quick Reference
+
+## Quick Reference
+
+**Creating good issues:**
+
+1. **Title**: Clear, specific, action-oriented
+2. **Description**: Problem statement, context, why it matters
+3. **Design**: Approach, architecture, trade-offs (can change)
+4. **Acceptance**: Outcomes, success criteria (should be stable)
+5. **Notes**: Implementation details, session handoffs (evolves over time)
+
+**OpenCode adaptation:** Follow the existing assignment and permissions; quoted commands are historical illustrations, not copyable local commands. Use the actor-scoped examples above.