feat: diagnose Repository Skill Set readiness

[marcioaltoe]

Add offline Repository Skill Set readiness to Doctor and make its filesystem and external hash checks deterministic.

Summary

• Report Roundfix-owned and external Repository Skill Set readiness through roundfix doctor, with actionable remediation.
• Harden repository inspection against symlink escapes, propagate cancellation, and match the external Node CLI hash ordering contract.
• Reconcile the authorized Baseline skill snapshots, user documentation, shipped Roundfix skill, QA evidence, and follow-up Spec task graphs.
• Clarify the Doctor help contract after CodeRabbit review and lock the wording with an exact regression assertion.

Implementation notes

• Repository reads stay anchored to the Git root and reject symbolic-link authorities and ancestors.
• External skill hashes share one collation implementation backed by golang.org/x/text so Doctor and Baseline restoration cannot drift.
• CLI help, user guides, and the canonical and embedded Roundfix skills remain synchronized.

Verification

• rtk make verify — passed before publication and again in Roundfix Batch 001 after the review fix.
• rtk roundfix profiles validate --category review — passed for the preferred and fallback review selections.
• rtk roundfix watch --source coderabbit --pr 37 --until-clean — Round 001 resolved 1 issue, invalidated 3 with recorded reasons, and left 0 unresolved; Round 002 fetched 0 new issues.
• GitHub status rollup on 072ae5b reports CodeRabbit SUCCESS, both CI checks passed, and the PR is approved. Roundfix reported CleanUnverified because it did not observe that status within its grace window.
• rtk roundfix doctor — Node, acpx, adapter, and Codex checks passed; the full command reports the existing project frontend Claude profile as failed because its adapter evidence lacks config_options.

Risk and rollback

The highest-risk areas are external path collation and the derived Baseline catalog digests. Reverting this PR restores the prior Doctor surface and hash behavior together.

[coderabbitai]

Walkthrough

The PR adds Repository Skill Set readiness checks to roundfix doctor, introduces deterministic Unicode-aware skill hashing, updates related documentation and fixtures, expands doctor tests, and configures repository review tooling and profile fallback models.

Changes

Doctor skill readiness

