Fix: make release guards consume release profile

[flyingrobots]

Summary

• add a typed .continuum/release.yml reader for release profile mechanics
• make scripts/release-guard.sh validate version sources and release docs from the profile instead of duplicated shell arrays
• make scripts/check-docs-topology.sh derive current docs from the profile and topic shelf
• declare yaml directly and test release-profile doc/version drift behavior

Closes #689.
Part of #693.

Validation

• npx vitest run test/unit/scripts/release-profile.test.ts
• npx vitest run test/unit/scripts/release-profile.test.ts test/unit/scripts/source-size-inventory-command.test.ts test/unit/scripts/pre-push-hook.test.ts
• npm run typecheck
• npm run lint
• npm run lint:docs-topology
• npm run release:guard -- --stage prep-pr
• pre-push IRONCLAD gate: passed on push

Summary by CodeRabbit

• New Features
  • Release validation now uses a centralized release profile to determine required documentation and to verify version lockstep across configured version sources.
  • Added enforcement to ensure designated version sources remain private during release checks.
• Bug Fixes
  • Improved detection and reporting for missing required documentation and version mismatches.
• Tests
  • Added unit tests covering release profile loading, required-docs collection, and version lockstep/privateness validation.
• Chores
  • Updated release tooling to derive required docs dynamically and added YAML support for the profile parser.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c3b71f87-bb75-4a1e-aaab-5137056fc0a0

📥 Commits

Reviewing files that changed from the base of the PR and between 99cebf9 and fd49240.

📒 Files selected for processing (2)

• scripts/release-profile.ts
• test/unit/scripts/release-profile.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• test/unit/scripts/release-profile.test.ts
• scripts/release-profile.ts

---

📝 Walkthrough

Walkthrough

Adds a YAML-backed release-profile CLI, uses it to derive required release-doc paths and version lockstep checks, and routes release-guard and docs-topology scripts through the new commands. Tests cover profile loading, doc paths, and version drift.

Changes

Release profile-driven guards

Layer / File(s)	Summary
Profile loading and doc paths package.json, scripts/release-profile.ts, test/unit/scripts/release-profile.test.ts	Adds YAML parsing support, release-profile validation/load helpers, doc-path collection, and Vitest coverage for profile loading and required-doc enumeration.
Version lockstep validation .continuum/release.yml, scripts/release-profile.ts, scripts/release-guard.sh, test/unit/scripts/release-profile.test.ts	Adds version-source expansion and lockstep failure collection, enforces private: true for workspace sources, and switches the release-guard version gate to the new CLI.
Doc requirement lookup scripts/check-docs-topology.sh, scripts/release-guard.sh, scripts/release-profile.ts	Replaces hardcoded release-doc arrays with required-docs output for docs-topology and release-evidence checks, and exposes the CLI command used by both scripts.

Release profile-driven guards

Layer / File(s)	Summary
Profile loading and doc paths package.json, scripts/release-profile.ts, test/unit/scripts/release-profile.test.ts	Adds YAML parsing support, release-profile validation/load helpers, doc-path collection, and Vitest coverage for profile loading and required-doc enumeration.
Version lockstep validation .continuum/release.yml, scripts/release-profile.ts, scripts/release-guard.sh, test/unit/scripts/release-profile.test.ts	Adds version-source expansion and lockstep failure collection, enforces private: true for workspace sources, and switches the release-guard version gate to the new CLI.
Doc requirement lookup scripts/check-docs-topology.sh, scripts/release-guard.sh, scripts/release-profile.ts	Replaces hardcoded release-doc arrays with required-docs output for docs-topology and release-evidence checks, and exposes the CLI command used by both scripts.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• git-stunts/git-warp#679: Also routes release guard and docs-topology checks through scripts/release-profile.ts, overlapping the same required-docs and version-source plumbing.
• git-stunts/git-warp#687: Also updates scripts/release-guard.sh and release-profile-driven release checks, overlapping the same guard integration path.

Poem

I sniffed the YAML by moonlight’s gleam,
And hopped through docs in a tidy stream.
The guard now listens to one shared song,
Where versions stay private and lockstep strong.
Binky! 🐇 The release path sings along.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: release guards now consume the release profile.
Description check	✅ Passed	The PR description covers summary and validation, and includes a same-repo issue reference, though it lacks an explicit Issue heading.
Linked Issues check	✅ Passed	The changes align with #689 by moving release-doc and version-source logic into the profile and adding tests for drift.
Out of Scope Changes check	✅ Passed	No clear out-of-scope changes are present; the added dependency, script, and tests all support the release-profile refactor.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch tooling/release-profile-guards

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Release Preflight

• package version: 18.1.2
• prerelease: false
• npm dist-tag on release: latest
• npm pack dry-run: passed
• jsr publish dry-run: passed

