v3.1.0

[v3.1.0] - 2026-08-27

Added

• Session-start hook (opt-in --session-hook / -SessionHook): deterministically
  causes the rubber-duck agent to load the duck-policy skill at session start.
  • OpenCode: plugin installed to .opencode/plugins/session-start.js registers
    rubber-duck sessions and injects the startup directive into the system prompt
    on every model call (experimental.chat.system.transform).
  • Claude Code: scripts installed to .claude/hooks/ and a SessionStart hook
    merged into .claude/settings.local.json (idempotent). Fires only when the
    rubber-duck agent is active, detected via hook input agent_type.
  • Build emits hook artifacts to dist/opencode/hooks/ and dist/claude/hooks/.
  • Installer (bash + PowerShell parity): install/uninstall of hook artifacts,
    manifest pins, and per-target sessionHook tracking replayed on sync.
  • The rubber-duck agent body keeps its Enforcement Bootstrap mandate as a
    fallback when the hook is not installed.
  • Copilot support pending (deferred; see plan doc).
• Reviewable-unit decomposition: multi-PR plans must decompose into reviewable units (independent merge, working state after each, explicit ordering + acceptance criteria). Methodology in src/shared/skill-snippets/reviewable-units.md; duck-design writes plans as PR sequences; duck-policy Checkpoint 1 gates on decomposition.
• Validation fixture validation/fixtures/context-loading/src/cache.ts anchors deferred-debt marker tests to real code.
• Plan decomposition verification spec: docs/architecture/08-plan-decomposition-verification.md defines the trigger predicate (explicit multi-PR OR agent-detected size/breadth), gate requirements, and verification acceptance criteria (positive, detection, negative, per-unit content).
• duck-tidy extras skill (stub): audit-first cleanup for stale/outdated comments and non-CONTEXT docs. Installed with --extras / -Extras. Evidence rules: contradicts current code, describes removed behavior, worktree-only add/remove never merged. Carve-outs: TODO markers (duck-debt), ADR/design notes flag-only, CONTEXT.md/.duck-tape (duck-tape). Method bodies pending.
• duck-adventure easter-egg skill (manual install): standalone rogue game — multi-turn dungeon crawls with maps, dice combat, random merchants, loot, and achievements tracked across sessions. Fun for its own sake; no handoff to productivity flows.

Changed

• Duckling silent-worker contract: duckling subagent redesigned as single-turn silent worker across all three harnesses (Claude Code, Copilot, OpenCode). Interactive mutating-action-gate include replaced by explicit Silent Worker Contract:
  • one invocation is one turn; no mid-run user dialog
  • never self-approve mutating work
  • execute mode produces terminal approval package (preflight + per-file diffs + Approve this scope?) instead of mutating the workspace
  • mid-run ambiguity flattens to ## Unresolved questions block instead of interactive Q&A
  • one phase per invocation; parent orchestrates phase progression
  • tool-unavailable degradation emits explicit ## Tool unavailable note instead of silent skip
