policy-matrix.md

Policy Matrix

This document is the source-of-truth matrix for ratchet-cli policy surfaces: permissions, sandboxing, trust, queue execution, extension points, and per-agent scope. It documents existing behavior and the boundaries required before broader automation such as arbitrary ACP scheduling or mutation-capable extension hooks.

Run ratchet policy matrix, ratchet policy matrix --json, or ratchet policy matrix --status deferred --json for a read-only CLI view of these supported, partial, explicit-operator, and deferred layers.

Scope

The matrix covers ratchet-cli-owned command, daemon, TUI, ACP client, MCP, team, and retro surfaces. It does not define a new policy evaluator. Trust matching, runtime trust decisions, and persistent trust grants continue to use workflow-plugin-agent/policy.TrustEngine and workflow-plugin-agent/policy.PermissionStore.

Non-Goals

• Arbitrary or scheduled ACP client execution beyond acknowledged per-session background drain.
• Config-file mutation from trust commands.
• New sandbox/path/network enforcement.
• Broad runtime extension SDK.
• Remote managed hook policy distribution or management APIs.
• Credentialed third-party agent CI.
• Go-native ACPX durable bundle compatibility is supported; .flow.ts source execution remains deferred.
• Local-first gateway or channel routing.

Policy Precedence

These rules describe the intended policy order for documented surfaces. Partial or deferred rows below must not be treated as fully enforced runtime behavior.

1. Managed hook policy applies after local source composition and hook trust; managed-only suppression and managed descriptor immutability cannot be relaxed locally.
2. Hard deny and missing authorization wins.
3. Persistent deny grants beat persistent allow grants.
4. Runtime deny rules beat runtime allow rules at the same scope.
5. Runtime rules can narrow current process behavior but are not durable.
6. Static config remains the daemon startup baseline.
7. Unknown or missing policy falls back to explicit prompt or deny, not silent auto-approval.

Layer Matrix

