@ai-outfitter/outfitter 0.6.1 → 0.7.1

package/doc/state_writeback_strategy.md

@@ -1,342 +0,0 @@
-# State Writeback Strategy
-
-This document describes Outfitter's current model for handling writes that agent CLIs make inside a composite profile.
-
-A composite profile is temporary, but agent CLIs sometimes perform intentionally durable writes, such as logging in, installing plugins, changing settings, or updating MCP configuration.
-Outfitter makes those paths explicit: adapter-declared writable paths are materialized with a resolved `state_persistence` strategy before the child CLI starts, and non-persistent or unknown writes are diagnosed after the child exits.
-
-## Functional model
-
-Outfitter separates three kinds of files that may exist in a composite profile:
-
-1. **Generated runtime files**: files Outfitter assembles from settings, profiles, templates, and adapter rules.
-   Outfitter may regenerate these while the child agent is running when their source inputs change.
-2. **Declared state paths**: adapter-known files or directories the agent CLI may update intentionally, such as auth, settings, MCP config, plugins, caches, and sessions.
-3. **Unknown writes**: files or directories the agent creates outside the adapter-declared state paths.
-
-Only declared state paths can be made durable automatically.
-Unknown writes are never silently persisted because Outfitter does not know their intended owner, merge rules, or durable destination.
-Generated runtime files and declared state paths are deliberately handled separately so live profile/template updates do not erase or re-baseline agent state changes made during the same run.
-
-The user-facing state update lifecycle is:
-
-1. **Choose a profile**.
-   Profile resolution determines the effective `state_persistence` map using normal profile precedence.
-2. **Resolve adapter defaults**.
-   For each path the selected adapter declares, Outfitter uses the profile override when present and otherwise uses the adapter default.
-3. **Prepare the composite profile**.
-   Durable paths are connected to a profile-managed or native CLI location; non-durable paths are created as normal temporary composite profile paths.
-4. **Run the agent**.
-   The agent CLI reads and writes the composite profile as if it were its normal configuration directory.
-5. **Classify changes after exit**.
-   Outfitter checks non-durable declared paths and unknown paths and reports or fails according to their strategies.
-6. **Clean up temporary state**.
-   Temporary composite profile contents are discarded; durable symlink targets remain in their profile or native CLI location.
-
-## Current behavior
-
-- Composite profiles remain temporary and reproducible by default.
-- Outfitter does not do generic post-run copy-back or JSON/YAML merge-back.
-- Persistent state is represented by symlinking a composite profile path to a profile file/directory or to the native CLI fallback path.
-- Adapters may generate a concrete runtime file for a declared state path when they need deterministic launch-time reconciliation.
-  For example, the Pi adapter can generate a transformed `settings.json` that removes native `packages` entries already supplied by profile-controlled extensions, and then mark that declared path as `discard` for write detection during the run.
-- Every adapter-declared state path has a resolved strategy before launch: profile overrides win, otherwise the adapter `default_strategy` is used, except for adapter-generated reconciliation files that are intentionally treated as discarded runtime files.
-- Invalid or disallowed profile-requested `state_persistence` strategies fail before launch; adapter-internal reconciliation may still choose a one-run handling strategy for a generated runtime file.
-- Non-persistent `warn` and `error` strategies are checked after the child CLI exits.
-- Unknown writes outside adapter-declared paths are checked with the adapter's `unknown` pseudo-path strategy.
-- `prompt` is reserved for a future interactive/control-plane workflow.
-  When accepted by a declaration today, it is treated as a non-persistent diagnostic like `warn`.
-
-## Non-goals
-
-- Outfitter does not implement generic copy-back from the composite profile to profiles.
-- Outfitter does not implement generic structured merge-back.
-- Outfitter does not silently persist unknown writes.
-
-## Profile stack and native fallback
-
-State persistence is a normal profile setting.
-Its strategy overrides resolve through the same profile stack as other profile data:
-
-```text
-project-local profile
-project profile
-user profile
-URI/cache profiles
-explicit inheritance
-implicit user default profile
-Outfitter default profile
-```
-
-Native CLI state is not represented as an extra profile layer.
-For `symlink` paths without a profile-provided source, the selected adapter resolves a native fallback location directly, such as `~/.pi/agent/...` for most Pi state paths, `~/.claude/...` for most Claude Code state paths, or `<cache_directory>/utilities` for Pi `utilities/` and `bin/`.
-This native fallback is not a base profile: it does not participate in profile inheritance or merge precedence, and it cannot contribute controls or profile YAML.
-Claude Code `projects/` is additionally controlled by `controls.session_directory` or `controls.claude.session_directory` when set.
-
-## Path-keyed adapter declarations
-
-Adapters declare writable state paths directly, using relative file paths as keys.
-Directory paths use a trailing slash.
-The same key is used for adapter coverage, `state_persistence` overrides, profile resource lookup, native fallback lookup, and composite profile materialization.
-
-The Pi adapter currently declares:
-
-```yaml
-state_paths:
-  auth.json:
-    default_strategy: symlink
-    allowed_strategies: [symlink, error, prompt]
-
-  settings.json:
-    default_strategy: symlink
-    allowed_strategies: [symlink, warn, error, prompt]
-    note: >-
-      When profile-controlled Pi extensions duplicate native settings packages,
-      Outfitter may generate a transformed runtime settings.json and treat this
-      declared path as discard for that launch. That discard handling is
-      adapter-internal; users still cannot request settings.json: discard
-      because discard is not listed in allowed_strategies.
-
-  mcp.json:
-    default_strategy: symlink
-    allowed_strategies: [symlink, warn, error, prompt]
-
-  models.json:
-    default_strategy: symlink
-    allowed_strategies: [symlink, warn, error, prompt]
-
-  trust.json:
-    default_strategy: symlink
-    allowed_strategies: [symlink, warn, error, prompt]
-
-  plugins/:
-    default_strategy: symlink
-    allowed_strategies: [symlink, discard, warn, error, prompt]
-
-  cache/:
-    default_strategy: symlink
-    allowed_strategies: [symlink, discard, warn, error]
-
-  sessions/:
-    default_strategy: symlink
-    allowed_strategies: [symlink, discard, warn, error]
-
-  npm/:
-    default_strategy: symlink
-    allowed_strategies: [symlink, discard, warn, error]
-
-  git/:
-    default_strategy: symlink
-    allowed_strategies: [symlink, discard, warn, error]
-
-  tmp/:
-    default_strategy: symlink
-    allowed_strategies: [symlink, discard]
-
-  utilities/:
-    default_strategy: symlink
-    allowed_strategies: [symlink, discard, warn, error]
-
-  bin/:
-    default_strategy: symlink
-    allowed_strategies: [symlink, discard, warn, error]
-
-  unknown:
-    default_strategy: warn
-    allowed_strategies: [discard, warn, error, prompt]
-```
-
-The Claude Code adapter currently declares:
-
-```yaml
-state_paths:
-  settings.json:
-    default_strategy: symlink
-    allowed_strategies: [symlink, warn, error, prompt]
-
-  agents/:
-    default_strategy: symlink
-    allowed_strategies: [symlink, discard, warn, error, prompt]
-
-  skills/:
-    default_strategy: symlink
-    allowed_strategies: [symlink, discard, warn, error, prompt]
-
-  commands/:
-    default_strategy: symlink
-    allowed_strategies: [symlink, discard, warn, error, prompt]
-
-  plugins/:
-    default_strategy: symlink
-    allowed_strategies: [symlink, discard, warn, error, prompt]
-
-  projects/:
-    default_strategy: symlink
-    allowed_strategies: [symlink, discard, warn, error]
-
-  debug/:
-    default_strategy: symlink
-    allowed_strategies: [symlink, discard, warn, error]
-
-  unknown:
-    default_strategy: warn
-    allowed_strategies: [discard, warn, error, prompt]
-```
-
-## Profile layout for state files
-
-State files live under the relevant CLI-specific profile folder:
-
-```text
-profiles/
-  default/
-    profile.yml
-    cli_specific/
-      pi/
-        auth.json
-        settings.json
-        plugins/
-      claude/
-        settings.json
-        skills/
-        commands/
-        plugins/
-```
-
-Except for special adapter paths described below, when a selected strategy is `symlink`, Outfitter searches the resolved profile folders from highest to lowest precedence for `cli_specific/<adapter>/<state-path>`.
-If a profile contains the file or directory, Outfitter symlinks the composite profile path to that source.
-
-For most Pi paths, if no profile source exists, Outfitter falls back to the corresponding native Pi agent path under `~/.pi/agent`.
-Missing native fallback files/directories are created so the composite profile symlink has a durable destination.
-
-Pi `utilities/` and `bin/` are special cache-backed paths: both resolve to `<cache_directory>/utilities` instead of profile or native Pi state.
-This keeps pi-managed helper binaries reusable across temporary composite profiles without treating them as user-editable profile files.
-
-For most Claude Code paths, if no profile source exists, Outfitter falls back to the corresponding native Claude Code path under `~/.claude`.
-Claude Code `projects/` is special: `controls.claude.session_directory` overrides generic `controls.session_directory`, and the selected session directory becomes the `projects/` symlink source.
-If neither session-directory control is present, `projects/` falls back to `~/.claude/projects`.
-
-## `state_persistence`
-
-Profiles may override persistence by mapping adapter-declared paths to strategy names:
-
-```yaml
-state_persistence:
-  auth.json: symlink
-  settings.json: symlink
-  plugins/: symlink
-  cache/: discard
-  sessions/: discard
-  unknown: warn
-```
-
-The values are concrete strategy names.
-`state_persistence` only needs overrides; omitted paths use the adapter declaration's `default_strategy`.
-
-`state_persistence` is validated by the profile JSON Schema at read boundaries.
-Outfitter also validates the resolved strategy against the adapter declaration before launch.
-
-Functional examples:
-
-```yaml
-# Persist logins and settings, but make caches and sessions run-local.
-state_persistence:
-  auth.json: symlink
-  settings.json: symlink
-  cache/: discard
-  sessions/: discard
-```
-
-```yaml
-# CI profile: fail if pi changes settings, MCP config, or unknown files.
-state_persistence:
-  settings.json: error
-  mcp.json: error
-  plugins/: error
-  unknown: error
-```
-
-```yaml
-# Exploratory profile: allow plugin experiments but report them after exit.
-state_persistence:
-  plugins/: warn
-  unknown: warn
-```
-
-## Composite profile materialization
-
-Before launch, Outfitter processes each adapter-declared state path:
-
-1. Resolve the path's strategy from profile `state_persistence` overrides, then the adapter `default_strategy`.
-2. Validate that the strategy is allowed for that path.
-3. Resolve a source path through the profile hierarchy when the strategy is `symlink`.
-4. Materialize the composite profile path.
-5. Record a baseline fingerprint for non-persistent and unknown write detection.
-
-For `symlink`, Outfitter creates a symlink from the composite profile path to the resolved profile or native CLI source.
-
-For `discard`, `warn`, `error`, and `prompt`, Outfitter creates normal temporary composite profile paths where needed and observes whether they changed.
-
-## Unknown writes
-
-The `unknown` pseudo-path controls writes outside adapter-declared paths:
-
-```yaml
-state_persistence:
-  unknown: warn
-```
-
-Supported `unknown` strategies are non-persistent only:
-
-- `discard`
-- `warn`
-- `error`
-- `prompt`
-
-`unknown` does not support `symlink`, because there is no declared durable destination.
-
-## Strategy selection guide
-
-Use `symlink` when a write is part of durable agent setup, such as logging in, editing native settings, updating MCP config, or installing plugins that should be reused.
-Use `discard` when the data is useful only during the current run, such as cache entries or throwaway sessions.
-Use `warn` when mutation is acceptable but should be visible to the user.
-Use `error` when mutation means the run was not reproducible enough, especially in CI or locked-down project profiles.
-Use `prompt` only as a forward-compatible declaration for future interactive handling.
-
-## Strategies
-
-### `symlink`
-
-Outfitter resolves the state path through the profile hierarchy, then the native CLI fallback, and symlinks that source into the composite profile.
-Persistence happens because the CLI writes through the symlink to an intentional file or directory.
-
-### `discard`
-
-Writes are allowed in the composite profile and are thrown away when the composite profile is deleted.
-Outfitter does not emit diagnostics for changed `discard` paths.
-
-### `warn`
-
-Writes are allowed, discarded, and reported after the child exits.
-`--strict` makes these warnings fatal.
-
-### `error`
-
-Writes are allowed during the child process but cause Outfitter to fail after the child exits if the path changed.
-This is useful for CI and strict reproducibility.
-
-### `prompt`
-
-`prompt` is reserved for a future interactive/control-plane workflow.
-Current implementations that allow it treat writes as non-persistent diagnostics, equivalent to `warn`, with the strategy name preserved in the message.
-
-## Rationale
-
-Path-keyed state declarations keep the model simple:
-
-- the adapter declares the paths it knows the CLI may write and their default strategies;
-- profiles may provide files at those same paths;
-- the native fallback exposes native CLI files at those same paths;
-- `state_persistence` says what to do with each path.
-
-This avoids ambiguous writeback behavior and gives users a clear rule: if a CLI write should persist, configure that composite profile path as `symlink` and provide or accept the profile/native file that should receive the mutation.