• Duckling non-delegation list: duckling refuses skill_name of quack (routing skill), duck-tape (session-memory mutation), and duck-policy (session-scoped policy loader). Emits blocked_recursive_routing status; parent invokes target skill directly.
• DUCKLING_CTX footer status vocabulary expanded: added blocked_awaiting_approval, blocked_skill_unavailable, blocked_recursive_routing, blocked_missing_inputs, phase_complete_await_parent, degraded_tool_unavailable. Prior <ok|blocked> binary replaced.
• Rubber-duck Subagent Return Handling: new agent-body section defining shape-based and status-token-based recognition of subagent returns. Approval packages relayed verbatim as parent's Checkpoint 3 presentation; parent-always-executes rule (subagents propose; parent executes) preserves single-approval-gate invariant. Explicit handlers for phase-progression, blocked-input, and degraded returns.
• Quack subagent-runbook: explicit disclaimer that quack has no return-side responsibility; parent (rubber-duck) owns return handling. Applies to any primary agent that dispatches to duckling.
• Duckling general contract snippet (skill-snippets/duckling-general-contract.md): behavior rules 4-6 aligned with silent-worker posture. Interactive-dialog contracts (Socratic loops, batched interviews, multi-turn design dialogs) flatten questions to ## Unresolved questions. Skill-unavailable path emits terminal error instead of interactive question.
• Duckling harness permission tightening: silent-worker contract now enforced at harness level in all three harnesses. Duckling tool maps drop mutation tools: Claude Read, Glob, Grep, Skill; Copilot read,search; OpenCode edit: deny, bash: deny. Duckling body gains explicit never-call-Edit/Write/Bash rule and parent-always-executes wording. duck-patch and duck-refactor gain "Subagent execution mode" sections documenting approval-package output under subagent invocation. Permission-tightening spike resolved inline.
• duck-policy skill unchanged: portable policy layer stays agent-shape-agnostic; no duckling/quack-specific knowledge added.
• OpenCode plugin uses system-level directive injection (system prompt) instead of
  user-message injection, so the model treats the directive as an instruction
  rather than a suggestion.
• Sync replay fixes a latent off-by-one where extras were matched against the
  install-agents-md flag; extras and the new session-hook flag now map to the
  correct positional arguments.
• Validation suite: 58 tests (V01-V58). V54 covers the Checkpoint 1 plan-decomposition gate; V55 positive trigger, V56 negative non-trigger, V57 per-unit acceptance content, V58 implicit detection trigger extend decomposition coverage via the rollout fixture. V25/V26/V38/V54 signals calibrated to observed vocabulary.
• Validation runner now overlays built skills/ onto .agents/skills/ in test workspaces, so tests exercise current policy instead of the last installer-synced copy. Resolves false V58 failure caused by stale installed skills.
• duck-policy Method adds gate-sequencing rule: approach-choice, clarify-first, Checkpoint 1 framing, and Checkpoint 2 fire as separate turns; clarify completes before framing. V51 prompt specifies the JWT failure mode so the Checkpoint 2 selection ask is deterministic.
• docs/architecture/03-adaptive-socratic-policy.md Checkpoint 1 documents plan decomposition requirement.
• Legacy managed-block migration no longer writes a .bak.<timestamp> recovery copy next to AGENTS.md/CLAUDE.md. The 3.x migration window is closed; the installer strips legacy blocks in place without backup (bash + PowerShell parity).
• Rule wording convention applied across skills, agent bodies, and instruction docs: content-logic rules converted from absolute (always/never/must) to conditional if-then phrasing (~58 rules); structural/spec rules and safety carve-outs retain absolute or refusal form. Convention codified in duck-adapt (philosophy-core.md + adaptation-checklist.md).
• duck-policy Style: gate ask strings are contract exceptions to terse style — Confirm or revise?, Select an option., Approve this scope?, Accept, revise, or rollback? emitted verbatim at their checkpoints even when otherwise terse. Mitigates intermittent gate compression (V50/V51). Version bump v3.0.1 -> v3.0.2.
• duck-tape Resume: a marker from a previous session is a resumable handoff checkpoint, not a stop condition; stale markers now continue to checkpoint reload and position report. Version bump v2.1.2 -> v2.1.3.

Fixed

• Validation runner: verdict matching evaluates the full multi-turn transcript instead of the final turn only; gate content from earlier turns (V50 Checkpoint 1 framing) no longer yields false negatives.
• Validation runner: fixture workspaces no longer copy the rubber-duck AGENTS.md, removing workspace-identity confusion that intermittently made models ignore fixture code (V02/V07 class).
• Validation tests calibrated to gate sequencing: V08/V25 gained follow_ups to advance past approach-choice/clarify-first; V45 steps through approach-choice -> clarify -> evidence -> Checkpoint 1 frame, signals reduced to problem+assumption (options coverage stays with V51).
• Bash installer fails fast with a clear requires bash 4+ message (and macOS
  brew install bash guidance) instead of dying with an obscure
  declare: -A: invalid option on bash < 4 (macOS default /bin/bash 3.2).