Layer / File(s)	Summary
Readiness contract and guidance .agents/skills/roundfix/SKILL.md, CONTEXT.md, README.md, skills-lock.json, docs/specs/...	Documents Repository Skill Set authority, hash validation, output ordering, remediation commands, read-only behavior, and evidence data.
Deterministic skill digest compatibility internal/skillhash/*, internal/baseline/..., go.mod	Adds deterministic path/content hashing and updates dependent baseline, parity, and dependency data.
Doctor execution and result construction internal/cli/doctor.go, internal/cli/health.go, internal/cli/cli.go	Runs skill readiness between profile and Codex checks, handles missing Git roots, classifies failures, and updates help output.
Doctor behavior validation internal/cli/doctor_test.go, internal/cli/cli_test.go	Tests readiness results, ordering, context propagation, non-mutation, argument validation, profile behavior, and documentation contracts.

Go testing guidance

Layer / File(s)	Summary
Go test organization and assertion guidance .agents/skills/golang-testing/SKILL.md	Adds source-aligned test file and function ordering conventions and documents assertion scope handling in subtests.

Repository tooling configuration

Layer / File(s)	Summary
Review configuration and model fallbacks .coderabbit.yaml, .roundfixrc.yml	Adds CodeRabbit review settings and changes fallback models for general, backend, QA, and review profiles.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant Doctor
  participant HealthChecks
  participant RepositorySkills
  User->>Doctor: run doctor
  Doctor->>HealthChecks: run Node, ACPX, adapter, and profile checks
  Doctor->>RepositorySkills: check repository skill readiness
  RepositorySkills-->>Doctor: readiness status and remediation details
  Doctor->>HealthChecks: run Codex check
  Doctor-->>User: ordered one-line readiness results

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 2.70% 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
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding Repository Skill Set readiness diagnosis to doctor.

✨ 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 ma/0036-doctor-skill-readiness

---

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

[coderabbitai]

Actionable comments posted: 4

🤖 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 @.agents/skills/golang-testing/SKILL.md:
- Around line 143-170: Reframe the “Assert Scope Leaking into Subtests” section
to comply with the repository’s standard-library-only testing policy. Remove
Testify references and rewrite both examples and the verification guidance using
subtest-local testing.T methods such as t.Errorf or t.Fatalf, while preserving
the requirement that failures are attributed to the correct subtest.
- Around line 75-88: Specify the fenced code block in the documentation around
the test-file naming examples with the text language identifier, changing the
opening fence to ```text while preserving the filename mapping content.

In @.roundfixrc.yml:
- Line 20: Remove the concrete gpt-5.6-terra model assignments from all affected
Roundfix profiles in .roundfixrc.yml, including the entries referenced at lines
20, 29, 47, and 56. Keep the profiles capability-oriented and rely on
runtime-owned configuration for provider/model fallback resolution.

In `@internal/cli/cli.go`:
- Around line 3780-3782: Update the doctor help text near the readiness
description to remove the stray conjunction before “required Agent Selection
Profiles,” leaving the enumeration as “the effective adapter, required Agent
Selection Profiles, the Repository Skill Set, and codex runtime hygiene.”

🪄 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: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 9a919629-4649-4314-b5d7-4adaf5938ec1

📥 Commits

Reviewing files that changed from the base of the PR and between be9c42c and 9a6b7f9.

⛔ Files ignored due to path filters (100)

• docs/findings/2026-07-26-baseline-profile-refresh-retention-gap.md is excluded by none and included by none
• docs/findings/2026-07-26-claude-adapter-configoptions-migration.md is excluded by none and included by none
• docs/findings/2026-07-26-vortex-baseline-capability-remediation.md is excluded by none and included by none
• docs/specs/0036-doctor-skill-readiness/task_01.md is excluded by none and included by none
• docs/specs/0036-doctor-skill-readiness/task_02.md is excluded by none and included by none
• docs/specs/0037-terminal-outcome-integrity/_prd.md is excluded by none and included by none
• docs/specs/0037-terminal-outcome-integrity/_tasks.md is excluded by none and included by none
• docs/specs/0037-terminal-outcome-integrity/_techspec.md is excluded by none and included by none
• docs/specs/0037-terminal-outcome-integrity/task_01.md is excluded by none and included by none
• docs/specs/0037-terminal-outcome-integrity/task_02.md is excluded by none and included by none
• docs/specs/0037-terminal-outcome-integrity/task_03.md is excluded by none and included by none
• docs/specs/0037-terminal-outcome-integrity/task_04.md is excluded by none and included by none
• docs/specs/0037-terminal-outcome-integrity/task_05.md is excluded by none and included by none
• docs/specs/0037-terminal-outcome-integrity/task_06.md is excluded by none and included by none
• docs/specs/0037-terminal-outcome-integrity/task_07.md is excluded by none and included by none
• docs/specs/0038-terminal-run-worktree-reconciliation/_prd.md is excluded by none and included by none
• docs/specs/0038-terminal-run-worktree-reconciliation/_tasks.md is excluded by none and included by none
• docs/specs/0038-terminal-run-worktree-reconciliation/_techspec.md is excluded by none and included by none
• docs/specs/0038-terminal-run-worktree-reconciliation/task_01.md is excluded by none and included by none
• docs/specs/0038-terminal-run-worktree-reconciliation/task_02.md is excluded by none and included by none
• docs/specs/0038-terminal-run-worktree-reconciliation/task_03.md is excluded by none and included by none
• docs/specs/0038-terminal-run-worktree-reconciliation/task_04.md is excluded by none and included by none
• docs/specs/0038-terminal-run-worktree-reconciliation/task_05.md is excluded by none and included by none
• docs/specs/0038-terminal-run-worktree-reconciliation/task_06.md is excluded by none and included by none
• docs/specs/0038-terminal-run-worktree-reconciliation/task_07.md is excluded by none and included by none
• docs/specs/0039-review-source-evidence-and-detached-outcomes/_prd.md is excluded by none and included by none
• docs/specs/0039-review-source-evidence-and-detached-outcomes/_tasks.md is excluded by none and included by none
• docs/specs/0039-review-source-evidence-and-detached-outcomes/_techspec.md is excluded by none and included by none
• docs/specs/0039-review-source-evidence-and-detached-outcomes/task_01.md is excluded by none and included by none
• docs/specs/0039-review-source-evidence-and-detached-outcomes/task_02.md is excluded by none and included by none
• docs/specs/0039-review-source-evidence-and-detached-outcomes/task_03.md is excluded by none and included by none
• docs/specs/0039-review-source-evidence-and-detached-outcomes/task_04.md is excluded by none and included by none
• docs/specs/0039-review-source-evidence-and-detached-outcomes/task_05.md is excluded by none and included by none
• docs/specs/0039-review-source-evidence-and-detached-outcomes/task_06.md is excluded by none and included by none
• docs/specs/0039-review-source-evidence-and-detached-outcomes/task_07.md is excluded by none and included by none
• docs/specs/0039-review-source-evidence-and-detached-outcomes/task_08.md is excluded by none and included by none
• docs/specs/0039-review-source-evidence-and-detached-outcomes/task_09.md is excluded by none and included by none
• docs/specs/0042-verification-capacity-and-daemon-task-settlement/_prd.md is excluded by none and included by none
• docs/specs/0042-verification-capacity-and-daemon-task-settlement/_tasks.md is excluded by none and included by none
• docs/specs/0042-verification-capacity-and-daemon-task-settlement/_techspec.md is excluded by none and included by none
• docs/specs/0042-verification-capacity-and-daemon-task-settlement/task_02.md is excluded by none and included by none
• docs/specs/0042-verification-capacity-and-daemon-task-settlement/task_05.md is excluded by none and included by none
• docs/specs/0042-verification-capacity-and-daemon-task-settlement/task_06.md is excluded by none and included by none
• docs/specs/0042-verification-capacity-and-daemon-task-settlement/task_07.md is excluded by none and included by none
• docs/specs/0042-verification-capacity-and-daemon-task-settlement/task_08.md is excluded by none and included by none
• docs/specs/_archived/0036-doctor-skill-readiness/_prd.md is excluded by none and included by none
• docs/specs/_archived/0036-doctor-skill-readiness/_tasks.md is excluded by none and included by none
• docs/specs/_archived/0036-doctor-skill-readiness/_techspec.md is excluded by none and included by none
• docs/specs/_archived/0036-doctor-skill-readiness/qa/evidence/2026-07-26-doctor-skill-readiness/command-evidence.md is excluded by none and included by none
• docs/specs/_archived/0036-doctor-skill-readiness/qa/evidence/2026-07-26-doctor-skill-readiness/full-access-clean-flow.md is excluded by none and included by none
• docs/specs/_archived/0036-doctor-skill-readiness/qa/qa-report-2026-07-26-01-partial.md is excluded by none and included by none
• docs/specs/_archived/0036-doctor-skill-readiness/qa/qa-report-2026-07-26.md is excluded by none and included by none
• docs/specs/_archived/0036-doctor-skill-readiness/task_01.md is excluded by none and included by none
• docs/specs/_archived/0036-doctor-skill-readiness/task_02.md is excluded by none and included by none
• docs/specs/_archived/0036-doctor-skill-readiness/task_03.md is excluded by none and included by none
• docs/specs/_archived/0049-baseline-preservation-idempotency/_prd.md is excluded by none and included by none
• docs/specs/_archived/0049-baseline-preservation-idempotency/_tasks.md is excluded by none and included by none
• docs/specs/_archived/0049-baseline-preservation-idempotency/_techspec.md is excluded by none and included by none
• docs/specs/_archived/0049-baseline-preservation-idempotency/task_01.md is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/_prd.md is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/_tasks.md is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/_techspec.md is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/qa/evidence/2026-07-26-doctor-skill-readiness/command-evidence.md is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/qa/evidence/2026-07-26-doctor-skill-readiness/unicode-corpus/-a is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/qa/evidence/2026-07-26-doctor-skill-readiness/unicode-corpus/10-guide.md is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/qa/evidence/2026-07-26-doctor-skill-readiness/unicode-corpus/2-guide.md is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/qa/evidence/2026-07-26-doctor-skill-readiness/unicode-corpus/A.md is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/qa/evidence/2026-07-26-doctor-skill-readiness/unicode-corpus/_a is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/qa/evidence/2026-07-26-doctor-skill-readiness/unicode-corpus/nested/deeper/ß.md is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/qa/evidence/2026-07-26-doctor-skill-readiness/unicode-corpus/nested/z.md is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/qa/evidence/2026-07-26-doctor-skill-readiness/unicode-corpus/nested/É.md is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/qa/evidence/2026-07-26-doctor-skill-readiness/unicode-corpus/nested/ä.md is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/qa/evidence/2026-07-26-doctor-skill-readiness/unicode-corpus/é.md is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/qa/qa-report-2026-07-26.md is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/task_01.md is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/task_02.md is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/task_03.md is excluded by none and included by none
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/task_04.md is excluded by none and included by none
• docs/specs/_archived/0051-doctor-readiness-contract-reconciliation/_prd.md is excluded by none and included by none
• docs/specs/_archived/0051-doctor-readiness-contract-reconciliation/_tasks.md is excluded by none and included by none
• docs/specs/_archived/0051-doctor-readiness-contract-reconciliation/_techspec.md is excluded by none and included by none
• docs/specs/_archived/0051-doctor-readiness-contract-reconciliation/qa/evidence/2026-07-26-doctor-readiness-1736dbc/command-evidence.md is excluded by none and included by none
• docs/specs/_archived/0051-doctor-readiness-contract-reconciliation/qa/evidence/2026-07-26-doctor-readiness/command-evidence.md is excluded by none and included by none
• docs/specs/_archived/0051-doctor-readiness-contract-reconciliation/qa/qa-report-2026-07-26.md is excluded by none and included by none
• docs/specs/_archived/0051-doctor-readiness-contract-reconciliation/task_01.md is excluded by none and included by none
• docs/specs/_archived/0051-doctor-readiness-contract-reconciliation/task_02.md is excluded by none and included by none
• docs/specs/_archived/0051-doctor-readiness-contract-reconciliation/task_03.md is excluded by none and included by none
• docs/specs/_archived/0051-doctor-readiness-contract-reconciliation/task_04.md is excluded by none and included by none
• docs/specs/_archived/0051-doctor-readiness-contract-reconciliation/task_05.md is excluded by none and included by none
• docs/specs/_archived/0051-doctor-readiness-contract-reconciliation/task_06.md is excluded by none and included by none
• docs/user-guide/commands.md is excluded by none and included by none
• docs/user-guide/usage.md is excluded by none and included by none
• go.sum is excluded by !**/*.sum and included by go.sum
• internal/baseline/testdata/catalog.digest is excluded by !**/*.digest and included by none
• skills/baseline_skill_contract_test.go is excluded by !skills/** and included by **/*.go
• skills/repository.go is excluded by !skills/** and included by **/*.go
• skills/repository_test.go is excluded by !skills/** and included by **/*.go
• skills/roundfix/SKILL.md is excluded by !skills/** and included by none
• skills/skills.go is excluded by !skills/** and included by **/*.go
• skills/skills_test.go is excluded by !skills/** and included by **/*.go

