@ai-outfitter/outfitter 0.6.1 → 0.7.0

package/doc/controllable-elements.md

@@ -1,162 +0,0 @@
-# Controllable Elements
-
-This document defines cross-agent-CLI concepts that Outfitter profiles may control.
-Pi is the first supported CLI, and Claude Code is supported as an additional adapter.
-Other CLIs may be added later while keeping the profile model generic.
-
-Status values:
-
-- **Supported**: Outfitter supports this control for the CLI.
-- **Roadmap**: the CLI appears to support this concept, but Outfitter does not support it yet.
-- **Unsupported**: the agent CLI cannot meaningfully support the concept or no known native mechanism exists.
-
-## How to Read This Matrix
-
-A `Supported` entry means Outfitter can control that concept for the agent CLI through at least one native mechanism: a config-directory boundary, state-path placement, generated files, environment variables, command-line flags, or pass-through arguments.
-It does not always mean there is a one-to-one native CLI flag or that every generic profile selector has been mapped.
-
-For example, Claude Code session/project state lives under Claude's config home rather than a standalone `--session-dir` flag.
-Outfitter supports that session-directory concept for Claude by setting `CLAUDE_CONFIG_DIR` to the composite profile root, declaring Claude `projects/` state for persistence, and allowing `controls.session_directory` or `controls.claude.session_directory` to choose where that state is symlinked from.
-Likewise, Claude skills and commands are supported as native directories under the profiled `CLAUDE_CONFIG_DIR`, even though the generic `controls.skills` and `controls.prompt_template` selectors are not yet translated into Claude-specific selection flags.
-
-## Defined Terms
-
-### Agent Config Directory
-
-The root directory that stores agent-global configuration, credentials, installed resources, and related state.
-
-- Pi name: `PI_CODING_AGENT_DIR` / agent dir
-- Claude name: `CLAUDE_CONFIG_DIR` / Claude config home
-
-### Session Directory
-
-The directory where conversation sessions, transcripts, or run state are stored.
-
-- Pi name: `PI_CODING_AGENT_SESSION_DIR` / `--session-dir`
-- Claude name: session/project state under `CLAUDE_CONFIG_DIR`, including `projects/` state managed by Outfitter state persistence
-
-### Extensions
-
-Executable/plugin modules that add tools, providers, hooks, or runtime behavior.
-
-- Pi name: extensions, `--extension` / `-e`
-- Claude name: plugins via `--plugin-dir`
-
-### Skills
-
-Reusable task instructions, workflows, or resource bundles exposed to the agent.
-
-- Pi name: skills, `--skill`
-- Claude name: skills under the Claude config directory; Outfitter can profile native Claude skills through `cli_specific/claude/skills`, but generic `skills` selection is not mapped yet
-
-### Prompt Templates
-
-Named reusable prompts/templates available to the agent runtime.
-
-- Pi name: prompt templates, `--prompt-template`
-- Claude name: commands/prompts under the Claude config directory; Outfitter can profile native Claude commands through `cli_specific/claude/commands`, but generic `prompt_template` selection is not mapped yet
-
-### System Prompt
-
-The primary instruction text supplied to the agent.
-
-- Pi name: `--system-prompt`, `SYSTEM.md`
-- Claude name: `--system-prompt`
-
-### Appended System Prompt
-
-Additional instruction text layered onto the primary system prompt.
-
-- Pi name: `--append-system-prompt`, `APPEND_SYSTEM.md`
-- Claude name: `--append-system-prompt`
-
-### Model Selection
-
-The selected provider/model and related inference options.
-
-- Pi name: `--provider`, `--model`, `--models`, `--thinking`
-- Claude name: `--model`, `--effort`
-
-### Credentials and Environment
-
-Environment variables, API keys, auth files, and related secret material needed by providers or tools.
-
-- Pi name: provider env vars, `auth.json`, `--api-key`
-- Claude name: environment variables and config files under `CLAUDE_CONFIG_DIR`
-
-### Tool Availability
-
-Configuration that enables, disables, or filters tools exposed to the agent.
-
-- Pi name: tool settings and extension-provided tools
-- Claude name: allowed/disallowed tools, roadmap adapter mapping
-
-### Context Files
-
-Project or profile files automatically loaded into context.
-
-- Pi name: context files, `--no-context-files`
-- Claude name: project memory/context files, roadmap adapter mapping
-
-### Theme / UI Presentation
-
-Terminal UI theme and presentation settings.
-
-- Pi name: themes, `--theme`, `--no-themes`
-- Claude name: UI/theme controls, roadmap adapter mapping
-
-### Project Override Policy
-
-Whether project-local agent configuration is allowed, ignored, or constrained.
-
-- Pi name: project `.pi/` resources and settings
-- Claude name: project-local config, roadmap adapter mapping
-
-### Working Directory
-
-The directory from which the inner agent CLI is launched.
-
-- Pi name: cwd/session cwd
-- Claude name: cwd/project directory
-
-### Pass-through Arguments
-
-Arguments not recognized by Outfitter that are forwarded unmodified to the inner agent CLI.
-
-- Pi name: native pi CLI args
-- Claude name: native Claude CLI args
-
-### Bootstrap Hook
-
-An early-startup customization used to register providers, tools, hooks, or additional runtime behavior.
-
-- Pi name: explicit bootstrap extension via `--extension` / `-e`
-- Claude name: startup hook/plugin mechanism, not mapped by Outfitter yet
-
-## Support Matrix
-
-| Controllable Element        | Pi        | Claude    |
-| --------------------------- | --------- | --------- |
-| Agent Config Directory      | Supported | Supported |
-| Session Directory           | Supported | Supported |
-| Extensions                  | Supported | Supported |
-| Skills                      | Supported | Supported |
-| Prompt Templates            | Supported | Supported |
-| System Prompt               | Supported | Supported |
-| Appended System Prompt      | Supported | Supported |
-| Model Selection             | Supported | Supported |
-| Credentials and Environment | Supported | Supported |
-| Tool Availability           | Roadmap   | Roadmap   |
-| Context Files               | Roadmap   | Roadmap   |
-| Theme / UI Presentation     | Roadmap   | Roadmap   |
-| Project Override Policy     | Roadmap   | Roadmap   |
-| Working Directory           | Roadmap   | Roadmap   |
-| Pass-through Arguments      | Supported | Supported |
-| Bootstrap Hook              | Supported | Roadmap   |
-
-## Day-One Interpretation
-
-For v1, a Outfitter profile may describe all defined terms generically.
-The Pi adapter is the first implementation, and pi remains the default adapter.
-Adapter-specific overrides live under `controls.pi` and `controls.claude`; unsupported controls warn at runtime, and `--strict` makes those warnings fatal.
-For Claude Code, `skills/` and `commands/` are supported as native configuration directories inside the profiled `CLAUDE_CONFIG_DIR`; the generic `controls.skills` and `controls.prompt_template` selectors remain unmapped and warn if requested.