Known regression

• None active. Intermittent failures under flash-class models remain (LLM non-determinism, documented suite limitation): V51 (selection ask occasionally omitted), V02/V07 (workspace identity confusion — mitigated by the fixture-workspace AGENTS.md exclusion), V19 (bug-signal calibration on a bug-free diff), V33/V55 (judge variance), V45 (follow-up brittleness vs question phrasing). Mitigations: union matcher, gate-sequence test calibration, fixture-workspace AGENTS.md exclusion. Suite nominal 52/58 under opencode-go/deepseek-v4-flash; no Critical behavioral regression observed.

v3.0.0

v3.0.0 — Flattened Duck

Consolidates the rubber-duck agent architecture around a single self-contained rubber-duck agent and moves the enforcement policy out of a managed block in AGENTS.md into a portable duck-policy skill loaded at agent session start. Installers, sync wrappers, tests, and docs updated to match. Also folds in remediations from a full duck-review of the branch.

Highlights

• Policy is now a skill. duck-policy (approval gates, safety carve-outs, Duck Ladder, style, deferred-debt markers) is portable and loadable by any agent. Rubber-duck agent body bootstraps it as its mandatory first action.
• AGENTS.md managed block retired. Installers strip legacy blocks on upgrade with a prominent notice and a timestamped backup preserving any user content that lived inside the block. Fresh installs no longer write policy into your AGENTS.md.
• Sync wrapper hardening. Version checks, scope-locked wrappers, portable substitution, and consistent bash/PowerShell parity.
• Validation suite expanded with checkpoint-4 fixture, security-vuln fixture, and context-loading fixture.

Breaking changes

• --claude-md / -ClaudeMd and --skip-agents-md / -SkipAgentsMd flags removed. CI or user aliases relying on these will fail hard. Deprecation stub deferred to a follow-up.
• --policy host|self flag removed.
• Legacy managed policy block in user AGENTS.md / CLAUDE.md is stripped on install. Backup written; migration is loud.
• Sync wrapper scope is embedded at install time. User-supplied --project / --global on the wrapper now errors instead of being silently filtered (PS) or triggering installer parse errors (bash). Re-run the installer to change scope.

Migration guide

1. Run the installer as usual.
2. On first upgrade, watch for the Legacy managed policy block detected (3.x migration) notice. Your AGENTS.md will be backed up next to itself as AGENTS.md.bak.<timestamp> before the block is removed.
3. If you had CI aliases using removed flags, drop them.
4. Update any custom scripts that expected wrapper scope override to instead re-run the installer with the desired scope.

Architecture changes

