Merge pull request #56 from freshtechbro/codex/unify-workflow-output-roots

fix: unify workflow output roots

Author: freshtechbro

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.30] - 2026-05-16
+
+### Changed
+- Workflow-generated artifacts now use one output-root contract across CLI, daemon RPC, OpenCode direct tools, and provider workflows.
+- Omitted workflow outputs resolve under the project `.opendevbrowser/<workflow>/<uuid>` tree while preserving explicit output directories.
+
+### Fixed
+- Direct OpenCode-style workflow calls no longer drift into transient `/var/folders` or other process temp roots when `outputDir` is omitted.
+
 ## [0.0.21] - 2026-04-19
 
 ### Added

README.md

@@ -108,7 +108,7 @@ export CLAUDECODE_HOME="$ISOLATED_ROOT/claudecode-home"
 export AMP_CLI_HOME="$ISOLATED_ROOT/ampcli-home"
 cd "$WORKDIR"
 npm init -y
-npm install <public-repo-root>/opendevbrowser-0.0.29.tgz
+npm install <public-repo-root>/opendevbrowser-0.0.30.tgz
 npx --no-install opendevbrowser --help
 npx --no-install opendevbrowser help
 ```

docs/AGENTS.md

@@ -1,4 +1,4 @@
-# docs/ — Agent Guidelines
+# docs/ - Agent Guidelines
 
 Documentation source-of-truth scope. Extends root `AGENTS.md`.
 
@@ -64,7 +64,7 @@ When release-gate automation changes:
 - `docs/RELEASE_RUNBOOK.md`
 - `docs/EXTENSION_RELEASE_RUNBOOK.md`
 - `docs/DISTRIBUTION_PLAN.md`
-- the current version-scoped release evidence doc (for this release: `docs/RELEASE_0.0.27_EVIDENCE.md`)
+- the current version-scoped release evidence doc (for this release: `docs/RELEASE_0.0.30_EVIDENCE.md`)
 - older ledgers stay historical-only and should receive explicit status clarifications only
 - automation scripts:
   - `scripts/audit-zombie-files.mjs`

docs/ARCHITECTURE.md

@@ -459,7 +459,7 @@ When hub mode is enabled, the hub daemon is the **sole relay owner** and enforce
 - **Parity gate** via `tests/parity-matrix.test.ts` (contract coverage for CLI/tool/runtime surface checks + mode coverage).
 - **Provider performance gate** via `tests/providers-performance-gate.test.ts` (deterministic fixture SLO checks).
 - **Strict live release gates** via `node scripts/provider-direct-runs.mjs --release-gate` and `node scripts/live-regression-direct.mjs --release-gate` (active live release proof layer).
-- **Release checklist** in `docs/RELEASE_RUNBOOK.md` with evidence tracking in the current version-scoped release ledger (for this cycle: `docs/RELEASE_0.0.27_EVIDENCE.md`).
+- **Release checklist** in `docs/RELEASE_RUNBOOK.md` with evidence tracking in the current version-scoped release ledger (for this cycle: `docs/RELEASE_0.0.30_EVIDENCE.md`).
 - **Benchmark fixture manifest** in `docs/benchmarks/provider-fixtures.md`.
 - **First-run onboarding checklist** in `docs/FIRST_RUN_ONBOARDING.md`.
 

docs/CLI.md

@@ -61,7 +61,7 @@ export CLAUDECODE_HOME="$ISOLATED_ROOT/claudecode-home"
 export AMP_CLI_HOME="$ISOLATED_ROOT/ampcli-home"
 cd "$WORKDIR"
 npm init -y
-npm install <public-repo-root>/opendevbrowser-0.0.29.tgz
+npm install <public-repo-root>/opendevbrowser-0.0.30.tgz
 npx --no-install opendevbrowser --help
 npx --no-install opendevbrowser help
 ```
@@ -550,7 +550,7 @@ Wrapper behavior:
 - Render modes for `research`, `shopping`, and `inspiredesign` are shared: `compact|json|md|context|path`.
 - Successful research, shopping, inspiredesign, and product-video artifact-bearing outputs include `artifact_path`.
 - `inspiredesign run` returns a reusable design contract plus a Canvas-first handoff bundle; `--include-prototype-guidance` adds prototype structure guidance to the same workflow output.
