Make agent onboarding scope- and consent-driven

[bruno-archastro]

Review on ArchCode

Problem and author intent

Make public ArchDev skills follow explicit placement and organization-stream reporting consent instead of enabling global hooks merely because an agent loads a skill.

Previously, core/Tasks binary bootstrap also installed or refreshed user-wide hooks. A repository-only request could therefore change personal agent configuration and report unrelated sessions. Even removing setup from the scripts is insufficient with the old binary: its ordinary auth/Tasks pre-action self-heal can install missing global hooks.

The failing lifecycle is load skill → resolve binary → implicit global hooks → organization-visible activity without scope/reporting approval. The intended outcome is read install guide → ask and wait for placement/reporting approval → resolve a compatible personal binary → install only explicitly approved scoped hooks.

What changed

• README uses the single agent prompt, placement choices, visibility/approval, and personal sign-in outcomes. Technical commands remain in agent implementation references, not human onboarding.
• Core and Tasks Bash/PowerShell bootstrap are binary-only: no hook setup or refresh. Existing pinned installer bytes, SHA-256 verification, release checksum verification, personal paths, and persistent PATH/completion suppression remain intact.
• Both skills require a CLI with --local, marking the coordinated release with consent-safe self-heal; Tasks also verifies actual review-command help rather than accepting parent help. Unsupported releases stop without global fallback.
• Readiness follows the approved operation/scope. Model providers are optional; user-wide placement does not initialize shared repository configuration. Existing activity mapping is preserved rather than overwritten.
• Mapping documents all five shared hook paths and actual trust/reload limits. Repairs use scoped --refresh, preserving uninstall opt-outs. Separately approved reinstall targets one harness with --force only after executable/PATH verification.
• Bash help probes consume the entire stream to avoid grep -q/pipefail SIGPIPE causing unnecessary installs. Negative fixtures intercept downloads and cover missing capability and old versions for both skills.
• Existing bootstrap workflow now includes real released-CLI proofs on Linux and Windows. Configuration snapshots preserve profile/settings/opt-outs while excluding runtime logs/cache, and ordinary commands exercise Claude and Codex identities outside Factory.

Scope: agent skill/documentation and distribution test tooling; no product frontend or live infrastructure changes.

Released CLI compatibility

Source implementation: merged firstlanding PR 16001. Release PR 16116 published CLI v0.48.0 through the existing immutable-source, checksum, signing, platform smoke, and public Homebrew gates; all 17 release jobs passed.

The Linux and Windows released-CLI checks now both pass at head 7e32470. No check is excluded from readiness. Windows initially exposed a fixture-only failure: Windows PowerShell promoted the deliberately unauthenticated native probe's stderr to a fatal error. That invocation now temporarily uses Continue, captures and requires exit 1, and restores Stop in finally before every original placement/callback/settings/opt-out assertion. No capability fence or product behavior was relaxed.

All eight PR checks pass. This skills PR remains unmerged and still requires one human approval; CLI publication alone does not publish the updated skill files.

Risk and user impact

High consequence, medium uncertainty: installation guidance and ordinary-command compatibility affect whether session activity is disclosed to the organization outside approved scope. Binary-only bootstrap, capability fences, preserved settings, and explicit opt-out rules mitigate that mechanism. Released Linux/Windows process proofs pass; actual native-agent trust/discovery/coexistence remains unverified.

People paste one prompt into their coding agent. The agent asks where to configure ArchDev and whether to enable reporting. Binaries/authentication remain personal in both modes; repository files never authenticate teammates or silently install software.

Testing

• Canonical Linux process proof: scripts/test-skill-bootstrap-cli.sh, the full script target. A real CLI runs in an isolated HOME/Git checkout: core and Tasks resolve without hooks; ordinary Claude/Codex-marked auth/Tasks commands leave configuration unchanged; approved repository setup writes all five shared files; actual shell/Node callbacks deliver the workflow or missing-binary guidance; explicit personal setup preserves unrelated hooks; uninstall/skill reload preserves opt-out. Passed against the published v0.48.0 binary in automatic PR CI run 36779869152.
• Canonical Windows process proof: scripts/test-skill-bootstrap-cli.ps1, the full script target. Windows PowerShell resolves the real executable, isolates personal/repository files, executes the generated callback through cmd.exe, and asserts positive hook installation, missing-binary guidance, preservation, removal, and recorded opt-out. Passed against published v0.48.0 in automatic PR CI run 36779869152, including real cmd.exe callback execution and every preservation/opt-out assertion.
• scripts/test-skill-bootstrap.sh: 24 Bash cases passed, including verbose help, missing --local, old versions, all calling harnesses, and Factory/job markers. Fake tests intercept all installer downloads.
• scripts/test-skill-bootstrap.ps1: core/Tasks capability and no-hook fixtures run automatically on Ubuntu PowerShell and Windows PowerShell. Initial CI exposed negative-case exit-status handling and Linux's absent LOCALAPPDATA; follow-ups isolate installer paths, make child rejection explicit, and prevent an intentional negative-case exit from leaking into successful suite status. Current-head Ubuntu Bash/PowerShell and Windows PowerShell fixtures and both real released-CLI jobs pass.
• Rebased onto origin/main 40e0089, retaining upstream conditional reporting guidance and the fake CLI's 0.47.0 default. Independent read-only rebase review found no concrete source defects. All 24 Bash fixtures passed again; current-head Ubuntu Bash/PowerShell, Windows PowerShell fixtures, and installer smoke checks pass in automatic PR CI.
• Bash syntax and git diff --check passed. Two independent checkout reviews and follow-up reviews found no remaining concrete bugs after corrections. PowerShell was unavailable locally; no local Windows success is claimed.

Automatic execution

.github/workflows/skill-bootstrap-checks.yml runs on pull requests, pushes to main, and manual dispatch:

• skill-bootstrap: Bash plus Ubuntu PowerShell fixtures.
• skill-bootstrap-windows: Windows PowerShell fixtures.
• skill-bootstrap-cli: latest released Linux executable and real scope/callback proof.
• skill-bootstrap-cli-windows: latest released Windows executable and real cmd.exe callback proof.

The last two are release gates, not mocks. Installer Smoke Test remains unchanged. No companion checkout, credentials, or revision pin was added to firstlanding CI.

Follow-ups and limitations

• Compatible CLI v0.48.0 is published and actual released Linux/Windows proofs pass. Publishing the updated skill files still requires merging this PR after its human approval.
• Actual native coding-agent repository trust/activation and global/project coexistence remain outside these process proofs; the source PR tracks that boundary.
• No commits or setup files are installed automatically by bootstrap. No model-provider setup is required for reporting, no instruction-file breadcrumbs are added, and no persistent PATH changes are authorized implicitly.

Agent session: 01a0edbb-e6b3-7638-9df9-a756ca152a51