• Single self-contained rubber-duck agent (no more reliance on AGENTS.md for rules).
• Agent body includes duck-policy snippet at build time.
• Installer templates reorganized under src/install/scripts/ and src/install/templates/.
• Build flow: src/agents/* → dist/*; src/skills/* → skills/*. Never edit generated outputs.

Installer + sync wrapper

• New sync-latest.{sh,ps1} helper installed alongside agents. Checks for newer versions before syncing; prompts on upgrade with CHANGELOG link.
• Bash + PowerShell installer parity tightened:
  • VERSION file format validated on both sides (^v\d+\.\d+\.\d+$)
  • Portable sync-wrapper token substitution (bash parameter expansion; no sed dependency; macOS-safe)
  • Get-SyncReplayArgs shape matches bash sync_replay_cmd (DRY dry-run + untrusted logic)
  • Doctor / doctor fail-fast when called before target resolve
  • Loud scope-collision reject in both wrappers
  • Version-check VERSION URL derives from installer URL (branch/custom raw-base aware)
• Sync wrappers embed RUBBER_DUCK_VERSION for diagnostics.
• Fallback wrapper templates removed; installer errors clearly if the template cannot be fetched.

Fixes bundled

• Legacy managed-block migration UX: loud notice, backup preserves user content, no spurious backups on fresh install
• Bash sync wrapper version comparison POSIX-compatible; incomparable pre-release strings no longer crash
• PS host detection uses (Get-Process -Id $PID).Path (previous automatic-variable reference was inert)
• running_piped() definition ordering fix
• CI line-ending drift resolved for *.ps1

Full Changelog: v2.1.4...v3.0.0

v2.1.4

What's Changed

• 2.1.4 - Agent rules consolidation by @sprngr in #23

Full Changelog: v2.1.3...v2.1.4

v2.1.3

Rubber Duck v2.1.3 - 2026-08-14 - Quack Fixes

Changed

• Quack routing language is now harness-agnostic for delegated execution:
  • Replaced OpenCode-specific task wording with generic subagent dispatch wording in source and generated skill artifacts.
  • Preserved existing routing behavior while removing tool-name coupling from skill text.
• Quack skill metadata version bumped to v2.1.3 in source-of-truth and regenerated artifact.
• Duck-grill close-out contract now aligns with duck-tape compaction expectations:
  • Added deterministic interoperability fields (Decision, Assumptions ledger status lines, deferred debt markers, position seed, compact-ready).
  • Added explicit follow-up prompt when compaction is ready (Run duck-tape merge now?).
• Duck-grill CONTEXT template now uses duck-tape schema-aligned section shape:
  • Contents, Goals, Decisions, Conventions, Glossary, Deferred-Debt, Open-Questions, Notes
  • Glossary entries retain richer domain metadata (Code, Scope, Aliases, Avoid).
  • Location guidance now sets canonical path to root CONTEXT.md.
• Project context debt tracking updated with linked spike marker:
  • TODO(architecture,#22): 2026-08-13 Define localized CONTEXT.md merge model for duck-tape

v2.1.2

Rubber Duck v2.1.2 — Patch Rollup

Changed

• duck-tape skill metadata bumped to v2.1.2 in source and regenerated artifact.
• Claude hook install guidance now supports repo-local .claude/settings.local.json (recommended) or .claude/settings.json.
• Claude troubleshooting guidance now validates both settings targets.
• Quick start now includes manifest-based update command: ./scripts/rubber-duck.sh sync --project.
• Edited skills aligned to project version v2.1.2 (duck-tape, duck-adapt, quack).

Fixed

• Clarified Claude hook setup docs to match repo-local config workflow.
• Replaced distributed src/skills/... references with .agents/skills/... in duck-tape hooks/docs and duck-adapt guidance.
• Harness artifact renderer now expands {{include: skill-snippets/...}} in agent bodies, removing leaked include tokens in rendered duckling dist artifacts.
• Quack boundaries now render safety carve-out snippet correctly (no leaked include token in built skill output).

Security

• Opencode duck-tape transcript snapshots now redact recursively before writing .duck-tape/-transcript.json, preventing raw secret leakage.
• Expanded redaction coverage across shell, PowerShell, and opencode plugin extract paths:
• password/passwd/pwd/secret/token/client_secret/private_key key-value forms
• credentialed connection URIs (scheme://user:pass@host)
• secret-like environment assignments (...PASSWORD=..., ...TOKEN=..., etc.)
• baseline PII shapes (email, phone, SSN)

Full Changelog: v2.1.1...v2.1.2

v2.1.1

What's Changed

• harden: tighten duck-tape transcript safety and duck-debt untrusted-content handling by @sprngr in #21
• Update instructions around installer scripts.

Full Changelog: v2.1.0...v2.1.1

v2.1.0

Rubber Duck v2.1.0

Installer overhaul, policy refinements, and full PowerShell parity.

Installer

• Multi-harness install via --harness opencode,claude,copilot / -Harness opencode,claude,copilot. One command, one banner, per-target [name] sections, single 🦆 quack footer.
• New sync action: manifest-driven install/prune across enabled targets. --prune / -Prune removes targets not enabled in manifest.
• Manifest schema v1 (.rubber-duck/manifest.json) tracks source, targets, and pins (sha256 change log). Reinstall skips unchanged files (mtime preserved).
• rawBase allowlist: installer only accepts sources under https://raw.githubusercontent.com/sprngr/rubber-duck unless --allow-untrusted-source / -AllowUntrustedSource is set. Prevents accidental fork/typo installs.
• PowerShell parity: -DryRun, -Prune, -Harness, -AllowUntrustedSource, script-scoped variables, hoisted security helpers.
• Consolidated output: banner + version: + source: + doctor: ok + skills printed once; per-target sections show only target-specific actions.
• Skills install consolidated: single npx call with one -a <agent> per selected target.
• Bash installer runtime floor: bash 4+, awk, curl, coreutils. python3 no longer required (pure-bash manifest library).
• Env var rename: BASH_SOURCE_URL → RUBBER_DUCK_SOURCE_URL (shell-agnostic naming, honored by both installers for branch auto-detect).
• Backup retention: only the most recent <file>.bak.* per policy file is kept; prior backups pruned on install/uninstall.
• --skip-agents-md / -SkipAgentsMd and --extras / -Extras flags exposed on both installers.

Policy & workflow

• Phase-gated approvals: preflight phase selection (stubs/skeleton/interfaces, wiring/integration, implementation), adaptive caps (6/4/2 files), objective review-fatigue thresholds using changed lines, mandatory re-approval between phases.
• New-file bootstrap rule: new feature files must land as stub/skeleton first, implementation in later phases.
• Docs-as-semantic default: documentation/planning edits treated as semantic changes (preflight + diff + approval); typo-only fixes in non-code text files remain lightweight.
• Approval intent: approve, approved, ok, go ahead, confirm all accepted (examples explicitly non-exhaustive).

Skills

• Skill metadata versioning aligned to RUBBER_DUCK_VERSION format (vX.Y.Z) across all skills.
• quack no longer stalls after routing.
• duck-tape session-id handling hardened; rotation metadata no longer persisted to CONTEXT.md.
• Cross-skill policy consistency pass: removed fixed file-count gating, aligned mutating workflows to phase-gated approvals.

Validation

• Suite expanded to V01–V35; V14 realigned to phase-cap boundary; V30 accepts clear approval intent; V32/V33 cover missing phase preflight and re-approval between phases.
• New V34/V35 cover documentation-as-semantic gate and typo-only cosmetic exception.

Tests & tooling

• Installer test suite with bash + PowerShell parity (8/8 each): fresh install, reinstall pin verify, sync round-trip, rawBase allowlist, claude two-file layout, dry-run no writes, dry-run multi-target layout, sync default source.
• Guardrails drift check now fails on duplicate headings in generated dist/**/*.md (catches nested-include composition regressions).
• markdownlint-cli2 wired into local pre-commit hook.
• Assembly renderers support nested embedded {{include: ...}} in both skill and harness pipelines.