-- Path-bearing workflow outputs persist artifacts under the explicit `--output-dir` when provided and include TTL metadata in manifest files. The CLI rejects blank `--output-dir` values and resolves relative paths from the invocation directory before daemon dispatch. When `--output-dir` is omitted, research, shopping, inspiredesign, and product-video asset packs write to `.opendevbrowser/<namespace>/<runId>` from the current workspace. Namespaces are `research`, `shopping`, `inspiredesign`, and `product-video`. Direct tool or daemon callers should pass an absolute output directory when they need caller-specific placement.
+- Path-bearing workflow outputs persist artifacts under the explicit `--output-dir` when provided and include TTL metadata in manifest files. The CLI rejects blank `--output-dir` values and resolves relative paths from the invocation directory before daemon dispatch. When `--output-dir` is omitted, research, shopping, inspiredesign, and product-video asset packs write to `<invocation-or-workspace-root>/.opendevbrowser/<namespace>/<runId>`. CLI runs use the process invocation directory, while direct OpenCode tools and daemon direct RPC use the workspace root equivalent from `core.cacheRoot`. Namespaces are `research`, `shopping`, `inspiredesign`, and `product-video`. Direct tool or daemon callers can still pass an explicit output directory for caller-specific placement.
 - Workflow cookie policy defaults to `providers.cookiePolicy=auto` and source defaults to `providers.cookieSource` (`file`, `env`, or `inline`).
 - Effective policy precedence is `--cookie-policy-override`/`--cookie-policy` > `--use-cookies` > config defaults.
 - `auto` attempts injection when cookies are available and continues when cookies are missing/unusable.
@@ -582,7 +582,7 @@ Script helper:
 
 Notes:
 - `--expired-only` is required.
-- Default cleanup root is `${TMPDIR:-/tmp}/opendevbrowser`. To clean workspace-local workflow artifacts, pass `--output-dir ./.opendevbrowser`.
+- Default cleanup root is `${TMPDIR:-/tmp}/opendevbrowser`. This helper cleanup default is separate from omitted workflow output roots. To clean workspace-local workflow artifacts, pass `--output-dir ./.opendevbrowser`.
 - Output includes `removed` and `skipped` run paths.
 
 ### Run (single-shot script)
@@ -1756,7 +1756,7 @@ npm run test -- tests/providers-performance-gate.test.ts
 
 These commands are release guards, not the live release-proof lane. Use the direct-run harness commands above for release evidence.
 
-Release gate source of truth: `docs/RELEASE_RUNBOOK.md` and `docs/RELEASE_0.0.28_EVIDENCE.md`.
+Release gate source of truth: `docs/RELEASE_RUNBOOK.md` and `docs/RELEASE_0.0.30_EVIDENCE.md`.
 Benchmark fixture manifest: `docs/benchmarks/provider-fixtures.md`.
 
 ---

docs/FIRST_RUN_ONBOARDING.md

@@ -27,7 +27,7 @@ This guide is the shipping checklist for validating OpenDevBrowser as a new user
 ```bash
 cd <public-repo-root>
 npm pack
-# -> opendevbrowser-0.0.29.tgz
+# -> opendevbrowser-0.0.30.tgz
 ```
 
 ## 2) Simulate a brand-new isolated user workspace
@@ -44,7 +44,7 @@ export AMP_CLI_HOME="$WORKROOT/amp-home"
 mkdir -p "$WORKDIR" "$HOME" "$OPENCODE_CONFIG_DIR" "$OPENCODE_CACHE_DIR" "$CODEX_HOME" "$CLAUDECODE_HOME" "$AMP_CLI_HOME"
 cd "$WORKDIR"
 npm init -y