package/doc/file_structure.md

@@ -1,141 +0,0 @@
-# Outfitter File Structure
-
-This document records the key repository file and directory structure used by Outfitter.
-See `doc/architecture.md` for runtime file conventions such as `.outfitter` settings folders, profile folders, and generated composite profile directories.
-
-## Repository Layout
-
-Outfitter is organized around clear TypeScript source boundaries, requirement documents, and scenario-based tests.
-
-```text
-.                                      # repository root
-├── .deepreview                        # root DeepWork review rules for project-wide checks
-├── .dockerignore                      # container build context exclusions
-├── Dockerfile                         # local and release Outfitter container image definition
-├── .deepwork/                         # DeepWork schemas and generated review instruction scratch files
-│   └── schemas/                       # project-specific DeepSchema definitions
-├── .github/                           # GitHub automation configuration
-│   └── workflows/                     # GitHub Actions workflows and local .deepreview rules
-├── doc/                               # architecture, design, and specification docs
-│   ├── .deepreview                    # documentation-specific DeepWork review rules
-│   ├── architecture.md                # architectural rationale and runtime file conventions
-│   ├── controllable-elements.md       # controllable element terminology and support matrix
-│   ├── file_structure.md              # repository file structure overview
-│   ├── integration_test_system.md     # fixture-backed integration test design
-│   ├── state_writeback_strategy.md    # composite profile state persistence and writeback design
-│   └── specs/                         # detailed supporting specs
-├── doc_site/                          # Nextra/Next.js documentation website
-│   ├── app/                           # App Router pages, layout, and site styles
-│   ├── eslint.config.js               # documentation site ESLint configuration
-│   ├── mdx-components.tsx             # Nextra MDX component bridge
-│   ├── next.config.mjs                # Next.js configuration wrapped by Nextra
-│   ├── package.json                   # documentation site package scripts and dependencies
-│   └── tsconfig.json                  # documentation site TypeScript configuration
-├── requirements/                      # formal OUTFITTER requirement documents
-│   ├── OFTR-001-project-foundation.md
-│   └── ...
-├── .prettierignore                    # Prettier ignore rules
-├── .prettierrc.json                   # Prettier formatting configuration
-├── .snapperrc.toml                    # Snapper Markdown formatting configuration
-├── CONTRIBUTING.md                    # local install and contributor workflow guide
-├── bin/                               # local executable development helpers
-│   ├── dev-container-setup            # clean container helper for setup smoke tests
-│   ├── dev-setup-source               # local build helper for real setup-source targets
-│   └── dev-tmp-home                   # isolated temporary HOME launch helper
-├── src/                               # production TypeScript source
-│   ├── cli.ts                         # executable CLI entry point
-│   ├── cli/                           # CLI parser construction and command registration
-│   │   ├── OutfitterCli.ts
-│   │   └── commands/                  # command objects for non-trivial CLI behavior
-│   │       ├── CommandObject.ts
-│   │       ├── FirstRunWelcomeProfile.ts
-│   │       ├── PiLoginLaunch.ts
-│   │       ├── RunCommand.ts
-│   │       ├── SetupCommand.ts
-│   │       ├── SyncCommand.ts
-│   │       ├── WelcomeCommand.ts
-│   │       └── profile/               # profile command namespace and subcommands
-│   │           ├── Command.ts
-│   │           ├── CreateCommand.ts
-│   │           ├── ListCommand.ts
-│   │           └── Shared.ts
-│   ├── settings/                      # settings loading and merging
-│   │   ├── Settings.ts
-│   │   ├── SettingsLoader.ts
-│   │   └── SettingsMerger.ts
-│   ├── profiles/                      # profile loading, validation, resolution, and merging
-│   │   ├── Profile.ts
-│   │   ├── ProfileCache.ts
-│   │   ├── ProfileLoader.ts
-│   │   ├── ProfileMerger.ts
-│   │   └── ProfileSource.ts
-│   ├── merge/                         # reusable deterministic value and array merge policy helpers
-│   │   ├── ArrayMergePolicy.ts
-│   │   └── SettingsValueMerger.ts
-│   ├── compositeProfile/              # generated runtime composite profile assembly and watching
-│   │   ├── CompositeProfile.ts
-│   │   ├── CompositeProfileAssembler.ts
-│   │   ├── CompositeProfileFile.ts
-│   │   ├── CompositeProfileTemplate.ts
-│   │   ├── CompositeProfileWatcher.ts
-│   │   └── StatePersistence.ts
-│   ├── agents/                        # agent adapter boundary and CLI-specific adapters
-│   │   ├── AdapterProfileControls.ts
-│   │   ├── AdapterStatePaths.ts
-│   │   ├── AgentAdapter.ts
-│   │   ├── AgentRegistry.ts
-│   │   ├── LaunchResources.ts
-│   │   ├── ResourceIdentity.ts
-│   │   ├── pi/                        # pi-specific adapter implementation
-│   │   │   ├── PiAdapter.ts
-│   │   │   ├── PiMcpConfig.ts
-│   │   │   ├── PiSettingsMergePolicy.ts
-│   │   │   └── PiCompositeProfileWriter.ts
-│   │   └── claude/                    # Claude Code-specific adapter implementation
-│   │       ├── ClaudeAdapter.ts
-│   │       └── ClaudeCompositeProfileWriter.ts
-│   ├── schemas/                       # JSON Schema artifacts for persisted formats
-│   │   ├── settings.schema.json
-│   │   ├── profile.schema.json
-│   │   ├── profile-source.schema.json
-│   │   └── SchemaDocument.ts
-│   └── validation/                    # shared validation helpers
-│       ├── SchemaValidator.ts
-│       └── YamlDocument.ts
-├── scripts/                           # local development and formatting helper scripts
-│   ├── .deepreview                    # script-specific DeepWork review rules
-│   └── run-snapper.mjs                # pinned Snapper binary downloader/runner
-├── skills/                            # Pi package skills published with Outfitter
-│   └── outfitter/                     # default /outfitter setup guidance skill
-│       └── SKILL.md
-├── tests/                             # automated tests
-│   ├── fixtures/                      # reusable test fixtures
-│   │   ├── integration/               # fixture-backed integration scenarios, catalog, and local .deepreview
-│   │   └── scenarios/                 # compact profile-resolution scenarios and expected outputs
-│   ├── integration/                   # fixture-backed integration tests and harness helpers
-│   ├── setup.ts                       # Vitest global setup for quiet test-output guards
-│   ├── test-console.ts                # shared console-output guard helpers for tests
-│   └── unit/                          # unit tests grouped by functionality under test, including welcome and first-run tests
-├── package-lock.json                  # locked npm dependency graph
-└── package.json                       # npm package metadata and scripts
-```
-
-The exact layout may evolve, but these boundaries should stay recognizable.
-
-## Test Fixtures
-
-Integration fixtures should live under `tests/fixtures/integration/` with full `home/`, `project/`, and optional `expected/` trees.
-Fixture-backed integration tests and shared harness helpers should live under `tests/integration/`.
-
-Scenario fixtures should live under `tests/fixtures/scenarios/`, for example:
-
-```text
-tests/fixtures/scenarios/
-  profile-cycle/
-  profile-inheritance-chain/
-  profile-missing-inheritance/
-  profile-multiple-inheritance/
-  profile-precedence/
-```
-
-Each scenario should include realistic `.outfitter` folders and expected resolution output.

