docs: design a re-runnable machine profile and place it in claude-ops

[kyle-sexton]

Refs #4666

Summary

Owner decision (2026-09-29) on #4666 narrowed option 2 to a design doc first. This adds that design doc and the ADR-style placement record. It changes no setup contract, no invocation-mode class and no plugin. The issue stays open: acceptance criteria 4-6 need the built skill, and the invocation-mode change in criterion 1 waits on the owner's later decision.

Fix

• docs/specs/machine-profile-design.md: storage location, per-domain document shape, the default-verified / default-unexamined verdict vocabulary, and the manual-change policy, plus the reuse boundary with machine-health.
• docs/adr/0041-place-the-machine-profile-as-a-claude-ops-skill.md: placement decision relative to machine-health.
• Touches neither docs/out-of-scope/machine-profile.md nor PR docs: remove agent-encoded decisions and correct decision records #5288 (that PR only corrects facts in the park doc), so the two do not conflict.

Verification

• git merge origin/main: clean, no conflicts.
• scripts/check-changelog-parity.sh --check --check-order: pass.
• scripts/validate-plugins.sh: all manifests and the catalog validated.
• scripts/check-adr-numbers.sh: ADR numbers unique.
• scripts/check-docs-naming.sh: docs names lower-kebab-case.
• Docs only, so no plugin version bump, CHANGELOG entry or plugin tests apply.

Related

• feat(claude-ops): design a re-runnable machine profile for the setup skills #4666 (open; stays open)
• docs: remove agent-encoded decisions and correct decision records #5288 (owner's audit group, edits the park doc facts)

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-29T23:01:41.731084Z	c06c909	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c06c909d90

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

PR body contract — issue linkage

This PR body does not yet satisfy the issue-linkage contract:

• Missing a native closing keyword (Closes/Fixes/Resolves #N). If this PR references an issue it must not close, put "Refs: #N" (or "Relates to: #N") on its own line. If it relates to no GitHub issue at all, state "No linked issue" (or "No related issue:") in the body instead.

Edit the body and this comment updates itself on the next run.

[claude]

Claude finished @kyle-sexton's task in 4m 36s —— View job

---

Code review (/review:code-review)

• Gather context (PR diff, CLAUDE.md/AGENTS.md, existing review comments)
• Understand the request (/review:code-review lane per custom instructions)
• Review changed files for correctness/alignment issues
• Cross-check against existing Codex review findings (avoid duplicates)
• Post inline findings and summary

Summary

This is a docs-only design PR (docs/specs/machine-profile-design.md, docs/adr/0041-...md, docs/out-of-scope/machine-profile.md). Codex's five prior findings on this PR (npm HOME write isolation, unrepresentable default-unexamined records, the unreal gh cwd probe, the park-doc conflict, and placement appearing in both "accepted" and "open questions") were all already resolved by commit 5194b93, which I verified against the current diff — no need to re-raise those.

I independently cross-checked the design doc's citations against the conventions it cites (plugin-philosophy.md configuration-ownership table, config-cascade user-global layer and expression doctrine, plugin-data-report-keying rules 1/3/4, hook-config-delivery facts 5/8/9, and machine-health:audit's inherited-CLAUDE_PLUGIN_DATA hazard) — all check out accurately. The "Verification record" section's fleet counts (59 setup skills, 8 check skills/5 wrapping setup check, prerequisites manifests) are pinned to a specific commit with an explicit recheck-trigger list, which is the correct pattern for a fact that will drift; not a defect.

One finding posted inline (docs/specs/machine-profile-design.md:175): the Record schema (lines 124-129) has no field to hold what the blocked verdict's own "Requires" column demands (the guard and the operator command). The other three verdicts (set, default-verified, default-unexamined) each map onto an existing schema field — blocked is the one left with nowhere to put its data, the same class of gap the default-unexamined/skipped_because fix just closed for its sibling case.

No other high-confidence correctness issues found within this lane's scope (security findings, if any, are out of scope here per REVIEW.md, and none of the changes touch code with security-sensitive behavior anyway — this is a design record).

[claude]

Claude finished @kyle-sexton's task in 1m 43s —— View job

---

Security review (/review:security-review)

• Gather context (PR is docs-only: design doc + ADR + edit to out-of-scope doc)
• Invoked /review:security-review skill and followed its procedure
• Post findings