If this PR is from a release/* branch and merges to main, Release Autotag will run final preflight and create v18.1.2. A maintainer who is a JSR @git-stunts scope member must then dispatch the Release workflow manually.

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/check-docs-topology.sh`:
- Line 5: The REQUIRED_DOCS population in check-docs-topology.sh currently
trusts the output of node scripts/release-profile.ts required-docs without
verifying whether the command succeeded, which can leave the array empty and
skip validation; update the script to check the CLI exit status (or otherwise
fail fast) before using REQUIRED_DOCS, and ensure the topology check aborts with
a clear error if the release-profile command fails.

In `@scripts/release-guard.sh`:
- Around line 391-396: The release-doc check in the `required-docs` loop can
incorrectly pass when `node scripts/release-profile.ts required-docs` fails,
because the process substitution yields no paths and `missing` stays zero.
Update the release guard logic around the `while IFS= read -r path; do ... done`
block to capture the command’s exit status (or otherwise verify generation
succeeded) and fail the script immediately if `required-docs` cannot be
produced, so `REL-DOC-EVIDENCE` does not pass on a broken
`release-profile.ts`/CLI path.

In `@scripts/release-profile.ts`:
- Around line 145-160: The glob handling in expandVersionSourcePaths is still
hardcoded to a single repo-specific pattern, which defeats the profile-driven
design. Update the function to stop special-casing packages/*/package.json and
instead resolve supported version-source globs from the ReleaseVersionSource
data/profile itself, using expandVersionSourcePaths and the ReleaseProfileError
path only for truly unsupported patterns. Keep the directory scanning logic
generic enough that future profile-owned glob changes do not require code edits.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 69a0216b-a7fc-4d19-9251-46215db16abf

📥 Commits

Reviewing files that changed from the base of the PR and between fc4627e and d9589f2.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (6)

• .continuum/release.yml
• package.json
• scripts/check-docs-topology.sh
• scripts/release-guard.sh
• scripts/release-profile.ts
• test/unit/scripts/release-profile.test.ts

[github-actions]

Release Preflight

• package version: 18.1.2
• prerelease: false
• npm dist-tag on release: latest
• npm pack dry-run: passed
• jsr publish dry-run: passed

If this PR is from a release/* branch and merges to main, Release Autotag will run final preflight and create v18.1.2. A maintainer who is a JSR @git-stunts scope member must then dispatch the Release workflow manually.

[flyingrobots]

Code Lawyer Activity Summary

@codex please confirm no remaining release-profile guard blockers.

Source	Severity	File	Issue	Fix commit	Outcome
CodeRabbit	P2 Major	scripts/check-docs-topology.sh	Required-doc derivation could fail open when the profile CLI failed.	99cebf97	Fixed; review thread resolved.
CodeRabbit	P2 Major	scripts/release-guard.sh	Release evidence check could pass if required-docs generation failed.	99cebf97	Fixed; review thread resolved.
CodeRabbit	P2 Major	scripts/release-profile.ts	Version-source glob expansion was repo-specific instead of profile-owned.	99cebf97	Fixed; review thread resolved.
Self-audit	P2 Major	scripts/release-profile.ts	Profile input used parsed-object shape trust via type assertion/raw JSON parsing instead of runtime validation.	fd492408	Fixed with YAML/JSON AST-backed map/scalar validation.
Self-audit	P5 Nit	test/unit/scripts/release-profile.test.ts	Fixture helper used join(path, "..") instead of direct parent-directory intent.	fd492408	Fixed with dirname(path).

Local validation after fd492408:

• npx vitest run test/unit/scripts/release-profile.test.ts
• npm run typecheck
• npm run lint
• npm run lint:docs-topology
• npm run release:guard -- --stage prep-pr
• pre-push IRONCLAD gate: passed and push authorized

Current gate note: refreshed GitHub checks are running for fd492408; do not merge until CI and CodeRabbit both return green.

[github-actions]

Release Preflight

• package version: 18.1.2
• prerelease: false
• npm dist-tag on release: latest
• npm pack dry-run: passed
• jsr publish dry-run: passed

If this PR is from a release/* branch and merges to main, Release Autotag will run final preflight and create v18.1.2. A maintainer who is a JSR @git-stunts scope member must then dispatch the Release workflow manually.

[flyingrobots]

Code Lawyer Recheck

Second audit pass after fd492408 found no new blockers.

Severity	Count	Notes
P0 Critical	0	No correctness, data-loss, release-integrity, or security blockers found.
P1 High	0	No unresolved CI, thread, or fail-open release gate defects found.
P2 Major	0	Prior P2 findings remain fixed in 99cebf97 and fd492408.
P3 Minor	0	No additional maintainability issues worth holding this PR.
P4/P5 Nit	0	No remaining style nits requiring churn before merge.

Evidence checked:

• Worktree clean after git fetch origin --tags.
• GraphQL review-thread sweep: all PR threads resolved.
• gh pr checks: all checks passing, including CodeRabbit and Release Preflight.
• git diff --check origin/main...HEAD: clean.
• Local validation: npm run lint, npm run typecheck, npx vitest run test/unit/scripts/release-profile.test.ts, npm run lint:docs-topology, npm run release:guard -- --stage prep-pr.
• Policy scan of touched release-profile surface: no explicit JSON.parse, as, any, unknown, as any, or as unknown as introduced.

@codex confirm: no remaining release-profile guard blockers identified in this pass.