package/requirements/OFTR-001-project-foundation.md

@@ -1,53 +0,0 @@
-# OFTR-001: Project Foundation
-
-## Overview
-
-Outfitter is a TypeScript CLI project.
-This document specifies the baseline runtime, language, test, lint, and documentation conventions that must exist before feature work grows.
-
-## Requirements
-
-### OFTR-001.1: Runtime, Package Manager, and Language
-
-1. The project MUST use TypeScript as its primary implementation language.
-2. The project MUST declare Node.js `>=22.19.0` as the supported runtime baseline for the first version.
-3. TypeScript configuration MUST enable strict type checking.
-4. The project MUST provide a separate build TypeScript configuration that emits production files from `src/` to `dist/`.
-5. The project MUST use npm as its package manager for the first version.
-6. The project MUST commit `package-lock.json` after dependency installation or updates.
-7. When an implementation library choice remains unclear, the project SHOULD prefer the same library or convention used by pi.dev.
-
-### OFTR-001.2: Test Framework and Coverage
-
-1. The project MUST use Vitest as its test framework before implementing substantial runtime behavior.
-2. The test command MUST be runnable from package scripts.
-3. The coverage command MUST use `@vitest/coverage-v8`.
-4. The test configuration MUST enforce at least 99% global coverage for statements, branches, functions, and lines.
-5. The coverage configuration MUST include all `src/**/*.ts` files even when a source file is not imported by any test.
-6. Tests that validate formal requirements MUST follow the traceability format required by OFTR-008.3.
-
-### OFTR-001.3: Linting and Complexity
-
-1. The project MUST configure ESLint with TypeScript support using `eslint`, `@eslint/js`, and `typescript-eslint`.
-2. ESLint MUST enforce a maximum cyclomatic complexity of 10.
-3. The lint command MUST be runnable from package scripts.
-4. Production code SHOULD use small command objects and services so the complexity limit remains practical.
-
-### OFTR-001.4: Persisted File Format Policy
-
-1. User-editable persisted Outfitter configuration MUST use YAML instead of JSON unless the file is a JSON Schema.
-2. Every user-editable YAML file format that Outfitter reads MUST have a corresponding JSON Schema.
-3. Outfitter MUST validate YAML files against their JSON Schemas anywhere those files are read.
-4. JSON Schema files MAY use JSON because schemas are tooling-facing validation artifacts.
-
-### OFTR-001.5: Initial Dependency Set
-
-1. The project MUST use Commander as the CLI framework.
-2. The project MUST use `yaml` for YAML parsing and serialization.
-3. The project MUST use AJV for runtime JSON Schema validation.
-4. The project SHOULD use TypeBox when TypeScript-friendly schema authoring is useful.
-5. The project MUST use `defu` for controlled settings and profile deep merging unless a documented merge-specific reason requires custom code.
-6. The project MUST use `cross-spawn` for launching inner agent CLI processes.
-7. The project SHOULD use `glob` for profile and resource discovery.
-8. The project SHOULD use `hosted-git-info` for hosted git URI parsing when the URI format is supported by that library.
-9. The project MAY use `chalk` for terminal diagnostics.

