@poetic-ai/poetic 1.42.0

package/docs/reference/README.md

@@ -0,0 +1,381 @@
+# Reference Documentation
+
+> **Quick reference materials for Poetic developers**
+
+This directory contains comprehensive reference guides for developers working with the Poetic AI orchestration platform. These documents provide detailed technical specifications, conventions, and best practices.
+
+---
+
+##  Reference Guides
+
+### Core References
+
+| Guide | Purpose | When to Use |
+|-------|---------|-------------|
+| [AI Orchestration Testing Guide](./AI_ORCHESTRATION_TESTING_GUIDE.md) | Comprehensive best practices for testing AI platforms | Designing quality strategies, security reviews, cost optimization |
+| [AI Testing Quick Reference](./AI_TESTING_QUICK_REFERENCE.md) | Copy-paste patterns for common testing scenarios | Quick implementation, patterns lookup |
+| [Testing Guide](./TESTING_GUIDE.md) | Comprehensive testing strategy and utilities | Writing tests, debugging test failures, setting up CI/CD |
+| [Type System](./TYPE_SYSTEM.md) | TypeScript type definitions and patterns | Understanding type hierarchies, adding new types |
+| [Naming Conventions](./NAMING_CONVENTIONS.md) | Naming standards for code and files | Creating new files, naming variables/functions |
+| [Terminology](./TERMINOLOGY.md) | Glossary of Poetic-specific terms | Understanding domain concepts, documentation |
+| [Coordination Kernel](./COORDINATION.md) | Shipped coordination kernel contracts (locks, claims, CAS) | Multi-process planning writes, claim protocol, lock ordering |
+
+### Specialized References
+
+| Guide | Purpose | When to Use |
+|-------|---------|-------------|
+| [.poetic/ Directory](./POETIC_DIRECTORY.md) | Instance directory structure (tracked instance data + ignored runtime) and gitignore rules | Understanding what's tracked vs ignored, fixing accidental commits |
+| [Extensions](./EXTENSIONS.md) | Extension list/path/remove and storage layout | Listing or removing installed extensions, `POETIC_EXTENSIONS_DIR` |
+| [CLI Prompt Commands](./CLI_PROMPT_COMMANDS.md) | Complete prompt management CLI reference | Managing prompts, versions, optimization |
+| [Security Reference](./SECURITY.md) | Security policy and best practices | Reporting vulnerabilities, security reviews |
+| [Telemetry And Privacy Reference](./TELEMETRY_PRIVACY.md) | Local telemetry contents, retention, disable, cleanup, and deletion | Reviewing privacy impact, cleaning local telemetry |
+| [Deprecations](./DEPRECATIONS.md) | Deprecated features and migration paths | Updating legacy code, understanding warnings |
+
+---
+
+##  When to Use This Section
+
+### You're in the Right Place If...
+
+-  You need to look up **specific technical details**
+-  You're **writing tests** and need mocking strategies
+-  You're **naming new components** and want consistency
+-  You're **using TypeScript types** and need definitions
+-  You're **managing prompts** via CLI commands
+-  You need to understand **domain terminology**
+-  You're dealing with **deprecated features**
+-  You're conducting a **security review**
+-  You need to understand the **`.poetic/` directory structure**
+-  You need **coordination kernel** lock ordering or claim lifecycle rules
+
+### Look Elsewhere If...
+
+-  You want architectural overview → [ARCHITECTURE.md](https://github.com/ebrindley/Poetic/blob/main/ARCHITECTURE.md)
+-  You need development workflows → [AGENTS.md](../../AGENTS.md)
+-  You want to understand strategy → [STRATEGY.md](https://github.com/ebrindley/Poetic/blob/main/STRATEGY.md)
+-  You need current managed work and sprint status → [Sprint Planning Guide](../SPRINT_PLANNING_GUIDE.md)
+-  You want feature guides → [docs/](../) (feature-specific docs)
+-  You need CLI usage → [CLI_REFERENCE.md](../CLI_REFERENCE.md)
+
+Root-level telemetry and provider documents predate the current placement policy. They
+remain indexed from the [documentation hub](../README.md) until a dedicated, link-safe
+rehome campaign moves them. New shipped-behavior references should be added here rather
+than expanding the root-doc cluster.
+
+---
+
+##  Guide Details
+
+### AI Orchestration Testing Guide
+**File**: [AI_ORCHESTRATION_TESTING_GUIDE.md](./AI_ORCHESTRATION_TESTING_GUIDE.md)
+
+Comprehensive research-backed best practices for testing, validating, and securing AI orchestration platforms covering:
+- Multi-provider LLM integration testing patterns
+- Security hardening (API keys, prompt injection, safe execution)
+- Non-deterministic output validation strategies
+- Performance testing and benchmarking
+- Cost monitoring and optimization
+- Production observability with OpenTelemetry
+- Resilience patterns (retry, fallback, circuit breaker)
+
+**Based on**: 20+ authoritative 2024-2025 sources including OWASP, Trail of Bits, OpenTelemetry, Portkey, academic research
+
+**Example Use Cases**:
+- "How do I test multi-provider LLM systems?"
+- "What are the OWASP LLM Top 10 risks?"
+- "How do I validate non-deterministic AI outputs?"
+- "How do I prevent prompt injection attacks?"
+- "What's the best way to sandbox code generation?"
+- "How can I reduce AI API costs by 80%?"
+
+---
+
+### AI Testing Quick Reference
+**File**: [AI_TESTING_QUICK_REFERENCE.md](./AI_TESTING_QUICK_REFERENCE.md)
+
+Copy-paste code patterns and templates for immediate implementation:
+- Multi-provider testing matrix
+- Non-deterministic testing patterns
+- API key security patterns
+- Prompt injection prevention
+- Safe shell command execution
+- LLM code generation safety
+- Cost tracking and optimization
+- Performance testing patterns
+- OpenTelemetry instrumentation
+- Resilience patterns (retry, fallback, circuit breaker)
+
+**Example Use Cases**:
+- "I need a template for testing non-deterministic outputs"
+- "Show me how to track costs per request"
+- "How do I implement circuit breaker pattern?"
+- "What's the pattern for safe command execution?"
+
+---
+
+### Testing Guide
+**File**: [TESTING_GUIDE.md](./TESTING_GUIDE.md)
+
+Complete testing strategy covering:
+- Test structure (unit, integration, E2E)
+- Running tests (`npm test`, coverage, watch mode)
+- Writing tests (patterns, utilities, assertions)
+- Mocking providers (realistic mocks, no API keys)
+- Debugging failures (verbose output, isolation)
+- CI/CD integration (GitHub Actions)
+- Coverage requirements (>80% overall, >90% new code)
+
+**Example Use Cases**:
+- "How do I mock OpenAI responses?"
+- "What's the test structure?"
+- "How do I debug a flaky test?"
+- "What coverage is required?"
+
+---
+
+### Type System
+**File**: [TYPE_SYSTEM.md](./TYPE_SYSTEM.md)
+
+TypeScript type definitions including:
+- Core types (Task, Variant, Result)
+- Provider interfaces (BaseProvider, ProviderConfig)
+- Telemetry types (Execution, Metrics)
+- Configuration types (PoeticConfig)
+- Type utilities (guards, narrowing)
+- Type hierarchies and relationships
+
+**Example Use Cases**:
+- "What's the structure of a Variant?"
+- "How do I define a new provider?"
+- "What telemetry data is captured?"
+- "How do I use type guards?"
+
+---
+
+### Naming Conventions
+**File**: [NAMING_CONVENTIONS.md](./NAMING_CONVENTIONS.md)
+
+Naming standards for:
+- Files (kebab-case for modules, PascalCase for classes)
+- Functions (camelCase, verb prefixes)
+- Variables (camelCase, descriptive)
+- Types/Interfaces (PascalCase)
+- Constants (UPPER_SNAKE_CASE)
+- Test files (*.test.ts)
+- Configuration files
+
+**Example Use Cases**:
+- "How should I name this utility module?"
+- "What's the pattern for test files?"
+- "Should I use a verb prefix here?"
+- "How do I name constants?"
+
+---
+
+### Terminology
+**File**: [TERMINOLOGY.md](./TERMINOLOGY.md)
+
+Glossary of terms:
+- **Orchestrator**: Core engine coordinating tasks
+- **Variant**: AI agent with specific strategy
+- **Strategy**: Approach for solving tasks
+- **Provider**: AI service (OpenAI, Anthropic, etc.)
+- **Judge**: Quality evaluator for results
+- **Synthesis**: Combining multiple solutions
+- **Telemetry**: Execution tracking and metrics
+- Additional domain-specific terms
+
+**Example Use Cases**:
+- "What's a 'variant'?"
+- "What does 'synthesis' mean in Poetic?"
+- "What's the difference between provider and variant?"
+- "What is telemetry?"
+
+---
+
+### CLI Prompt Commands
+**File**: [CLI_PROMPT_COMMANDS.md](./CLI_PROMPT_COMMANDS.md)
+
+Complete reference for prompt management:
+- 8 CLI commands (list, status, history, optimize, activate, rollback, generate, export)
+- Options and arguments for each command
+- Analytics integration (trend detection, forecasting, regression detection)
+- Auto-tuning capabilities with safety checks
+- Workflow examples and use cases
+- Quick start guide
+- Troubleshooting
+
+**Example Use Cases**:
+- "How do I list all prompts?"
+- "How do I optimize a prompt?"
+- "What's the syntax for activating a version?"
+- "How does auto-tuning work?"
+
+---
+
+### Security Reference
+**File**: [SECURITY.md](./SECURITY.md)
+
+Security policy including:
+- Supported versions
+- Vulnerability reporting process
+- Security best practices
+- API key management
+- Code review guidelines
+- Response timelines
+
+**Example Use Cases**:
+- "How do I report a security vulnerability?"
+- "Which versions are supported?"
+- "What are the security best practices?"
+- "How should I handle API keys?"
+
+---
+
+### Deprecations
+**File**: [DEPRECATIONS.md](./DEPRECATIONS.md)
+
+Deprecated features and migrations:
+- Deprecated APIs and functions
+- Migration paths to new APIs
+- Deprecation timeline
+- Removal schedule
+- Breaking changes
+
+**Example Use Cases**:
+- "Why am I getting a deprecation warning?"
+- "How do I migrate from old API X to new API Y?"
+- "When will this feature be removed?"
+- "What's the replacement for this?"
+
+---
+
+##  Cross-Reference Hints
+
+### For Testing
+1. Start with [Testing Guide](./TESTING_GUIDE.md) for strategies
+2. Check [Type System](./TYPE_SYSTEM.md) for mock type definitions
+3. Reference [Naming Conventions](./NAMING_CONVENTIONS.md) for test file names
+
+### For New Features
+1. Review [Naming Conventions](./NAMING_CONVENTIONS.md) for file/function names
+2. Check [Type System](./TYPE_SYSTEM.md) for type definitions
+3. Reference [Terminology](./TERMINOLOGY.md) for consistent language
+4. Check [Deprecations](./DEPRECATIONS.md) to avoid deprecated patterns
+
+### For CLI Work
+1. Start with [CLI Prompt Commands](./CLI_PROMPT_COMMANDS.md) for prompt management
+2. Reference [CLI_REFERENCE.md](../CLI_REFERENCE.md) for general CLI usage
+3. Check [Type System](./TYPE_SYSTEM.md) for command types
+
+### For Security
+1. Review [Security Reference](./SECURITY.md) for policies
+2. Check [Testing Guide](./TESTING_GUIDE.md) for security test patterns
+3. Reference [ARCHITECTURE.md](https://github.com/ebrindley/Poetic/blob/main/ARCHITECTURE.md) for security architecture
+
+---
+
+##  Quick Look-ups
+
+### Common Patterns
+
+**"How do I name a new module?"**
+→ [Naming Conventions](./NAMING_CONVENTIONS.md#files)
+
+**"How do I mock a provider in tests?"**
+→ [Testing Guide](./TESTING_GUIDE.md#mocking-providers)
+
+**"What's the type for a task result?"**
+→ [Type System](./TYPE_SYSTEM.md#result-types)
+
+**"What does 'synthesis' mean?"**
+→ [Terminology](./TERMINOLOGY.md#synthesis)
+
+**"How do I optimize a prompt?"**
+→ [CLI Prompt Commands](./CLI_PROMPT_COMMANDS.md#4-poetic-prompt-optimize-promptid)
+
+**"How do I report a security issue?"**
+→ [Security Reference](./SECURITY.md#reporting-a-vulnerability)
+
+**"Is feature X deprecated?"**
+→ [Deprecations](./DEPRECATIONS.md)
+
+**"What .poetic/ directories should be gitignored?"**
+→ [.poetic/ Directory](./POETIC_DIRECTORY.md#gitignored-directories-local-only)
+
+**"What is the mandatory planning-lock vs entity-lock ordering?"**
+→ [Coordination Kernel](./COORDINATION.md#1-mandatory-lock-ordering-planning-lock-outermost-entity-lock-inside)
+
+**"Can stale locks from another machine be auto-broken?"**
+→ [Coordination Kernel](./COORDINATION.md#2-cross-machine-locks-are-never-auto-broken)
+
+**"I accidentally committed lab artifacts"**
+→ [.poetic/ Directory](./POETIC_DIRECTORY.md#common-issues)
+
+---
+
+##  Related Documentation
+
+### Architecture & Design
+- [ARCHITECTURE.md](https://github.com/ebrindley/Poetic/blob/main/ARCHITECTURE.md) - System architecture and structure
+- [STRATEGY.md](https://github.com/ebrindley/Poetic/blob/main/STRATEGY.md) - Development philosophy
+- [Sprint Planning Guide](../SPRINT_PLANNING_GUIDE.md) - Current phase and progress
+
+### Workflows & Guides
+- [AGENTS.md](../../AGENTS.md) - Development guide and AI sessions
+- [CLI_REFERENCE.md](../CLI_REFERENCE.md) - Complete CLI command reference
+- [WORKFLOW_CHECKLIST.md](../WORKFLOW_CHECKLIST.md) - Development checklists
+
+### Feature-Specific
+- [PARALLEL_EXECUTION.md](../PARALLEL_EXECUTION.md) - Parallel task execution
+- [TELEMETRY_ARCHITECTURE.md](../TELEMETRY_ARCHITECTURE.md) - Telemetry system
+
+---
+
+##  Document Maintenance
+
+### Adding New References
+
+When adding a new reference document:
+
+1. **Create the file** in `docs/reference/`
+2. **Follow the template**:
+   - Clear title and purpose
+   - Table of contents
+   - Detailed sections
+   - Examples and use cases
+   - Cross-references
+3. **Update this README**:
+   - Add entry to appropriate table
+   - Add guide details section
+   - Add cross-reference hints
+   - Add quick look-up entries
+4. **Update related docs** with links to new reference
+
+### Reference Document Guidelines
+
+-  **Be concise**: Reference, not tutorial
+-  **Be specific**: Exact syntax, types, patterns
+-  **Be complete**: Cover all variations
+-  **Be current**: Update with code changes
+-  **Use examples**: Show, don't just tell
+-  **Cross-reference**: Link to related docs
+-  **Avoid duplication**: Link to authoritative source
+-  **Avoid narrative**: Keep it factual
+-  **Avoid opinions**: Show best practices objectively
+
+---
+
+##  Still Can't Find It?
+
+1. **Check the main docs directory**: [docs/](../)
+2. **Search the codebase**: Look for inline documentation
+3. **Check git history**: `git log -- path/to/file`
+4. **Ask in discussion**: Create a GitHub discussion
+5. **Check related links**: Follow cross-references
+
+---
+
+**Last Updated**: 2024-11-05
+
+**Maintenance**: Keep this index updated when adding/removing reference documents

package/docs/reference/SECURITY.md

@@ -0,0 +1,262 @@
+# Security Reference
+
+This reference summarizes Poetic's public-release security policy and the main
+runtime security boundaries that affect users of the public npm package.
+
+Poetic telemetry is local-first but can include prompts, repository paths,
+provider metadata, output and error tails, token usage, and costs. See
+[Telemetry And Privacy Reference](https://github.com/ebrindley/Poetic/blob/main/docs/reference/TELEMETRY_PRIVACY.md) for storage,
+retention, disable, cleanup, and deletion details.
+
+## Reporting Vulnerabilities
+
+Do not open public issues for security vulnerabilities. Report them privately
+through GitHub Security Advisories:
+
+https://github.com/ebrindley/Poetic/security/advisories/new
+
+Include the Poetic version from `poetic --version`, your operating system, the
+provider or command involved, and the smallest reproduction you can share
+privately.
+
+The canonical project policy lives in [.github/SECURITY.md](../../.github/SECURITY.md).
+Only the latest published minor release line receives security fixes.
+
+## User Responsibilities
+
+- Keep provider API keys and tokens out of the repository.
+- Prefer provider-native authentication stores over committed environment files.
+- Review generated code and commands before applying changes from untrusted
+  prompts or third-party repositories.
+- Run release and package checks before publishing a build.
+- Report suspicious provider output or sandbox bypass behavior through the
+  private advisory channel.
+
+## Runtime Security Boundaries
+
+Poetic orchestrates external provider CLIs. Those CLIs may read project files,
+spawn subprocesses, and access the network according to the active provider and
+platform configuration. Treat provider execution as delegated code execution
+inside the configured workspace, not as a confidentiality boundary.
+
+### macOS Sandbox
+
+On macOS, Poetic can wrap provider CLI processes with `sandbox-exec`. This
+boundary is intended to reduce unintended writes outside approved locations and
+to protect selected credential paths from filesystem access.
+
+Important limits:
+
+- It is not an outbound network filter.
+- It is not a complete confidentiality boundary for every readable file.
+- Provider processes may still receive credentials from inherited environment
+  variables or provider authentication stores.
+- Custom sandbox profiles replace the generated profile, so review them before
+  use.
+
+Use `poetic sandbox status` and the telemetry commands documented in the CLI
+reference to confirm whether a provider run was sandboxed or authorized by
+Linux host class.
+
+Runtime sandbox settings:
+
+- `POETIC_SANDBOX_ENABLED=0` is an incomplete emergency hatch. It disables
+  Poetic's sandbox wrapper for that process. It does not authorize provider
+  internal-sandbox bypass. Host class is the Linux write path; do not use this
+  variable as the Linux write opt-in.
+- `POETIC_SANDBOX_<PROVIDER>_ENABLED=0` disables the wrapper for one provider,
+  such as `POETIC_SANDBOX_CLAUDE_ENABLED=0` or
+  `POETIC_SANDBOX_COPILOT_ENABLED=0`. Same hatch limits as the global flag.
+- `POETIC_SANDBOX_PROFILE_PATH=/path/to/profile.sb` uses a custom macOS
+  sandbox profile. A custom profile fully replaces Poetic's generated profile.
+- `POETIC_SANDBOX_BOUNDARY_POLICY` sets boundary acceptance policy. The default
+  (`attested_outer_ok`) accepts a self-generated seatbelt, an attested
+  container, an attested inherited-outer boundary, or a Linux host class on
+  Linux. `strict` still rejects an inherited-outer boundary, but Linux host
+  class remains accepted on Linux under both policies. Host class is a Seatbelt
+  substitute, not an inherited-outer. Darwin ignores a forged linux proof pair.
+  Every boundary decision consults the policy uniformly: the provider bypass
+  gate, the wrapper path, and the will-be-active predicate.
+- `POETIC_SANDBOX_LINUX_HOST_CLASS=isolated|desktop` is the Linux-only launch
+  declaration. `isolated` is the supported empty-home / cloud-agent contract.
+  `desktop` forces the desktop consent path even inside a container. Ignored on
+  macOS. Provider children never inherit this variable.
+- `POETIC_SANDBOX_CONTAINER_ATTESTED` and
+  `POETIC_SANDBOX_PROVENANCE=container` are container-boundary claims. Poetic
+  accepts them only when the host also provides a runtime-created container
+  signal; environment variables alone cannot attest a container. Existing
+  attested containers remain a valid isolated-class signal.
+- `POETIC_SANDBOX_FORCE_INHERITED_OUTER` is a deprecated legacy test key. It is
+  ignored by sandbox policy and retained as deprecated compatibility metadata.
+  Provider child environments independently scrub all Poetic sandbox-authority
+  variables. Do not use it to configure a runtime boundary.
+
+### Supported write-capable provider boundaries
+
+Write-capable provider automation needs an accepted sandbox/policy boundary.
+On macOS that is still a confinement boundary plus proof that required state
+paths are writable under it. On Linux, host class is the write policy: it
+authorizes writes without claiming a Seatbelt-equivalent filesystem allowlist.
+
+Supported paths:
+
+- **macOS Seatbelt** — Poetic's generated seatbelt profile (`sandbox-exec`) is
+  the default self-authored boundary on macOS and proves the policy allowlist by
+  construction. Missing Seatbelt, an accepted container, or an inherited outer
+  still fails closed. Unchanged.
+- **Attested container** — container provenance is accepted only when a
+  container-boundary claim is paired with a runtime-created container signal
+  (`POETIC_SANDBOX_CONTAINER_ATTESTED` / `POETIC_SANDBOX_PROVENANCE=container`
+  above). Container acceptance still requires the provider's required write
+  paths to be writable under that outer boundary. Existing attested containers
+  remain valid.
+- **Linux host class** — Linux has no self-generated Seatbelt. Isolated or
+  acknowledged Linux means provider CLIs can write anywhere `$USER` can. That
+  is not Seatbelt-sandboxed. All three write gates honor `linux_isolated` /
+  `linux_acknowledged` plus `linux_host_class` on Linux only. Accepted under
+  both `strict` and `attested_outer_ok`.
+  - **isolated** (VM, container, cloud, CI): writes just work. Classify with
+    `poetic sandbox trust linux --host isolated` or launch env
+    `POETIC_SANDBOX_LINUX_HOST_CLASS=isolated` (supported empty-home /
+    cloud-agent contract). Isolated never expires except
+    `poetic sandbox trust linux --revoke`. Auto-isolate on container OS
+    markers, well-known CI vendor vars, and Codespaces/Gitpod. Not DMI /
+    hypervisor. Not `CI=true` alone. Not unverified `CURSOR_AGENT`.
+  - **desktop**: warn plus informed override
+    (`poetic sandbox trust linux --ack-desktop` or a TTY prompt). Never a
+    platform ban. Missing consent fails this run with
+    `linux_desktop_consent_required`. WSL is treated as a desktop.
+  - Consent is user-scoped (`getStateDir()` /
+    `~/.poetic/state/linux-host-policy.json`), never repo `.poetic/`.
+
+```bash
+poetic sandbox status [--json] [--probe] [--provider] [--all]
+poetic sandbox classify [--json]
+poetic sandbox trust linux --host isolated
+poetic sandbox trust linux --ack-desktop
+poetic sandbox trust linux --revoke
+```
+
+`status --json` includes `linuxHost`. `--ack-desktop` always prints the full
+risk paragraph to stderr (the flag is the consent; the paragraph is the
+record). `poetic doctor` keeps `sandboxCapable` as a path-writability probe;
+desktop-unacked is a warning, not sandbox-blocked.
+
+Install, readiness (`provider list`, `doctor`), orientation (`plan next`),
+telemetry/cost reads, and other read-only or non-provider-write CLI commands
+remain available on Linux without host-class consent.
+
+The write-capable subprocess paths — headless provider automation through the
+shared base runner, the tmux transport, and the API transport's `bash` tool —
+honor the same contract (macOS Seatbelt / attested container / inherited outer,
+or Linux host class). Other sandbox-wrapped subprocesses — auth, model
+discovery, `doctor`, and readiness probes — are still wrapped but are not
+refused when no confinement boundary is available, which is what keeps them
+usable on Linux without host-class consent (some of them, such as provider
+auth, do write provider configuration).
+
+It also does not cover the API transport's in-process `write_file` and
+`edit_file` tools, which write files directly from the Poetic process rather
+than through a sandboxed subprocess. Those writes are confined by a path jail
+instead: the target path is resolved against the run's working directory, and
+paths — or symlinks — resolving outside it are rejected. That containment is
+enforced when the path is validated, not at the moment of the write, so it is
+not resistant to a concurrent rename or symlink swap inside the working
+directory between the two steps.
+
+The API transport is opt-in, and reaching those write tools takes a deliberate
+configuration. `resolveTransportType` selects `api` only from a `+api` variant
+suffix, `POETIC_PROVIDER_<ID>_TRANSPORT=api`, or a provider's configured
+`transport` field; every shipped provider that can execute work defaults to
+`transport: cli`. (The catalog does contain a `transport: api` entry, but it is
+`enabled: false` and is a pricing data source rather than an execution
+provider.) Analysis-only provider runs additionally narrow the API tool roster to
+the read-only tools, so `write_file` and `edit_file` are neither advertised nor
+executable there. Runs that go through the shared provider runner derive that
+narrowing from the run's execution intent rather than relying on each caller to
+pass it. A few paths call a provider engine directly, bypassing that runner, and
+remain responsible for setting the flag themselves. Where the narrowing applies
+it is enforced at the dispatch boundary as well as in what is advertised: a
+response naming a tool outside the resolved set is refused rather than run.
+
+Where the transport is selected for write-capable work, two consequences follow.
+On bare Linux those specific writes can proceed without an accepted sandbox
+boundary, confined by the working directory rather than by the boundary
+described above. On macOS, where a seatbelt profile is generated, they also
+bypass that profile's write denials on `.git/hooks` and `core.hooksPath` — the
+`bash` tool obeys those denials, the in-process write tools never reach the
+profile. Those tools write with ordinary file permissions and cannot set an
+executable bit, so a newly created hook file is inert; the deferred-execution
+consequence needs an already-executable hook to overwrite, or `.git/config` and
+`core.hooksPath` redirection to an existing executable.
+
+### Project Verification Executes Target-Repository Code
+
+Poetic's verification path runs the target repository's own test, build, lint, and
+typecheck commands. On macOS, those commands use the generated `sandbox-exec`
+boundary with worktree writes allowed and Git metadata writes disabled. On
+unsupported platforms or when the sandbox is explicitly disabled, verification
+remains an ordinary child process.
+
+Without an active boundary, code reached through a verification command can write
+anywhere your user account can write, including `$HOME`, and can read credential
+paths. With the generated macOS profile, filesystem effects are confined to the
+worktree, approved runtime state, caches, and temporary directories.
+
+Mitigations that do apply, and what each does not cover:
+
+- Verification children receive a narrow environment allowlist rather than the
+  parent environment. AI and provider API keys, cloud credentials, `GIT_*`
+  routing, and `GH_*` and `GITHUB_*` tokens are excluded. This is credential
+  scrubbing, not filesystem isolation; `HOME` and `PATH` are preserved. The two
+  callers differ: the local CI gate excludes ambient `POETIC_*` authority
+  variables, forces `CI=1`, and injects only authority-derived values, while
+  orchestrator verification inherits ambient `CI`. Verified code can therefore
+  tell the two contexts apart.
+- A command-safety allowlist rejects shell metacharacters, `sh`/`bash`/`zsh` and
+  similar shell executables, inline `node -e`, install and remote-exec verbs such
+  as `npm ci`, and `npx` without `--no-install` or `--offline`. It constrains the
+  command string, not what the invoked script does. `npm test`, `pytest`,
+  `cargo test`, and `make test` are all accepted, and each then runs whatever the
+  repository defines. Some interpreters are admitted for a specific narrow verb,
+  such as `pwsh` limited to `Invoke-Pester`, which still executes the
+  repository's own test code.
+- Dependency materialization passes `--ignore-scripts` for npm, pnpm, and bun, so
+  install lifecycle scripts are suppressed. Yarn is excluded because Yarn Berry
+  rejects the flag, the Python path uses `pip install`, which can execute build
+  backends, and `--ignore-scripts` has no effect on what a test script runs
+  later.
+
+Realistic exposure paths are a compromised dependency pulled into the target
+project, or agent-authored or prompt-injected code that reaches a verification
+script. Neither requires a hostile third-party contribution.
+
+This is not limited to the local CI gate. Orchestrator verification also uses the
+same runner as local CI (wrapped when a boundary is available), including
+progress validation, the typecheck gate, post-execution checks, and
+competition verification.
+
+Treat running Poetic against an untrusted or unfamiliar repository as running
+that repository's code on your machine.
+
+### Package Contents
+
+The public npm package uses an explicit `package.json#files` allowlist.
+User docs are included by path instead of shipping the whole
+`docs/` tree, and package guards reject internal security session notes,
+validation reports, and audit artifacts.
+
+Relevant local checks:
+
+```bash
+npm run -s check:package-docs
+npm run -s verify:dist
+npm run -s release:pack-smoke
+```
+
+## Security Review Scope
+
+Security audit notes, validation reports, and investigation drafts belong in
+internal planning or security-audit locations, not in the public npm package
+or its reference docs. Packaged docs should describe
+shipped behavior, reporting channels, and user-facing security boundaries.