📒 Files selected for processing (22)

• .agents/skills/golang-testing/SKILL.md
• .agents/skills/roundfix/SKILL.md
• .coderabbit.yaml
• .roundfixrc.yml
• CONTEXT.md
• README.md
• docs/specs/_archived/0050-doctor-skill-readiness-hardening/qa/evidence/2026-07-26-doctor-skill-readiness/unicode-skills-lock.json
• go.mod
• internal/baseline/assets/lock-hash-compatibility-v1.json
• internal/baseline/assets/setups/typescript-bun.json
• internal/baseline/skills_restore.go
• internal/baseline/testdata/catalog.normalized.json
• internal/baseline/testdata/parity-corpus/v1/fixtures/asset-sync.json
• internal/baseline/testdata/parity-corpus/v1/manifest.json
• internal/cli/cli.go
• internal/cli/cli_test.go
• internal/cli/doctor.go
• internal/cli/doctor_test.go
• internal/cli/health.go
• internal/skillhash/hash.go
• internal/skillhash/hash_test.go
• skills-lock.json

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

internal/cli/cli.go (1)

3781-3785: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Fix the malformed doctor help wording.

“The aggregate profiles: line exact-proves…” reads like an unfinished sentence and makes the profiles: report label unclear. Rewrite this as a direct description, such as “Profiles are exact-proved per distinct tuple. Skills compare …”.