package/requirements/OFTR-002-settings.md

@@ -1,65 +0,0 @@
-# OFTR-002: Settings Discovery and Validation
-
-## Overview
-
-Outfitter settings are the merged result of user, project, and project-local `.outfitter/settings.yml` files.
-The internal Settings object is the single source of resolved configuration for commands.
-
-## Requirements
-
-### OFTR-002.1: Settings Locations
-
-1. Outfitter MUST support a user settings file at `~/.outfitter/settings.yml`.
-2. Outfitter MUST support a project settings file at `<project>/.outfitter/settings.yml`.
-3. Outfitter MUST support a project-local settings file at `<project>/.outfitter/local/settings.yml`.
-4. Outfitter MUST collectively refer to discovered settings files as `settings.yml` in user-facing documentation when discussing the merged settings concept.
-
-### OFTR-002.2: Settings Precedence
-
-1. Project-local settings MUST take precedence over project settings.
-2. Project settings MUST take precedence over user settings.
-3. User settings MUST take precedence over built-in defaults.
-4. Outfitter MUST expose the merged result as a conceptual internal `Settings` object.
-5. The Settings loader SHOULD be designed so future settings sources can be added without changing command implementations.
-
-### OFTR-002.3: Settings Schema
-
-1. Outfitter MUST provide a JSON Schema for `settings.yml`.
-2. Outfitter MUST validate every discovered `settings.yml` file against the settings JSON Schema before merging it.
-3. Validation diagnostics MUST identify the file that failed validation.
-4. Validation diagnostics SHOULD identify the failing setting path when the validator provides that information.
-
-### OFTR-002.4: Default Profile
-
-1. The user settings file `~/.outfitter/settings.yml` MUST declare a default profile after `outfitter setup` completes.
-2. `outfitter run` MUST use the resolved default profile when no profile is selected with `-p` or `--profile`.
-3. Outfitter MUST report an actionable error when no selected profile and no default profile are available.
-
-### OFTR-002.5: Profile Sources in Settings
-
-1. `settings.yml` MAY contain a `profile_sources` array.
-2. Each `profile_sources` entry MUST specify either a local `path`, a remote `uri`, or a `github` shorthand.
-3. A local-only `path` profile source MUST resolve relative to the settings file containing it when the path is relative.
-4. A local-only `path` profile source MUST point to a folder containing profile folders rather than to one specific profile folder.
-5. A `uri` or `github` profile source MUST be syncable by `outfitter sync`.
-6. A `uri` or `github` profile source MAY specify `ref` to select a branch, tag, or commit.
-7. A `uri` or `github` profile source MAY specify `path` to load profiles from a repository subdirectory.
-8. A profile source MAY specify `only` to allow only named profiles from that source.
-9. A profile source MAY specify `except` to exclude named profiles from that source.
-10. If neither `only` nor `except` is specified, Outfitter MUST load all profiles from the source.
-
-### OFTR-002.6: Remote Settings Sources
-
-1. `settings.yml` MAY contain a `remote_settings` array.
-2. Each `remote_settings` entry MUST specify either a remote `uri` or a `github` shorthand.
-3. Each `remote_settings` entry MUST specify `path` to a settings-style YAML file inside the remote repository.
-4. A `remote_settings` entry MAY specify `ref` to select a branch, tag, or commit.
-5. Outfitter MUST load cached remote settings files from their repository subpaths when resolving settings.
-6. Local discovered settings MUST take precedence over remote settings when both define the same setting.
-
-### OFTR-002.7: Cache Directory Setting
-
-1. `settings.yml` MAY contain a `cache_directory` path.
-2. Relative `cache_directory` values MUST resolve relative to the settings file containing them.
-3. When `cache_directory` is not configured, Outfitter MUST use `~/.outfitter/cache` as the default cache directory.
-4. Agent adapters MUST receive the resolved cache directory when assembling a composite profile so persistent composite profile links use the configured cache location.