package/doc/integration_test_system.md

@@ -1,214 +0,0 @@
-# Integration Test System
-
-## Purpose
-
-Outfitter uses fixture-backed integration tests to exercise real settings/profile directory trees rather than constructing every input inside individual tests.
-This is especially important for composite profile generation and state persistence because the effective runtime composite profile can be composed from multiple settings files, multiple profile sources, inherited profiles, adapter defaults, and CLI-specific profile state files.
-
-The core risk is that a generated composite profile can look correct in isolated unit tests while write-back/state-persistence behavior remains ambiguous or unsafe when the composite profile came from four or more durable sources.
-Integration fixtures make those source relationships visible and testable.
-
-## Goals
-
-- Store realistic, pre-written Outfitter projects as fixture directories.
-- Copy each fixture into a temporary directory before the test mutates it.
-- Traverse fixtures through the same public loading, resolution, composite profile assembly, and run/write detection paths used by commands.
-- Assert the resulting composite profile shape, symlinks, generated files, argv/env launch plan, warnings, and durable write results.
-- Make source ownership explicit enough that tests prove Outfitter does not perform unsupported generic write-back into composed settings/profile inputs.
-- Keep fixtures reusable across tests and documented in the integration fixture catalog.
-
-## Non-goals
-
-- Integration tests do not replace focused unit tests for schema validation, merge algorithms, adapter helpers, or path-safety checks.
-- Outfitter does not implement generic structured merge-back from generated composite profile files into settings or profiles.
-- Integration tests do not require real pi or Claude Code binaries.
-  Tests inject fake launchers that read/write the composite profile.
-- Integration tests do not depend on the developer machine's real home directory, native CLI config, or network state.
-
-## Repository layout
-
-```text
-tests/
-  integration/
-    composite profile-generation.test.ts
-    fixtureHarness.ts
-  fixtures/
-    integration/
-      README.md
-      trivial_repo_only_profile/
-        README.md
-        home/
-          .outfitter/settings.yml
-          .outfitter/profiles/default/profile.yml
-        project/
-          .outfitter/settings.yml
-          .outfitter/profiles/repo-review/profile.yml
-        expected/
-          pi/
-            composite profile-summary.json
-            warnings.json
-```
-
-The existing `tests/fixtures/scenarios/` directory contains small profile-resolution fixtures used by current unit tests.
-The integration framework does not replace or move those fixtures.
-End-to-end fixtures live in `tests/fixtures/integration/` because they model full home/project/cache/native trees and expected composite profile effects.
-When an existing scenario is useful for an integration test, copy or expand it into a new integration fixture instead of changing the existing unit-test fixture in place.
-
-Additional fixture-set PRs target this framework branch and add more directories under `tests/fixtures/integration/`.
-
-## Fixture directory contract
-
-Each integration fixture is a complete synthetic filesystem tree.
-A fixture uses these top-level entries:
-
-| Path        | Purpose                                                                                                      |
-| ----------- | ------------------------------------------------------------------------------------------------------------ |
-| `README.md` | Human explanation of the scenario and the behavior it protects.                                              |
-| `home/`     | Synthetic user home directory passed to command execution.                                                   |
-| `project/`  | Synthetic project directory passed to command execution.                                                     |
-| `expected/` | Expected composite profile summaries, symlink targets, warnings, launch args/env, and durable file contents. |
-
-A fixture may also include these top-level entries:
-
-| Path      | Purpose                                                                                         |
-| --------- | ----------------------------------------------------------------------------------------------- |
-| `native/` | Explicit native CLI state tree for tests that map adapter fallbacks away from `home/`.          |
-| `cache/`  | Pre-seeded Outfitter cache, remote-profile cache, or adapter cache/tooling state when required. |
-
-Settings and profiles inside `home/` and `project/` use normal Outfitter paths such as `.outfitter/settings.yml`, `.outfitter/local/settings.yml`, and `.outfitter/profiles/<id>/profile.yml`.
-CLI-specific state lives under profile folders, for example `cli_specific/pi/settings.json` or `cli_specific/claude/settings.json`.
-Fixture names describe the user/project scenario rather than the adapter; adapter-specific expected output is nested under `expected/pi/`, `expected/claude/`, and similar directories.
-
-## Harness responsibilities
-
-`tests/integration/fixtureHarness.ts` exports these helpers:
-
-- `copyFixtureToTemp(name)` copies `tests/fixtures/integration/<name>` into `mkdtemp` and returns an `IntegrationFixture` with `root`, `home`, `project`, `cache`, and `expected` paths.
-- `runFixture(fixture, options)` executes `executeRunCommand` with the copied home/project and the provided fake launcher.
-- `summarizePiComposite profile(fixture, composite profileRoot)` returns stable pi-specific facts about generated profile content and selected state symlinks.
-- `readExpectedJson(fixture, relativePath)` loads expected fixture output from the copied `expected/` tree.
-- `readFixtureText(fixture, relativePath)` reads a text file from the copied fixture root.
-- `cleanupIntegrationFixtures()` removes copied fixtures after each test.
-
-The harness normalizes absolute paths in expected output using tokens such as `<fixture>`, `<home>`, `<project>`, `<cache>`, and `<composite profile>`.
-This keeps expected files readable and independent of temporary directory names.
-
-## Where mutations and assertions live
-
-The framework uses a split model:
-
-- **Fixture files encode inputs and expected stable outputs.
-  ** The fixture directory contains settings, profiles, CLI-specific state files, and optional `expected/*.json` snapshots such as expected symlink targets, warnings, or final durable file contents.
-- **Test code encodes behavior.
-  ** The Vitest test case chooses which fixture to run, defines the fake launcher's mutation script, and performs assertions against the copied fixture and any expected files.
-
-This keeps fixtures readable as normal Outfitter directory trees while keeping active behavior in TypeScript where it can use filesystem APIs, helper functions, and precise assertions.
-Do not hide executable test behavior in ad hoc YAML unless a future mutation-script format is deliberately added.
-
-For example:
-
-```ts
-it('does not copy generated composed settings back to source layers', async () => {
-  const fixture = copyFixtureToTemp('heavily_overridden_engineering');
-
-  const result = await runFixture(fixture, {
-    launcher(plan) {
-      const composite profileRoot = composite profileRootFromLaunchPlan(plan);
-      writeFileSync(join(composite profileRoot, 'outfitter', 'profile.json'), '{"mutated":true}\n');
-      writeFileSync(join(composite profileRoot, 'unexpected.txt'), 'unknown write\n');
-      return Promise.resolve(0);
-    },
-  });
-
-  expect(result.warnings).toEqual(readExpectedJson(fixture, 'warnings.json'));
-  expect(readFileSync(join(fixture.project, '.outfitter/settings.yml'), 'utf8')).toBe(
-    readExpectedText(fixture, 'source-project-settings-after.yml'),
-  );
-});
-```
-
-A fixture can include optional expectation files like:
-
-```text
-expected/
-  composite profile-summary.json
-  warnings.json
-  durable-files-after.json
-  source-project-settings-after.yml
-```
-
-The test decides how much to snapshot.
-Use structured expected files for broad composite profile summaries and explicit inline assertions for the key write-back invariant the test protects.
-
-## Test flow
-
-A typical integration test:
-
-1. Copies a named fixture to a temporary directory.
-2. Runs Outfitter command code with the copied `homeDirectory` and `projectDirectory`.
-3. Uses a fake launcher defined in the Vitest test to inspect the composite profile while it exists.
-4. Mutates declared or undeclared composite profile paths from that fake launcher when the scenario requires it.
-5. Lets normal post-run state detection classify the mutations.
-6. Asserts warnings/errors and durable source files after the command completes, using fixture `expected/` files where snapshots improve readability.
-
-Example fake-launcher responsibilities:
-
-```text
-- Read the adapter config root from launch plan env, such as `PI_CODING_AGENT_DIR` or `CLAUDE_CONFIG_DIR`.
-- Assert generated composite profile files exist.
-- Assert declared persistent paths are symlinks to the expected profile/native/cache sources.
-- Write to declared state paths and unknown files according to the scenario.
-- Return exit code 0 unless the scenario is testing child failure handling.
-```
-
-## Composite profile assertions
-
-Integration tests assert stable behavior, not incidental implementation details.
-Useful composite profile assertions include:
-
-- selected adapter and profile id;
-- resolved profile stack order;
-- generated Outfitter metadata files;
-- generated adapter-specific files such as profile/settings payloads;
-- launch argv and environment;
-- symlink versus temporary materialization for each declared state path;
-- symlink target precedence: project-local profile, project profile, user profile, cache, then native fallback as applicable;
-- non-persistent baseline paths and detected writes;
-- warnings becoming fatal under `--strict`.
-
-## Write-back/state-persistence focus
-
-The integration suite encodes the product rule from `doc/state_writeback_strategy.md`: Outfitter does not do generic post-run copy-back or structured merge-back.
-Durable writes happen only through declared state paths that have a persistent strategy, normally by symlink.
-
-Important cases:
-
-- A generated composite profile file composed from several settings/profile layers is mutated in the composite profile.
-  Current behavior is explicit: the mutation is not generically copied back to any source layer unless that path is an adapter-declared symlink.
-- A state file supplied by a high-precedence profile is symlinked and receives writes directly.
-- A declared state path configured as `warn` or `error` is not persisted.
-- Unknown files written into the composite profile are classified by the adapter's `unknown` strategy and never silently persisted.
-- Cache-backed adapter paths, such as Pi `utilities/` and `bin/`, persist to the configured cache rather than to profile directories.
-
-## Fixture authoring rules
-
-- Prefer realistic fixtures with one clear user/project story.
-- Name fixtures after that story, such as `trivial_repo_only_profile` or `heavily_overridden_engineering`, rather than after an adapter.
-- Include enough settings/profile layers to demonstrate precedence when the scenario is about merging.
-- Use obvious values such as `REMOTE_ONLY`, `USER_ONLY`, `REPO_ONLY`, `LOCAL_ONLY`, and `SHARED` so failed assertions identify the wrong layer immediately.
-- Keep expected output as JSON when possible so tests can diff structured facts.
-- Avoid timestamps, random IDs, host-specific paths, and real credentials.
-- Include a fixture-root `README.md` for every fixture set.
-
-## Extension path
-
-The framework currently includes `trivial_repo_only_profile` as the first implemented fixture.
-Additional fixture-set PRs add the remaining cataloged scenarios under `tests/fixtures/integration/` and extend `tests/integration/composite profile-generation.test.ts` or add focused integration test files when needed.
-
-When adding or changing a fixture:
-
-1. Add or update the fixture root `README.md` in the same change.
-2. Add static fixture files under `home/`, `project/`, optional `cache/` or `native/`, and optional `expected/`.
-3. Add a Vitest integration test that copies the fixture, runs through command code, and asserts the composite profile/write-back behavior.
-4. Update `tests/fixtures/integration/INTEGRATION_TEST_FIXTURES.md` when the fixture's scenario, status, or purpose changes.
-5. Run `npm run check-ci` before opening or updating the PR.