Fixes

• Installer --raw-base no longer silently overwritten by branch default.
• PowerShell sync -Prune no longer returns early with no enabled targets.
• PowerShell security helpers (Test-RawBaseAllowed, Get-Sha256) hoisted to script scope so sync path enforces allowlist.
• Bash sync install loop under set -u no longer errors on empty enabled-targets array (bash 3.2).
• Managed block upsert no longer accumulates blank lines above fences.
• PowerShell script-file execution detection fixed for -Source local.
• PowerShell local-source file resolution uses script-scoped variables.
• Installer sync no longer fails with default source (RAW_BASE ordering fix).
• write_pins / Write-Pins now honor dry-run.
• dist/*/agents/rubber-duck.md no longer duplicates approval-workflow sections.

Full Changelog: v2.0.1...v2.1.0

v2.0.1

What's Changed

Patch release: duck-tape opencode plugin hook hardening.

Fixed

• Path traversal in opencode.plugin.js — strict sessionId charset validation (alphanumeric + hyphen, max 128 chars) before filename construction. Prevents ../-style traversal attacks on state file paths.
• Windows filename safety — stamp format changed from HH:MM to HHMM (colon stripped), matching skill's <YYYY-MM-DD-HHMM> session ID format. Colons invalid in Windows filenames.
• Rotation off-by-one — cap now enforces 10 total state files (was allowing 11). Eviction precedence: auto, then recovered, then manual.
• Rotation comment aligned with actual behavior.
• Tests added — sessionId traversal guard, extraction edge cases (<-prefixed user text skip, multiple DECISION_PATTERN variants, lastText assignment, null-info guards).

Changed

• [Unreleased] entries folded into v2.0.0 (changelog hygiene).

Full Changelog: v2.0.0...v2.0.1

v2.0.0

Quackening

Major release: validation framework, UX standardization, agent consolidation, new skills, installer features, and documentation refinement.

Highlights

Agent consolidation

6 specialized duckling subagents collapsed into a single duckling delegator with skill-based routing (-1,797 lines). Simpler mental model, fewer moving parts, same coverage.

New skills

• duck-refactor — Multi-file restructuring (extract/rename/move/inline/pattern-convert; max 5 files)
• duck-adapt — Meta-skill for adapting external skills to Rubber Duck philosophy
• duck-grill — Deep interrogation with batched questions (up to 3), adversarial plan stress-testing
• duck-tape — Two-tier session memory (CONTEXT.md + state files)

Skill count: 11 -> 13. duck-explain merged into duck-teach.

Validation framework

31-test behavior regression suite with automated runner. Hybrid LLM-judge matcher handles vocabulary variance across model invocations. Quick subset (7 Critical/High tests) gates merges.

UX standardization

• Prompt-order standard across skills
• Duck Ladder 6-rung minimal-change discipline
• Two-tier approval gates: semantic (full 6-step) vs cosmetic (lightweight)
• Terse language policy: no invented abbreviations, no hedging, fragments OK

Installer

• --skip-agents-md — install skills only, preserve existing AGENTS.md
• --branch — install from non-main branches (testing)
• --extras — optional skills (duck-adapt, duck-grill, duck-tape)
• Bash and PowerShell feature parity
• AGENTS.md managed-block fencing

Policy

• 4-checkpoint decision policy: problem framing, solution selection, execution approval, acceptance
• Auto-Clarity: terse-by-default, expands when safety requires it
• Safety carve-outs (non-negotiable): trust boundaries, security controls, data-loss prevention, accessibility

Breaking changes

• 6 duckling subagents removed; replaced by single duckling delegator
• duck-explain merged into duck-teach
• Alias set trimmed 76 -> 33 (-57%)
• Decision-debt marker format: TODO(decision-debt) -> TODO(<debt type>)
• AGENTS.md managed-block fencing introduced

Migration

See migration guide for v1.x -> v2 upgrade steps.

Validation

Quick subset PASS (7/7, two consecutive runs). Full run log: validation/RUNLOG.md.

Full Changelog: v1.1.0...v2.0.0

v1.1.0

What's Changed

• v1.1 - optimizations & tweaks by @sprngr in #8
  • Implemented build system to share reused strings between skills and agents.
  • Fixed duck-debt to be deferred marker agnostic (TODO/FIXME/ETC)
  • Added deferred marker inclusion rule to the core AGENTS.md
  • Compacted prose for token usage, removed redundant rules.
  • Reorganized skills and agents for rules loading order.

Full Changelog: v1.0.0...v1.1.0