package/requirements/OFTR-003-profiles.md

@@ -1,60 +0,0 @@
-# OFTR-003: Profiles and Inheritance
-
-## Overview
-
-Profiles describe reusable agent-CLI loadouts.
-Outfitter resolves profile definitions across settings scopes, explicit sources, inherited profiles, and the implicit user default profile.
-
-## Requirements
-
-### OFTR-003.1: Profile Folder Layout
-
-1. A profile MUST be represented by a folder with a required `profile.yml` file.
-2. Outfitter MUST provide a JSON Schema for `profile.yml`.
-3. Outfitter MUST validate every loaded `profile.yml` file against the profile JSON Schema.
-4. A profile folder MAY contain conventional resource folders such as `skills`, `prompts`, `extensions`, and `deepwork/jobs`.
-5. A profile folder MAY contain `cli_specific/<cli-name>/` folders for agent-specific resources and overrides.
-
-### OFTR-003.2: Profile Identity
-
-1. Profile IDs MUST be stable identifiers suitable for commands, logs, cache keys, and documentation.
-2. Profile IDs MUST match the regex `^[a-z0-9][a-z0-9._-]*[a-z0-9]$|^[a-z0-9]$`.
-3. Outfitter MUST reject profile IDs that cannot be safely referenced from the CLI.
-4. Outfitter SHOULD support a separate display label if human-readable names need spaces or punctuation.
-5. Profiles MAY include a short `description` for interactive prompts and profile discovery surfaces.
-
-### OFTR-003.3: Profile Scope Precedence
-
-1. Project-local profile definitions MUST take precedence over project profile definitions for the same profile name.
-2. Project profile definitions MUST take precedence over user profile definitions for the same profile name.
-3. User profile definitions MUST take precedence over cached URI profile definitions for the same profile name.
-4. Cached URI profile definitions MUST be considered according to resolved source order when multiple URI sources provide the same profile name.
-
-### OFTR-003.4: Profile Inheritance
-
-1. `profile.yml` MAY specify an ordered `inherits` array of profile names.
-2. Inherited profiles MUST be treated as lower-precedence sources for the inheriting profile.
-3. Outfitter MUST recursively resolve inherited profiles.
-4. Outfitter MUST detect inheritance cycles and report them as validation errors.
-5. Outfitter MUST preserve inherited profile order when building the profile stack.
-
-### OFTR-003.5: Default Profile Selection
-
-1. Outfitter MUST use the configured `default_profile` only when no explicit profile is selected.
-2. When an explicit profile is selected, Outfitter MUST resolve only that profile and its declared `inherits` chain.
-3. Outfitter MUST NOT include the configured `default_profile` as an implicit base layer for an explicit profile.
-
-### OFTR-003.6: Profile Merging
-
-1. Outfitter MUST merge resolved profile layers deterministically.
-2. YAML object values SHOULD be merged with `defu` or an equivalent controlled deep-merge utility.
-3. Array merge behavior MUST be documented per profile key before that key is treated as stable.
-4. CLI-specific profile content MUST take precedence over generic controls when both generate the same agent-specific artifact.
-5. Outfitter MUST compose `append_system_prompt` values from multiple resolved profile layers into repeated agent append-prompt inputs without requiring profiles to use raw CLI `args` for prompt composition.
-
-### OFTR-003.7: Template Profiles
-
-1. A profile MAY set top-level `template: true` to indicate it is intended for inheritance by runnable profiles rather than direct launch.
-2. Outfitter MUST allow template profiles to contribute controls through `inherits` without marking the inheriting profile as a template.
-3. Outfitter MUST reject direct launches of template profiles, including launches selected through `default_profile`.
-4. `outfitter profile list` SHOULD hide template profiles by default and MUST expose them when the user explicitly requests all profiles.