-npm install <public-repo-root>/opendevbrowser-0.0.29.tgz
+npm install <public-repo-root>/opendevbrowser-0.0.30.tgz
 npx --no-install opendevbrowser version --output-format json
 ```
 

docs/README.md

@@ -34,7 +34,9 @@ Generated help is the canonical first-contact discovery surface and must keep th
 
 ## Version-scoped evidence
 
-- `<public-repo-root>/docs/RELEASE_0.0.27_EVIDENCE.md` - current release evidence ledger for the active ship cycle
+- `<public-repo-root>/docs/RELEASE_0.0.30_EVIDENCE.md` - current release evidence ledger for the active ship cycle
+- `<public-repo-root>/docs/RELEASE_0.0.28_EVIDENCE.md` - historical v0.0.28 release evidence ledger
+- `<public-repo-root>/docs/RELEASE_0.0.27_EVIDENCE.md` - historical v0.0.27 release evidence ledger
 - `<public-repo-root>/docs/RELEASE_0.0.26_EVIDENCE.md` - historical v0.0.26 release evidence ledger
 - `<public-repo-root>/docs/RELEASE_0.0.21_EVIDENCE.md` - historical v0.0.21 release evidence ledger
 - `<public-repo-root>/docs/RELEASE_0.0.20_EVIDENCE.md` - historical v0.0.20 release evidence ledger

docs/RELEASE_0.0.30_EVIDENCE.md

@@ -0,0 +1,113 @@
+# v0.0.30 Release Evidence
+
+Status: active release ledger
+Target release date: 2026-05-16
+Target tag: `v0.0.30`
+
+## Scope
+
+Tracks the `0.0.30` release cycle for uniform workflow output roots across CLI, daemon RPC, OpenCode direct tools, and provider workflow fallbacks.
+
+## Reference State
+
+- Previous npm `latest`: `0.0.29`
+- Previous GitHub release: `v0.0.29`
+- Release branch: `codex/unify-workflow-output-roots`
+- Target tag: `v0.0.30`
+- GitHub release workflow: `.github/workflows/release-public.yml`
+- Repository secret preflight: `NPM_TOKEN` is configured.
+
+## Release Delta
+
+- Omitted generated workflow output roots now resolve to `<cli cwd>/.opendevbrowser/<workflow>/<uuid>` for CLI invocations.
+- OpenCode direct tools and raw daemon RPCs now resolve omitted workflow output roots from the project workspace root instead of transient process temp directories.
+- Explicit `outputDir` values remain preserved across CLI, direct tools, daemon RPC, and provider workflow calls.
+- Low-level non-workflow artifact fallback and screencast replay defaults remain unchanged.
+
+## Version Alignment
+
+- `package.json`: `0.0.30`
+- `package-lock.json`: `0.0.30`
+- `extension/package.json`: `0.0.30`
+- `extension/manifest.json`: `0.0.30`
+
+## Mandatory Local Release Gates
+
+- [x] `npm run extension:sync`
+- [x] `npm run version:check`
+- [x] `npm run test:release-gate`
+- [x] `node scripts/audit-zombie-files.mjs`
+- [x] `node scripts/docs-drift-check.mjs`
+- [x] `node scripts/chrome-store-compliance-check.mjs`
+- [x] `./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh`
+- [x] `npx opendevbrowser --help`
+- [x] `npx opendevbrowser help`
+- [x] `npm run lint`
+- [x] `npm run typecheck`
+- [x] `npm run test`
+- [x] `npm run build`
+- [x] `npm run extension:build`
+- [x] `npm run extension:pack`
+- [x] `npm pack --pack-destination /tmp`
+
+## Optional Strict Live Gates
+
+- [ ] Deferred unless explicitly required for this release:
+  - `node scripts/provider-direct-runs.mjs --release-gate --out artifacts/release/v0.0.30/provider-direct-runs.json`
+  - `node scripts/live-regression-direct.mjs --release-gate --out artifacts/release/v0.0.30/live-regression-direct.json`
+
+## Implementation Proof
+
+- [x] Progressive RepoPrompt review loop completed.
+  - First review found P2 test coverage gaps for direct and daemon roots; fixed.
+  - Second review found an unrelated screencast assertion hunk; removed.
+  - Third review had no actionable P0/P1/P2 findings.
+- [x] Focused workflow test suite passed after review.
+  - Command: `npm run test -- tests/tools-workflows.test.ts tests/daemon-commands.integration.test.ts tests/cli-workflows.test.ts tests/providers-artifacts-workflows.test.ts tests/providers-inspiredesign-workflow.test.ts`
+  - Result: 5 files passed, 196 tests passed.
+- [x] Pre-release full test gate passed before version bump.
+  - Command: `npm run test`
+  - Result: 271 files passed, 1 skipped; 4414 tests passed, 1 skipped; all-files coverage 98.22% statements, 97% branches, 97.95% functions, 98.28% lines.
+- [x] Live workflow output validation passed before version bump.
+  - CLI managed runs for research, shopping, inspiredesign, and product-video wrote under `.opendevbrowser/<workflow>/<uuid>`.
+  - Direct OpenCode-style tool runs from `/var/folders/.../odb-direct-tool-cwd-*` wrote under the repo `.opendevbrowser`, not the temp cwd.
+  - Raw daemon RPC runs wrote under the repo `.opendevbrowser/<workflow>/<uuid>`.
+  - Explicit output roots were preserved across CLI, daemon RPC, and direct tool runs.
+
+## Local Release Gate Results
+
+- `npm run extension:sync`: synced `extension/manifest.json` and `extension/package.json` to `0.0.30`.
+- `npm run version:check`: passed, version `0.0.30`.
+- `node scripts/audit-zombie-files.mjs`: passed, scanned 1028 files, flagged none.
+- `node scripts/docs-drift-check.mjs`: initially failed because `README.md` still referenced `opendevbrowser-0.0.29.tgz`; after updating that stale reference, rerun passed.
+- `node scripts/chrome-store-compliance-check.mjs`: passed, manifest version `0.0.30`.
+- `./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh`: passed, 22 referenced files present, 10 JSON templates parsed.
+- `npm run test:release-gate`: passed all five groups.
+  - Group 1 `provider-direct-contracts`: 2 files passed, 99 tests passed.
+  - Group 2 `live-direct-regression-contracts`: 3 files passed, 37 tests passed.
+  - Group 3 `cli-help-parity`: 1 file passed, 15 tests passed.
+  - Group 4 `docs-and-zombie-audits`: 2 files passed, 5 tests passed.
+  - Group 5 `chrome-store-compliance`: 1 file passed, 1 test passed.
+- `npx opendevbrowser --help`: passed, wrote 798 lines to `/tmp/odb-help-0.0.30.txt`.
+- `npx opendevbrowser help`: passed, wrote 798 lines to `/tmp/odb-help-command-0.0.30.txt`.
+- `npm run lint`: passed.
+- `npm run typecheck`: passed.
+- `npm run build`: passed.
+- `npm run extension:build`: passed.
+- `npm run test`: passed, 271 files passed, 1 skipped; 4414 tests passed, 1 skipped; all-files coverage 98.22% statements, 97% branches, 97.95% functions, 98.29% lines.
+- `npm run extension:pack`: passed, produced `opendevbrowser-extension.zip`.
+- `shasum -a 256 opendevbrowser-extension.zip`: `d794bd052e3e01ab6bb84d99f983e36faa989afd7e1e42128634111043773a75`.
+- `npm pack --pack-destination /tmp`: passed, produced `/tmp/opendevbrowser-0.0.30.tgz`; package size 2.3 MB, unpacked size 11.6 MB, total files 1218, shasum `af40f0b5b41da820db34af604bfbf49bf150892e`.
+
+## External Release Workflow Evidence
+
+- [ ] Release workflow run URL
+- [ ] npm publish verification
+- [ ] Registry consumer smoke
+- [ ] GitHub release URL
+- [ ] GitHub release asset verification
+
+## Notes
+
+- Strict live gates are separate from release quality gates. They remain deferred for this release unless explicitly enabled.
+- If GitHub Actions npm publication fails despite `NPM_TOKEN` being configured, local authenticated npm publish is available as fallback and must be recorded here.

docs/SURFACE_REFERENCE.md

@@ -2,7 +2,7 @@
 
 Source-accurate inventory for CLI commands, plugin tools, relay channel commands, flags, and modes.
 Status: active  
-Last updated: 2026-04-12
+Last updated: 2026-05-16
 
 This reference is intentionally exhaustive and should stay synchronized with:
 - `src/public-surface/source.ts`
@@ -221,6 +221,8 @@ Operational note:
 - `opendevbrowser_skill_list` - List available bundled and discovered skill packs. Tool-only.
 - `opendevbrowser_skill_load` - Load a specific skill pack locally without browser work. Tool-only.
 
+Workflow output note: omitted direct workflow tool output roots resolve through the workspace root to `.opendevbrowser/<workflow>/<runId>`. Explicit output roots are preserved as caller intent.
+
 ---
 
 ## Relay Channel Inventory