Layer	Owner	Status	Rule	Validation
Static config trust rules	internal/config plus workflow-plugin-agent/policy.TrustEngine	Supported	Config provides the daemon startup baseline for trust mode and rules. Runtime and persistent changes do not rewrite config.	Config and trust-engine tests; docs guard checks this layer name.
Runtime trust rules	Daemon RPC, CLI, and TUI trust commands	Supported	/mode, /trust allow, /trust deny, /trust list, ratchet trust allow, ratchet trust deny, and ratchet trust list mutate or inspect daemon-local runtime state.	Daemon trust tests and cmd/ratchet docs guard.
Persistent trust grants	workflow-plugin-agent/policy.PermissionStore through daemon RPC	Supported	`ratchet trust persist allow	deny, /trust persist allow
Permission prompts	Daemon permission gate and TUI prompt flow	Supported	Human approval remains explicit for unresolved decisions. Missing or unknown policy must not silently auto-approve.	Permission prompt tests and daemon/TUI behavior.
Provider setup and credential custody	Shared provider catalog, CLI/TUI setup, daemon provider operations, and existing Workflow secret provider	Supported	The CLI and TUI use the same provider catalog and settings contract. Model discovery can fall back to a manual model ID. Credentials are submitted to the daemon's existing secret provider; persisted provider rows and durable operation/status/log output contain only a versioned secret reference and non-secret metadata.	Catalog contract tests, CLI/TUI state tests, daemon restart and cleanup tests, Unix PTY durable provider save, and Windows ConPTY provider save.
ACP client queue/drain	internal/acpclient, daemon RPC, and CLI	Supported with explicit acknowledgement	--no-wait writes prompt text to a local FIFO queue. Operator-started drain and foreground watch require an explicit launch target. ratchet acp client background start <id> --agent <profile> --acknowledge-unattended authorizes one daemon-owned session drain through a built-in agent or trusted profile; raw command/argv flags are unavailable. Descriptor pinning blocks missing, untrusted, or changed profiles with no automatic retry. background status exposes metadata, background stop disables the policy, and unchanged policies resume after daemon restart. Production daemon IPC remains Unix-only. Arbitrary ACP scheduling remains deferred.	Parser/RPC tests, release-shaped fixture lifecycle proof, redaction assertions, restart/drift tests, native Windows persistence/DACL gates, and command cross-build checks.
ACP archive/compare/replay artifacts	internal/acpclient	Supported local-only	ratchet acp client sessions export --history summary|raw|both, ratchet acp client sessions events, ratchet acp client compare --save, and ratchet acp client flow replay read or write local raw ACPX event logs, archives, compare bundles, and Go-native ACPX replay bundles. They may include prompts, responses, summaries, JSON-RPC messages, action stdout/stderr, and path metadata; shared evidence must use counts and filenames, not payloads.	ACP archive, compare bundle, flow replay, binary smoke, and docs guard tests.
Daemon session export artifacts	Daemon session RPCs and ratchet sessions export	Supported local-only	ratchet sessions export <id> --output <archive.json> writes daemon session tree metadata, message history, and compaction records to a local JSON bundle with user-only permissions. --format jsonl writes line-oriented export/session/message/compaction records for local harness handoff. Exports may include prompts, responses, summaries, provider/model metadata, local paths, and branch relationships; shared evidence must use counts and filenames, not payloads.	TestHandleSessionsExportWritesSensitiveBundle; TestHandleSessionsExportWritesJSONLRecords; command tests cover output validation and summary-only terminal output.
ACP launch profiles	internal/acpclient profile store plus plugin templates	Supported with local trust	ratchet acp client profiles list, add, install, trust, remove, and verify manage local reviewed launch specs. Profiles store commands, args, cwd, and env key names only, not secret values. Built-in ACP agents win over profile names, profile names cannot shadow built-ins, and untrusted profiles do not resolve through --agent or single-profile profiles verify. Profile execution is limited to explicit foreground exec, drain, watch, compare, flow run, redacted profiles verify, and explicitly acknowledged per-session background drain. profiles verify <name> reports session id, stop reason, command fingerprint, and response byte count without prompt text, response text, or env values. profiles verify --all verifies trusted profiles and reports untrusted profiles as skipped without launching them.	ACP profile store, plugin template, command, watch/drain/compare/background, profile verify, and flow tests cover trusted and untrusted resolution.
Release artifact gates	GoReleaser, GitHub Actions, and internal/releaseguard	Supported for release artifacts	GoReleaser snapshot release-check, draft release asset postcheck, tap preflight, generated-cask publish, and tap postcheck gates inspect release archives, checksums, generated cask material, draft metadata, and Homebrew tap path-changing commits before public release undraft. Windows ConPTY smoke covers the test-only smoke binary. Windows command binary startup smoke builds and runs native ratchet.exe --version and help; full packaged release ratchet.exe TUI/installer runtime remains deferred.	Releaseguard tests, CI Release Check, Windows ConPTY smoke, Windows command binary startup smoke, release workflow postchecks, and docs guard tests.
Sandbox/path/network controls	Agent plugin trust logic, mesh path guard, and future sandbox work	Partial	Existing trust decisions and mesh path guard cover only their implemented surfaces. ratchet-cli does not claim Codex/Claude-style full sandbox, network, or per-tool escalation parity.	Existing tests for implemented guards; future sandbox work needs a separate design.
Hooks/extensions	internal/hooks, plugin manifests, plugin marketplaces, plugin reload, and future extension work	Supported with review/trust / Deferred	User hooks in ~/.ratchet/hooks.yaml remain trusted by default for compatibility. Project hooks in .ratchet/hooks.yaml and plugin hooks are listed but skipped until exact descriptor hook trust is recorded with ratchet hooks trust <hash>. ratchet hooks disable <hash> overrides trust, changed hook descriptors require re-review, and plugin hook/profile paths must stay inside plugin roots. `ratchet plugin marketplace add	list
Managed hooks	internal/hooks and daemon final hook composition	Supported	Managed hooks are supported from a fixed administrator-owned platform path. Secure loading occurs before initial or reload publication. Policy is applied after user, plugin, project, and trust composition: additive runs every eligible source, while managed-only retains local diagnostics as suppressed and runs only managed hooks. Managed descriptors are immutable through local trust commands. ratchet hooks policy --json inspects policy state and ratchet hooks audit --json reads the private metadata-only audit. Missing policy is normal; present insecure or malformed policy and required audit failure fail closed.	Managed policy readers and ownership/DACL tests, policy-last side-effect and reload tests, service-boundary execution, exact JSONL schema/privacy tests, and Windows native/cross-build gates.
Flow action nodes	internal/acpclient	Supported with explicit grants	JSON v1 action nodes run runtime-owned local commands only after ratchet acp client flow run receives --allow shell. Node working directories outside the flow base require --allow outside-cwd. Action stdout/stderr persisted in run bundles is sensitive local command output. This is flow-local preflight, not a new trust engine or full sandbox.	ACP client flow tests and binary smoke cover action nodes, missing grants, cwd escapes, and persisted outputs.
Visible routines/workflows	internal/routines, internal/workflows, and CLI stores	Supported local-only	`ratchet routines add	list
Retro/self-improvement	internal/retro and local project evidence routing	Partial	Retro evidence is opt-in. ratchet retro analyze --evidence <file> [--session ID] [--json] reports findings, local actions, and upstream instructions without mutating config or opening PRs. ratchet retro instructions --evidence <file> [--session ID] [--output file] renders the same routed output as a Markdown handoff. ratchet retro bundle --evidence <file> [--session ID] --output <dir> writes derived analysis.json, instructions.md, and manifest.json files without copying raw evidence. These commands do not mutate config, contact GitHub, or open PRs. Automatic local mutation and upstream PR creation are disabled unless a future configurable policy enables them.	Retro analyzer, command, Markdown handoff, bundle, and config-gating tests.
Blackboard notification-event export	Daemon blackboard CLI plus workflow-plugin-messaging-core bridge helpers	Supported local-only	ratchet blackboard export [section] [--json|--jsonl] reads daemon blackboard entries and projects them into local notification-event records with messaging.text. --workflow-messaging adds workflow-plugin-messaging-core step.messaging_send handoff metadata with required downstream channel config. workflow-plugin-messaging-core parses notification-event JSON/JSONL exports with ParseNotificationEvents and projects typed send inputs with ProjectNotificationEventToMessagingSend. Ratchet does not post to Slack, Discord, Teams, webhooks, email, or any network provider, and it has no credential/channel flags. External delivery remains a Workflow messaging plugin responsibility.	Blackboard command tests cover section export, all-section export, JSONL output, Workflow metadata output, and rejected provider credential flags; messaging-core PR #10 covers parser/projection helpers.
Per-agent/team scopes	Daemon team manager and mesh configs	Partial / Deferred	Team orchestration and MCP team messaging exist. Per-agent permission scopes, worktree isolation policy, and channel routing are future work.	Team and MCP tests for current behavior; future per-agent scopes need a separate design.

Sensitive Metadata

Trust rules, grant patterns, hook descriptors, managed hook audit records and archives, launch profile names and commands, provider settings and secret references, queue contents, archive exports, raw ACPX event logs, compare bundles, daemon session export bundles, flow replay bundles, routine/workflow definitions and run records, retro evidence, retro bundle summaries, blackboard export records, flow action output, and policy decisions are sensitive local policy metadata. They can reveal local paths, command names, provider usage, project conventions, prompts, responses, stdout/stderr, or operational habits. Do not expand logging, exports, or public docs with raw policy values unless a future design includes redaction and user consent.

Grant listings and archive files should be handled like local credentials or conversation data:

• prefer local-only storage under the user's state directory;
• redact command/path/provider values in shared evidence;
• avoid exporting queued prompts or grant lists unless explicitly requested;
• avoid sharing blackboard export records unless the local coordination payload was reviewed for secrets and prompt context;
• keep retro evidence opt-in and redacted.

Deferred Automation

The following work is intentionally blocked until a future locked design defines authorization, cancellation, audit evidence, and redaction boundaries:

Work	Status	Required policy decision
Arbitrary ACP scheduling	Deferred	Per-session background drain is supported only with explicit acknowledgement and a descriptor-pinned built-in agent or trusted profile. Cron-like schedules, command-bearing policies, and broader hidden autonomy need a separate policy design.
Remote managed hook distribution	Deferred	Fixed-path local administrator policy is supported. Remote policy distribution remains deferred until a management transport, authenticated authority, rollout, and rollback contract are designed.
Extension SDK	Deferred	Define TypeScript extension SDK boundaries, marketplace update policy, lifecycle interception, mutation opt-in, environment redaction, command/path access, and reviewable local changes. Daemon plugin reload is supported for installed plugin manifests but is not a full extension SDK.
Workflow source execution and triggers	Deferred	Visible, bounded workflow and routine state exists for local definitions and run records. JavaScript workflow execution, shell workflow nodes, API/GitHub triggers, and hidden background autonomy are not implemented.
Sandbox/path/network expansion	Deferred	Define enforced filesystem and network boundaries before claiming parity with Codex or Claude sandbox controls.
Per-agent policy scopes	Deferred	Define how agent roles, teams, worktrees, channels, and scopes compose with persistent grants and runtime rules.
Credentialed third-party agent CI	Deferred	ratchet acp client profiles verify provides the credential-free local contract check; real third-party matrices still need secret handling, provider credentials, failure isolation, and artifact redaction.
ACPX flow source execution	Deferred	Ratchet supports Go-native ACPX durable bundle generation and replay validation through the shared workflow-plugin-acpx runtime while continuing to write bundles with acpx-go; executing .flow.ts files remains out of scope unless a future design defines source compatibility and runtime boundaries.
Local-first gateway/channels	Deferred	Define account/channel routing, inbox persistence, and sandboxing for non-main sessions.

Verification

The docs regression in cmd/ratchet/harness_docs_test.go must keep this matrix visible from the public docs and must fail if required policy layers, statuses, or sensitive local policy metadata warnings disappear.

Run:

go test ./cmd/ratchet -run HarnessEmulationDocs -count=1