package/requirements/OFTR-004-sync-and-setup.md

@@ -1,67 +0,0 @@
-# OFTR-004: Setup, Sync, and Profile Creation Commands
-
-## Overview
-
-Outfitter provides setup and maintenance commands that create initial configuration, synchronize remote profile sources, and generate placeholder profile folders.
-
-## Requirements
-
-### OFTR-004.1: Setup Command
-
-1. Outfitter MUST provide a `setup` command.
-2. The `setup` command MUST create `~/.outfitter/settings.yml` when it does not exist.
-3. The `setup` command MUST create a default user profile when no user default profile exists.
-4. The `setup` command MUST validate discovered settings files.
-5. The `setup` command MUST run sync behavior for URI-based profile sources.
-6. The `setup` command SHOULD avoid overwriting existing user files unless a future explicit force option authorizes replacement.
-7. When provided a setup source URI, the `setup` command MUST use that source repository's Outfitter `settings.yml` and profiles as the initial setup starting point for the selected import target.
-8. The interactive `setup` command MUST require interactive TTY streams on both stdin and stdout before prompting.
-9. The interactive `setup` command MUST synchronize remote profile sources before any setup profile choice prompt.
-10. Initial interactive first-run setup MUST NOT ask a separate default-profile choice before welcome onboarding; the welcome role selection determines the generated local default profile.
-11. When the interactive `setup` command presents setup profile choices outside the initial welcome handoff, it MUST present discovered profile IDs as default-profile choices and preserve available display labels in the prompt choices.
-12. When the interactive `setup` command presents setup profile choices outside the initial welcome handoff, it MUST validate the selected default profile ID before writing it to `settings.yml`.
-13. After the interactive `setup` command writes a selected default profile, any newly-created fallback default profile file MUST correspond to the final selected default profile.
-14. When interactive `setup <source>` presents setup profile choices, it MUST limit those choices to profiles from the passed setup source and MUST NOT include default profile sources from pre-existing effective settings.
-15. When interactive `setup <source>` presents setup profile choices and the setup source declares an explicit `default_profile` that exists among those source choices, it MUST make that profile the prompt default and first displayed choice; pre-existing user defaults MUST NOT override that source default for the setup-source prompt.
-16. Interactive `setup <source>` MUST NOT present a default-profile choice before the setup-source welcome/import explanation.
-17. Interactive `setup <source>` MUST explain which setup source is being imported and MUST let the user choose whether to install profiles into user home or the current project before writing setup-source profiles/settings.
-18. Interactive `setup <source>` MUST present exactly one setup-source profile/default choice after the import target choice when setup-source profiles are available.
-19. When the interactive setup-source import target is user home, setup MUST copy missing source profiles into `~/.outfitter/profiles`, write the selected default profile to `~/.outfitter/settings.yml`, and preserve non-overwrite copy behavior.
-20. When the interactive setup-source import target is the current project, setup MUST copy missing source profiles into `<project>/.outfitter/profiles`, write the selected default profile to `<project>/.outfitter/settings.yml`, ensure that project settings expose `./profiles`, and preserve any existing user default profile.
-21. After interactive `setup <source>` imports the selected default profile, setup MUST offer to start Outfitter with that selected profile.
-22. When the user declines the post-import start offer, setup MUST exit without launching and show both `outfitter` for starting the configured default profile and `outfitter --profile <selected-profile>` for starting it explicitly.
-23. Non-interactive `setup <source>` completion MUST NOT launch Outfitter and MUST show the same default and explicit start command guidance.
-
-### OFTR-004.2: Sync Command
-
-1. Outfitter MUST provide a `sync` command.
-2. The `sync` command MUST read and validate settings before synchronizing sources.
-3. The `sync` command MUST fetch or update remote settings sources and URI-based profile sources.
-4. The `sync` command MUST store plain URI-based profile sources without `ref` or repository subpaths under `~/.outfitter/cache/profiles/<encoded-uri>/`, and MUST store URI or GitHub sources with `ref` or repository subpaths under `~/.outfitter/cache/repos/<encoded-uri-and-ref>/`.
-5. The encoded URI cache path MUST support non-GitHub URIs.
-6. The `sync` command MUST validate profiles loaded from synchronized sources.
-7. The `sync` command SHOULD report whether each source was updated, unchanged, skipped, or failed.
-8. The first version of `sync` MUST NOT require lockfile-based profile source reproducibility.
-9. The `sync` command MUST redact credentials embedded in source URIs from user-facing output.
-
-### OFTR-004.3: Create Profile Command
-
-1. Outfitter MUST provide a `profile create` command.
-2. The `profile create` command MUST require a destination scope or destination path.
-3. The `profile create` command MUST require a profile name.
-4. The `profile create` command MUST create a placeholder profile folder with a valid `profile.yml` file.
-5. The `profile create` command SHOULD create conventional subfolders for common profile resources.
-
-### OFTR-004.4: Command Object Implementation
-
-1. All CLI command entry points MUST execute command objects rather than duplicate implementation logic in parser callbacks.
-2. Command objects MUST accept typed input objects rather than reading directly from `process.argv`.
-3. Command objects SHOULD receive filesystem, settings, profile, and process dependencies through constructors or equivalent dependency injection.
-4. The `profile create` parser entry point MUST execute the profile-creation command object.
-
-### OFTR-004.5: List Profiles Command
-
-1. Outfitter MUST provide a `profile list` command.
-2. The `profile list` command MUST read and validate settings before listing profiles.
-3. The `profile list` command MUST list unique profile IDs from configured local and cached remote profile sources.
-4. When multiple configured sources define the same profile ID, the listed profile metadata MUST come from the highest-precedence loaded definition.