🤖 Prompt for 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.

In `@internal/cli/cli.go` around lines 3781 - 3785, Rewrite the malformed doctor
help text near the aggregate profiles and skills description into complete,
direct sentences: clearly state that profiles are exact-proved per distinct
tuple, then retain the existing skills comparison behavior and artifact
distinctions. Keep the surrounding supported-version, adapter, and
runtime-hygiene wording unchanged.

Source: Coding guidelines

🤖 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.

Outside diff comments:
In `@internal/cli/cli.go`:
- Around line 3781-3785: Rewrite the malformed doctor help text near the
aggregate profiles and skills description into complete, direct sentences:
clearly state that profiles are exact-proved per distinct tuple, then retain the
existing skills comparison behavior and artifact distinctions. Keep the
surrounding supported-version, adapter, and runtime-hygiene wording unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 298be557-399f-418e-a315-a8d879e107c8

📥 Commits

Reviewing files that changed from the base of the PR and between 9a6b7f9 and 072ae5b.

⛔ Files ignored due to path filters (5)

• docs/specs/_reviews/pr-37/round-001/issue_001.md is excluded by none and included by none
• docs/specs/_reviews/pr-37/round-001/issue_002.md is excluded by none and included by none
• docs/specs/_reviews/pr-37/round-001/issue_003.md is excluded by none and included by none
• docs/specs/_reviews/pr-37/round-001/issue_004.md is excluded by none and included by none
• docs/specs/_reviews/pr-37/round-001/round.md is excluded by none and included by none

📒 Files selected for processing (2)

• internal/cli/cli.go
• internal/cli/cli_test.go