Scope reviewed (git diff across the three changed files, PR #5494, head 9d52ddc):

• docs/specs/machine-profile-design.md (new, design doc)
• docs/adr/0041-place-the-machine-profile-as-a-claude-ops-skill.md (new, ADR)
• docs/out-of-scope/machine-profile.md (edited: park record marked "superseded in part")

Result: no security findings.

This PR contains no executable surface — no code, scripts, CI workflow, or plugin manifest changes. It is a design document and an ADR that explicitly defer the build, the setup-contract change, and any invocation-mode amendment to a later owner decision (see "Out of scope until the later decision" in the design doc and the ADR's "Status scope" section). There is nothing here that runs, parses input, handles a credential, or touches a trust boundary yet.

Instruction-surface check. The edit to docs/out-of-scope/machine-profile.md softens a standing "Park. Do not build." record, which is exactly the shape this lane's instruction-surface lens exists to catch. I read docs/conventions/instruction-exception-register/README.md and checked the edit against its six protected classes (irreversible-action, secret-handling, data-integrity, external-publication, legal-compliance, agent-authority). The edit doesn't match any of them: the gate itself isn't removed, only re-pointed — the revised text still states "no machine-profile skill exists, no new plugin is added" until the owner rules on the new design doc (replacing the old dependency on issue #4240). No mechanism that currently blocks an action is weakened or deleted by this diff.

The earlier Codex review comments on this PR (npm HOME isolation, the gh per-tree probe, default-unexamined provenance, and superseding the park doc) all appear to have already been addressed in commit 5194b93 ("resolve machine-profile design review findings"), which is included in this head.
· branch docs/4666-machine-profile-design

[claude]

Claude finished @kyle-sexton's task in 57s —— View job

---

Security review (/review:security-review)

• Gather context (PR diff, CLAUDE.md/AGENTS.md, existing review comments)
• Check skip gate / whether prior review still applies to new head
• Review changed files for security-relevant surface
• Check instruction-surface lens against out-of-scope doc edit
• Post findings

Result: no security findings.

Scope reviewed: the incremental change on this push, commit 21e56e9 ("docs(claude-ops): add the guard field for the blocked verdict") against the previously-reviewed head 9d52ddc. The only diff is one line in docs/specs/machine-profile-design.md:

guard:        <blocked only: the guard and the operator command>,

This adds a schema field to the Record documentation block (responding to the earlier inline review comment that the blocked verdict had nowhere to put its guard/command data). It is pure prose describing a future field name — no executable surface, no change to docs/out-of-scope/machine-profile.md or the ADR, and no instruction-surface deletion/narrowing to check against the instruction exception register.

This PR remains docs-only overall (design doc + ADR + out-of-scope park-record edit), with the build, setup-contract change, and invocation-mode amendment all explicitly deferred to a later owner decision. My prior full-scope pass on this branch (head 9d52ddc) already covered the npm HOME isolation, gh per-tree config-dir, default-unexamined provenance, and park-doc supersession points Codex raised, and confirmed the docs/out-of-scope/machine-profile.md edit doesn't weaken any of the six protected classes in the instruction exception register — none of that changed in this push, so those conclusions still stand.
· branch docs/4666-machine-profile-design

[claude]

Claude finished @kyle-sexton's task in 2m 30s —— View job

---

Code review (/review:code-review)

• Gather context (PR diff, CLAUDE.md/AGENTS.md, existing review comments)
• Understand the request (/review:code-review lane per custom instructions)
• Review changed files for correctness/alignment issues
• Cross-check against existing Codex/Claude review findings (avoid duplicates)
• Post inline findings and summary

Summary

Docs-only PR (docs/specs/machine-profile-design.md, docs/adr/0041-...md,
docs/out-of-scope/machine-profile.md). This synchronize event's only new content since the
last code-review pass is commit 21e56e9, which adds a guard field to the Record schema
(docs/specs/machine-profile-design.md:128) — that's the fix for the one open finding from the
prior code-review run (the blocked verdict's "Requires: the guard and the operator command"
had no schema field to hold it). I checked it against the sibling fields it parallels
(supplied_by for set, observed_by for default-verified, skipped_because for
default-unexamined) and against every other guard/blocked mention in the file
(:156,
:161-163,
:176) — all consistent, no gap left open.

I re-read the full current diff against origin/main (all three files, not just the delta),
since I hadn't reviewed this specific head before:

• All five prior Codex findings (npm HOME isolation, unrepresentable default-unexamined,
  the unreal gh cwd probe, the park-doc conflict, placement in both "accepted" and "open
  questions") and the one prior Claude finding (the blocked/guard gap) are resolved in the
  current text, with no regression introduced by resolving one bumping into another.
• Verified factually rather than taken on trust: claude-ops ships both prerequisites
  (plugins/claude-ops/skills/prerequisites/SKILL.md) and inventory
  (plugins/claude-ops/skills/inventory/SKILL.md) as the ADR and design doc claim, and
  claude-config/claude-memory exist as the ADR's Context section describes.
• The diff stat (359 additions / 4 deletions across the three files) matches the PR's declared
  additions/deletions, so nothing outside the reviewed scope crept in.

No new high-confidence correctness or maintainability findings on this head. Nothing to post
inline.