package/requirements/OFTR-005-run-and-composite-profile.md

@@ -1,60 +0,0 @@
-# OFTR-005: Run Command and Composite profile Lifecycle
-
-## Overview
-
-The `run` command assembles a temporary agent-specific configuration directory called a composite profile, launches the selected agent CLI, and keeps Outfitter alive to manage the composite profile while the child process runs.
-
-## Requirements
-
-### OFTR-005.1: Run Command Defaults
-
-1. Outfitter MUST provide a `run` command.
-2. `run` MUST be the default command when no command is specified.
-3. The default command behavior MUST be implemented with Commander rather than a custom `process.argv` parser.
-4. The `run` command MUST accept `-p` and `--profile` options for selecting the profile.
-5. The `run` command MUST use the resolved default profile when no profile option is provided.
-6. The `run` command MUST pass unrecognized arguments through to the selected agent CLI unaltered.
-7. When invoked before user setup has created `~/.outfitter/settings.yml`, the default `run` command MUST print `` `outfitter setup` has not been run yet - running now `` and execute setup before resolving the profile.
-
-### OFTR-005.2: Composite profile Definition
-
-1. Outfitter MUST call the dynamically assembled runtime configuration directory a `composite profile`.
-2. A composite profile MUST be scoped to a resolved profile and a selected agent CLI.
-3. Outfitter MUST create composite profile directories under the system temporary directory.
-4. Outfitter SHOULD use composite profile paths that include a run-specific identifier to avoid collisions between concurrent runs.
-
-### OFTR-005.3: Composite profile Assembly
-
-1. Outfitter MUST assemble the composite profile from resolved profile layers in precedence order.
-2. Outfitter MUST combine generic profile controls with CLI-specific overrides.
-3. Each logical generated file in the composite profile MUST have an object instance representing it.
-4. Each composite profile file object MUST know its source inputs and generated output path.
-5. Each composite profile file object SHOULD expose its merge or transform strategy.
-
-### OFTR-005.4: Composite profile Watching
-
-1. Outfitter MUST keep its process alive while the child agent CLI is running.
-2. Outfitter MUST use `fs.watch` or an equivalent Node file watching mechanism on composite profile input files while the child process is running.
-3. Outfitter MUST update generated composite profile files when watched inputs change and the generated output path remains inside the composite profile root.
-4. Outfitter MUST warn when a live update cannot be applied because regeneration or composite profile-root path validation fails.
-
-### OFTR-005.5: Unsupported Controls and Strict Mode
-
-1. Outfitter MUST write a warning to stderr when a profile requests a control that the selected agent adapter cannot support.
-2. The `run` command MUST accept a `--strict` option.
-3. When `--strict` is enabled, unsupported controls MUST cause composite profile assembly to fail instead of only warning.
-4. Strict failures MUST identify the unsupported control and selected agent CLI.
-
-### OFTR-005.6: Composite profile State Persistence
-
-1. Profiles MAY define `state_persistence` entries that map adapter-declared state paths to persistence strategies.
-2. Outfitter MUST validate `state_persistence` values at profile read boundaries.
-3. Before launch, Outfitter MUST resolve each adapter-declared state path to either a profile override strategy or the adapter default strategy.
-4. Outfitter MUST reject profile `state_persistence` keys that are not declared by the selected adapter.
-5. Outfitter MUST reject strategies that are not allowed for the adapter-declared state path.
-6. For `symlink` strategy paths, Outfitter MUST materialize the composite profile path as a symlink to the resolved profile or native CLI source path.
-7. For non-persistent strategies, Outfitter MUST materialize normal temporary composite profile paths and detect writes after the child agent exits.
-8. Unknown writes MUST be governed by the adapter's `unknown` pseudo-path strategy and MUST NOT be persisted by symlink.
-9. Outfitter MUST warn for `warn`, `prompt`, and symlink-replacement state write issues, fail for `error` state write issues, and ignore `discard` state writes.
-10. State path materialization MUST reject paths that escape the composite profile root.
-11. During live composite profile updates, Outfitter MUST update generated composite profile files without re-materializing declared state paths so post-launch write detection can still observe agent changes to those paths.