chore: added user policy reference doc and tweaked loadout docs - #1091
Conversation
📝 WalkthroughWalkthroughUpdates loadout documentation examples, removes outdated fields and variables, and adds a reference page describing ChangesLoadout documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Comment |
There was a problem hiding this comment.
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 `@docs/concepts/loadouts.md`:
- Line 120: Update the lifecycle-hook description in the loadouts concepts
documentation to match the canonical behavior in the reference loadouts
documentation: hooks are included in composition and recorded with the session,
but are not executed. Remove or revise the statement that hooks are excluded
from composition, preserving the surrounding declaration-format guidance.
In `@docs/reference/user-policy.md`:
- Line 37: Add a language identifier, preferably text, to the opening fenced
code block in the user policy documentation while preserving its contents and
closing fence.
- Around line 26-31: Resolve the contradiction between the package exemption
described near “Packages and lifecycle hooks” and the static-valued variable
behavior in the package allow-step section. Explicitly state whether static
package variables are subject to user-policy gating, then revise both
explanations consistently while preserving the documented treatment of packages,
file patches, and host-derived environment variables.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: ab6e2baf-fc46-4bd7-857e-04e94fb1c703
📒 Files selected for processing (4)
docs/concepts/loadouts.mddocs/reference/loadouts.mddocs/reference/manifest.jsondocs/reference/user-policy.md
| > **Coming soon.** Lifecycle hooks are not yet live: a hook declared in a | ||
| > loadout is accepted, but the current release excludes it from composition | ||
| > and nothing executes it. The declaration format below is what will ship. | ||
| > and nothing executes it. The declaration format below is what we expect to ship. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Align lifecycle-hook status with the reference page.
This says hooks are excluded from composition, but docs/reference/loadouts.md Lines 218-219 says they are composed and recorded with the session but not executed. Document one canonical behavior.
Proposed wording
-> and nothing executes it. The declaration format below is what we expect to ship.
+> but it is not executed. The declaration format below is what we expect to ship.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| > and nothing executes it. The declaration format below is what we expect to ship. | |
| > but it is not executed. The declaration format below is what we expect to ship. |
🤖 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 `@docs/concepts/loadouts.md` at line 120, Update the lifecycle-hook description
in the loadouts concepts documentation to match the canonical behavior in the
reference loadouts documentation: hooks are included in composition and recorded
with the session, but are not executed. Remove or revise the statement that
hooks are excluded from composition, preserving the surrounding
declaration-format guidance.
| Packages and lifecycle hooks are not gated by the user policy as they do not request user data. | ||
|
|
||
| Packages are effectively out of scope. A package cannot supply file | ||
| patches, nor environment variables that carry host data (values inherited from | ||
| your shell); Because packages cannot transfer host data into a session, the policy's protective | ||
| purpose does not apply to them. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Resolve the contradictory package-policy semantics.
Lines 26-31 say packages are not gated by user policy, while Lines 163-165 say a package can reach the policy allow step through a static-valued variable. Clarify whether static package variables are gated, then update the surrounding explanation consistently.
Based on the supplied policy reference text.
Also applies to: 163-165
🤖 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 `@docs/reference/user-policy.md` around lines 26 - 31, Resolve the
contradiction between the package exemption described near “Packages and
lifecycle hooks” and the static-valued variable behavior in the package
allow-step section. Explicitly state whether static package variables are
subject to user-policy gating, then revise both explanations consistently while
preserving the documented treatment of packages, file patches, and host-derived
environment variables.
|
|
||
| A single TOML file, beside your client [`config.toml`](./loadouts.md#client-config): | ||
|
|
||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add a language to this fenced code block.
The path-only fence triggers markdownlint MD040. Use text (or another appropriate language) after the opening fence.
Based on the markdownlint-cli2 warning.
🧰 Tools
🪛 markdownlint-cli2 (0.23.1)
[warning] 37-37: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 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 `@docs/reference/user-policy.md` at line 37, Add a language identifier,
preferably text, to the opening fenced code block in the user policy
documentation while preserving its contents and closing fence.
Source: Linters/SAST tools
Added reference docs for user policies and made some slight tweaks to loadout docs.
Note
Add
user_policy.tomlreference doc and update loadout documentation examplesuser_policy.toml: file location, schema for[vars]and[patches](allow/deny/ignore glob lists), origin semantics, interactive prompting, and non-interactive behavior.TERM/COLORTERMvariable entries and trims the lifecycle hooks example.Macroscope summarized 9a14d89.
Summary by CodeRabbit
user_policy.toml, including variable and file-patch rules, prompts, enforcement behavior, and troubleshooting guidance.