package/doc/specs/validating_requirements_with_rules.md

@@ -1,55 +0,0 @@
-## Validating Requirements with Tests, DeepSchemas, and Review Rules
-
-Formal requirements use RFC 2119 keywords such as MUST, SHOULD, and MAY.
-Each requirement needs an appropriate validation mechanism.
-
-### Use automated TypeScript tests for deterministic requirements
-
-Use tests when a requirement can be checked by exact values, paths, return values, emitted CLI arguments, or structured data.
-
-Examples:
-
-- `PI_CODING_AGENT_DIR` MUST be set to the selected profile directory → assert the generated launch environment contains that exact value.
-- A profile name MUST be rejected when it contains whitespace → assert validation returns an error.
-- The wrapper MUST pass `--extension` for configured bootstrap extensions → assert generated argv contains the expected flag and path.
-
-### Use DeepSchemas for file-level contracts
-
-Use DeepSchemas when a file must satisfy structural or semantic constraints.
-
-- Named DeepSchemas are useful for classes of files, such as all requirement specs.
-- Anonymous DeepSchemas are useful when a rule governs one specific file.
-- Put exact structural checks in JSON Schema when the target file is structured data.
-- Put semantic RFC 2119 requirements in the DeepSchema `requirements` section when judgment is required.
-
-### Use `.deepreview` rules for broad judgment-based policies
-
-Use DeepReview rules when the reviewer must compare changed files, requirements, tests, documentation, or conventions across multiple files.
-
-Examples:
-
-- Requirement files MUST follow the project requirement format.
-- Tests that claim requirement coverage MUST use durable traceability comments.
-- Documentation MUST stay consistent with TypeScript source behavior.
-
-### Anti-patterns
-
-Do not use fragile keyword tests for judgment requirements.
-A test such as `expect(text).toContain("safe")` does not prove that a prompt or policy meaningfully enforces safety.
-
-Do not spend reviewer judgment on facts that TypeScript tests or JSON Schema can verify exactly.
-
-### Test traceability comment format
-
-Tests that validate a formal requirement should use a durable comment immediately before the relevant `it(...)`, `test(...)`, or `describe(...)` block:
-
-```ts
-// THIS TEST VALIDATES A HARD REQUIREMENT (OFTR-008.3).
-// YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES.
-it('rejects stale requirement traceability comments', () => {
-  // ...
-});
-```
-
-Comments should explain durable policy intent.
-They should not reference source line numbers, pull request numbers, or one-time migration context.