@multileaf/ai-workflow 0.1.0

package/docs/README.md

@@ -0,0 +1,20 @@
+# AI Workflow Documentation
+
+AI Workflow is a portable, spec-driven development system for AI coding agents. It installs reusable capabilities, profiles each repository, generates project-specific configuration, and preserves a neutral source of truth across agent targets.
+
+## Documents
+
+- [Product vision](product-vision.md)
+- [Product requirements](product-requirements.md)
+- [Architecture](architecture.md)
+- [Package and resource model](package-model.md)
+- [Adapter model](adapter-model.md)
+- [Security and trust](security.md)
+- [Quality and testing](quality.md)
+- [Token efficiency](token-efficiency.md)
+- [Project intelligence](project-intelligence.md)
+- [Release process](release-process.md)
+- [Release backlog](release-backlog.md)
+- [Backlog](backlog.md)
+
+All generated AI Workflow artifacts are written in English unless the user explicitly requests another language.

package/docs/adapter-model.md

@@ -0,0 +1,16 @@
+# Adapter Model
+
+Adapters translate the neutral resource model into a target agent's conventions.
+
+```text
+Neutral skill → Codex SKILL.md
+Neutral rule  → Cursor .mdc / Claude instruction / AGENTS.md
+Neutral agent → Target agent declaration or best-effort prompt
+Neutral hook  → Native hook, command, or documented fallback
+```
+
+Each adapter must declare supported resource types and lifecycle events. Adapters must never silently discard unsupported resources. They must emit warnings and retain the neutral source.
+
+## Migration
+
+`aiw target <target>` performs a dry-run analysis, reports additions, removals, conflicts, fallbacks, and unsupported features, then renders the new target after confirmation. User-modified generated files require explicit conflict handling.

package/docs/architecture.md

@@ -0,0 +1,66 @@
+# Architecture
+
+```text
+CLI
+ └── Core runtime
+      ├── Package manager
+      ├── Project scanner and profiler
+      ├── AI project interpreter
+      ├── Recommendation engine
+      ├── Personalization engine
+      ├── Resource registry
+      ├── Validation and evidence engine
+      ├── Opt-in telemetry boundary
+      ├── Plugin authoring SDK
+      ├── Local dashboard
+      ├── Multi-agent scheduler
+      └── Adapter manager
+             ├── Codex
+             ├── Claude Code
+             ├── Cursor
+             ├── Gemini CLI
+             ├── GitHub Copilot
+             └── Universal
+```
+
+## Source of truth
+
+`.aiw/` contains the neutral manifest, lockfile, project profile, selected resources, and versioned checkpoints. Generated specifications, plans, docs, and artifacts live under `.aiw/generated/`.
+
+Target files such as `.cursor/rules`, `.claude/skills`, or Codex skill directories are generated by adapters and must not be treated as canonical state.
+
+## Runtime lifecycle
+
+1. Discover the project.
+2. Build or update the project profile.
+3. Resolve package dependencies.
+4. Recommend capabilities.
+5. Request user decisions.
+6. Generate personalized resources.
+7. Render target-specific files.
+8. Validate configuration and evidence.
+9. Record the operation.
+
+Project analysis is hybrid: deterministic detectors establish observable facts, while a scoped AI interpreter explains conventions and produces recommendations. AI output is never confirmed project state without user approval.
+
+## Modularity
+
+The CLI is an entry point, not the business layer. Filesystem, package providers, scanners, recommendation engines, generators, validators, and adapters must be replaceable through interfaces and dependency injection.
+
+## Telemetry
+
+Telemetry is disabled by default and separated from command execution through an injectable client. The core emits only user-approved aggregate fields and does not own a network transport. Collector failures are isolated from workflow results.
+
+## Local dashboard
+
+`aiw ui` starts an HTTP server bound exclusively to `127.0.0.1`. It projects the neutral `.aiw/` state into an English HTML dashboard and JSON read model. The page uses no external assets or client-side scripts. Migration posts require the exact `MIGRATE` confirmation and delegate to the existing target command, preserving its conflict, backup, and rollback behavior.
+
+## Multi-agent orchestration
+
+The orchestration domain parses a strict, versioned task graph and schedules dependency waves with bounded parallelism. Preview is deterministic and read-only. Execution requires the explicit `--execute` flag and an injected `AgentOrchestrator`; this keeps Codex, Claude, Gemini, Orca, and future runtimes outside the core. Failed tasks block only their descendants, while independent work continues. Completed outcomes are recorded once in a versioned `.aiw/checkpoints/orchestration-<plan>.yml` checkpoint.
+
+## Self-hosting
+
+The repository uses the `multileaf/aiw-self-hosting` package. This package supplies the workflow resources required to develop AI Workflow itself, including SDD skills, quality rules, specialist agents, lifecycle hooks, and artifact templates.
+
+Behavioral changes are validated against this repository with `aiw self-validate --ticket=TYPE-000`. The command runs the complete project quality pipeline and writes deterministic evidence to `.aiw/checkpoints/self-validation-<ticket>.yml`, including required AIW state and the generated artifacts inspected during the run. Checkpoints are reviewable project history and are not part of the ignored `.aiw/generated` tree.

package/docs/backlog.md

@@ -0,0 +1,93 @@
+# Product Backlog
+
+Priority levels: **P0** blocks the product or makes it unsafe; **P1** is required for a usable product; **P2** improves scale, quality, or portability; **P3** is an advanced or ecosystem feature.
+
+## Foundation — P0
+
+- [x] **FND-001** Define and validate the neutral `manifest.yaml` schema. _Acceptance:_ invalid manifests produce actionable errors; schema is versioned and tested.
+- [x] **FND-002** Define `package.yaml` and resource contracts. _Acceptance:_ skills, rules, agents, hooks, templates, policies, dependencies, permissions, and provenance are representable.
+- [x] **FND-003** Define adapter contract and capability matrix. _Acceptance:_ adapters report supported resources and lifecycle events.
+- [x] **FND-004** Introduce structured domain types and service interfaces. _Acceptance:_ CLI contains no business logic; services are dependency-injected and unit-testable.
+- [x] **FND-005** Add complete TDD quality pipeline. _Acceptance:_ `check` runs format, lint, typecheck, tests, and security checks.
+- [x] **FND-006** Add CI workflow. _Acceptance:_ every pull request runs all required checks.
+
+## Installation and lifecycle — P0/P1
+
+- [x] **INS-001** Make installation idempotent and non-destructive. _Acceptance:_ repeated installation preserves overrides and reports state.
+- [x] **INS-002** Implement target selection and detection. _Acceptance:_ supported installed agents are detected and user can override detection.
+- [x] **INS-003** Install and register the base `ai-init` skill. _Acceptance:_ generated artifact is valid for every supported target.
+- [x] **INS-004** Implement `status`, `doctor`, and actionable diagnostics. _Acceptance:_ missing, stale, conflicting, and unsupported state is explained.
+- [x] **INS-005** Implement package resolution and lockfile generation. _Acceptance:_ same lockfile produces the same resources.
+- [x] **INS-006** Implement uninstall and repair safely. _Acceptance:_ only AIW-owned generated files are removed or restored.
+
+## Project intelligence — P1
+
+- [x] **SCAN-001** Build ignore-aware repository scanner. _Acceptance:_ respects `.gitignore`, excludes secrets, and has deterministic output.
+- [x] **SCAN-002** Detect languages, frameworks, package managers, scripts, tests, linters, formatters, CI, and workspace structure. _Acceptance:_ fixtures cover common project types.
+- [x] **SCAN-003** Store confidence and evidence for detected facts. _Acceptance:_ each inferred fact points to a source and confidence score.
+- [x] **SCAN-005** Define the hybrid intelligence contract. _Acceptance:_ detected, inferred, and confirmed states are represented and AI inference cannot silently replace deterministic facts.
+- [x] **SCAN-006** Implement scoped AI project interpreter. _Acceptance:_ interpreter receives filtered context and produces structured insights requiring confirmation when uncertain.
+- [x] **SCAN-007** Add interpreter privacy and token guardrails. _Acceptance:_ secrets, dependencies, generated files, Git internals, and checkpoints are excluded and token usage is measured.
+- [x] **SCAN-004** Add interactive confirmation and overrides. _Acceptance:_ users can accept, reject, or edit inferred facts.
+- [x] **REC-001** Build capability recommendation engine. _Acceptance:_ recommendations include rationale, evidence, permissions, conflicts, and confidence.
+- [x] **REC-002** Add interactive capability selection. _Acceptance:_ users select packages and individual resources before installation.
+- [x] **GEN-001** Generate project-specific rules, agents, hooks, and context. _Acceptance:_ generated content uses confirmed profile data and English artifacts.
+- [x] **GEN-002** Preserve manual overrides and detect drift. _Acceptance:_ regeneration never silently overwrites user changes.
+
+## SDD workflow — P1
+
+- [x] **SDD-001** Implement brainstorming artifact and facilitator skill. _Acceptance:_ goals, users, assumptions, constraints, and open questions are captured.
+- [x] **SDD-002** Implement specification skill and template. _Acceptance:_ requirements have stable IDs and acceptance criteria.
+- [x] **SDD-003** Implement design and architecture decision records. _Acceptance:_ alternatives, decisions, and rationale are linked.
+- [x] **SDD-004** Implement implementation planning. _Acceptance:_ tasks link to requirements and validation commands.
+- [x] **SDD-005** Implement verification skill. _Acceptance:_ missing evidence and untested requirements are reported.
+- [x] **SDD-006** Implement requirement-to-evidence traceability graph. _Acceptance:_ requirement → decision → task → code → test → evidence is queryable.
+- [x] **SDD-007** Add quality gates between workflow stages. _Acceptance:_ incomplete artifacts block progression with actionable feedback.
+
+## Adapters and migration — P1/P2
+
+- [x] **ADP-001** Complete Codex adapter. _Acceptance:_ skills, rules, agents, hooks, and context render correctly where supported.
+- [x] **ADP-002** Implement Claude Code adapter.
+- [x] **ADP-003** Implement Cursor adapter.
+- [x] **ADP-004** Implement Gemini CLI adapter.
+- [x] **ADP-005** Implement GitHub Copilot adapter.
+- [x] **ADP-006** Implement universal fallback adapter.
+- [x] **MIG-001** Implement `aiw target <target>` migration. _Acceptance:_ neutral resources are rendered to the new target and manifest is updated.
+- [x] **MIG-002** Add migration dry-run, conflict report, backup, and rollback. _Acceptance:_ failed migration leaves the previous target intact.
+- [x] **MIG-003** Add adapter contract and fixture tests. _Acceptance:_ each adapter passes common rendering and degradation scenarios.
+
+## External ecosystem — P2
+
+- [x] **PKG-001** Implement local and Git package providers.
+- [x] **PKG-002** Integrate Vercel Skills as an external provider. _Acceptance:_ search, inspect, install, lock, and update are represented in AIW state.
+- [x] **PKG-003** Add package audit and permission review before installation.
+- [x] **PKG-004** Add update, compatibility, and dependency conflict workflows.
+- [x] **PKG-005** Create a curated Multileaf package registry.
+- [x] **PKG-006** Add package signing, checksums, and provenance verification.
+
+## Context and cost — P2
+
+- [x] **CTX-001** Build layered project context store.
+- [x] **CTX-002** Add task-scoped context retrieval and delta loading.
+- [x] **CTX-003** Add summary cache and freshness invalidation.
+- [x] **CTX-004** Add per-stage token budgets and usage reporting.
+- [x] **CTX-005** Add context quality metrics and regression tests.
+
+## Enterprise and ecosystem — P3
+
+- [x] **ENT-001** Add organization policies and approved package sources.
+- [x] **ENT-002** Add team-shared presets and private registries.
+- [x] **ENT-003** Add policy enforcement in CI and pull requests.
+- [x] **ENT-004** Add telemetry opt-in with privacy controls. _Acceptance:_ telemetry is disabled by default, users independently control aggregate command/outcome fields, sensitive execution data is never serialized, and collector failures cannot affect workflow results.
+- [x] **ENT-005** Add plugin SDK and package authoring tooling. _Acceptance:_ authors can deterministically scaffold and validate portable packages through the CLI and typed SDK, unsafe paths and overwrites fail atomically, and generated resources are English and contract-valid.
+- [x] **ENT-006** Add web UI for project profile, recommendations, traceability, and migrations. _Acceptance:_ `aiw ui` serves a local-only, responsive and accessible dashboard from packaged project state; profile, recommendations, and requirement evidence are visible; migrations require explicit confirmation and delegate to the existing workflow.
+- [x] **ENT-007** Add multi-agent orchestration and parallel task execution. _Acceptance:_ strict versioned task graphs support deterministic preview, explicit adapter-backed execution, bounded parallelism, dependency-aware failure isolation, and immutable checkpoint evidence.
+
+## Backlog rules
+
+- [x] **FND-009** Add self-validation workflow. _Acceptance:_ changes affecting AIW behavior execute against this repository and record generated-output evidence.
+- Every item must have tests or explicit validation evidence before completion.
+- Every item must validate all affected layers; domain tests alone cannot mark an externally visible feature as complete.
+- New work must identify its affected contract and dependencies.
+- P0 work takes precedence over feature expansion.
+- A task may move to Done only when implementation, tests, documentation, and quality checks pass.

package/docs/orchestration.md

@@ -0,0 +1,50 @@
+# Multi-agent Orchestration
+
+AI Workflow represents coordinated work as a strict, versioned task graph. The core scheduler is provider-neutral: a host integrates Codex, Claude, Gemini, Orca, or another runtime through the exported `AgentOrchestrator` interface.
+
+## Plan format
+
+```yaml
+schema: 1
+id: release-readiness
+tasks:
+  - id: TASK-001
+    agent: codex
+    prompt: "Implement the approved specification."
+    depends_on: []
+  - id: TASK-002
+    agent: claude
+    prompt: "Review the implementation and tests."
+    depends_on: [TASK-001]
+  - id: TASK-003
+    agent: gemini
+    prompt: "Validate documentation and traceability."
+    depends_on: [TASK-001]
+```
+
+Plan identifiers use lowercase letters, numbers, and hyphens. Task identifiers use `TASK-###`. Prompts are JSON-quoted strings, dependencies must reference tasks in the same plan, and cycles are rejected before execution.
+
+## Commands
+
+```bash
+aiw orchestrate --plan=orchestration.yml
+aiw orchestrate --plan=orchestration.yml --execute --max-parallel=2
+```
+
+The first command prints deterministic execution waves and does not invoke an agent or mutate project state. `--execute` requires a host-provided adapter. Parallelism must be an integer from 1 through 16. A failed or unavailable agent marks its task as failed; dependent tasks are blocked, while unrelated tasks continue.
+
+Each executed plan writes one `.aiw/checkpoints/orchestration-<plan-id>.yml` result. Existing checkpoints are never overwritten: use a new plan identifier for a new run. Agent result details are bounded and serialized safely.
+
+## Adapter contract
+
+```ts
+import type { AgentOrchestrator, OrchestrationTask } from "@multileaf/ai-workflow/orchestration";
+
+const orchestrator: AgentOrchestrator = {
+  async run(task: OrchestrationTask) {
+    return { success: true, detail: `${task.id} completed by ${task.agent}` };
+  },
+};
+```
+
+The adapter owns runtime authentication, process isolation, completion detection, and permission enforcement. It must resolve only after the delegated agent has finished. AI Workflow owns graph validation, scheduling, failure propagation, result ordering, and checkpoint persistence.

package/docs/package-model.md

@@ -0,0 +1,53 @@
+# Package and Resource Model
+
+An AI Workflow package is a versioned collection of capabilities.
+
+```text
+package/
+├── package.yaml
+├── skills/
+├── rules/
+├── agents/
+├── hooks/
+├── templates/
+├── policies/
+└── adapters/
+```
+
+## Resource types
+
+- **Skill**: procedural knowledge for an agent.
+- **Rule**: constraint or project policy.
+- **Agent**: specialized role with inputs and outputs.
+- **Hook**: lifecycle-triggered action.
+- **Template**: structure for a project artifact.
+- **Policy**: permissions, quality gates, or governance.
+- **Adapter**: target-specific rendering metadata.
+
+Packages may come from local paths, Git repositories, npm-compatible providers, Vercel Skills, or a future Multileaf registry.
+
+Local directories and Git repositories are resolved with `aiw resolve --source=<source>`. A local source may be a package directory or its `package.yaml`; relative paths are resolved from the project. Git sources support `git+https`, HTTPS, SSH, and `file://` URLs. Git packages are cloned into an isolated temporary checkout, validated before the lockfile is changed, and removed after resolution. The lockfile records the selected provider and normalized source rather than trusting those fields from the fetched manifest. The legacy `--package=<path>` form remains available for direct manifest resolution.
+
+Vercel Skills is exposed through `aiw skills search`, `inspect`, `install`, `check`, and `update`. AIW delegates to the official `npx skills` CLI with argument arrays, requires explicit `network:external` permission for network-mutating/check operations, and records installed skills and upstream integrity in `.aiw/lock.yml`. Update output is inspected for upstream failure text because some CLI releases may report failures with a successful process exit code.
+
+Use `aiw audit-package --package=<path>` before resolution or installation to review requested permissions and their risk levels. Every permission must belong to AIW's known permission catalog, and every requested permission requires an exact `--allow=<permission>` approval. Unknown permissions are rejected even when passed through `--allow`; denied audits and approvals must not modify package state.
+
+Organizations can install a versioned policy with `aiw organization-policy --file=<path>`. The policy defines approved provider/source patterns and denied permissions. A trailing `*` performs an explicit prefix match; all other entries require an exact match. Once configured, AIW validates the provider and source before loading a package, so unapproved Git sources are rejected before a clone or temporary checkout is created. Permissions are validated after the package manifest is loaded and before project state or the lockfile changes; temporary checkouts created for approved Git sources are removed when permission validation fails. Replacing an existing policy requires the explicit `--replace` flag.
+
+Repositories enforce the tracked policy in CI with `aiw policy-check --package=<path>`. The gate validates declared package permissions, every package source in the lockfile, and configured private registries. It fails when the organization policy is missing, malformed, or violated and is intended to run on pushes and pull requests after the normal quality pipeline.
+
+Teams can commit a portable preset with package requirements and named registry references, then install it with `aiw preset --file=<path>`. AIW writes a deterministic copy to `.aiw/team-preset.yml`; replacing it requires `--replace`. Presets contain no credentials.
+
+Private registries are configured with `aiw registry configure --file=<path>`. Each HTTPS registry entry stores a name, URL, and environment-variable reference such as `AIW_ENGINEERING_TOKEN`; inline secrets, URL credentials, query strings, and fragments are rejected. The complete document is validated before an atomic replacement, so malformed entries cannot apply a valid subset or overwrite the previous configuration. `aiw registry --private=<name> --search=<query>` reads the credential only at execution time, applies organization source and `network:external` policy before the request, validates the response and known permissions, and never serializes the token. Registry configuration is stored in `.aiw/registries.yml` and requires `--replace` for updates.
+
+Every package must declare an identifier, package version, provider, source, engine compatibility, resources, dependencies, supported targets, permissions, and provenance. Each resource has its own stable identifier, version, and path.
+
+The project manifest stores requested version ranges. The lockfile stores the exact resolved version, provider, source, integrity information, requested permissions, and resource versions used by the project. The CI policy gate parses every lock entry strictly and evaluates it independently from package manifests, including entries with matching identifiers. Updates compare the requested range with the resolved lockfile version and never rely on a filename or list position.
+
+```yaml
+packages:
+  - id: multileaf/sdd-core
+    requested: ^1.2.0
+    provider: vercel-skills
+    source: vercel-labs/agent-skills
+```

package/docs/plugin-authoring.md

@@ -0,0 +1,31 @@
+# Plugin SDK and Package Authoring
+
+AI Workflow plugins use the same neutral package contract as built-in resources. A plugin can contain skills, rules, agents, hooks, and templates while adapters remain responsible for target-specific rendering.
+
+## Create a plugin
+
+```bash
+aiw plugin create \
+  --directory=plugins/example \
+  --id=acme/example \
+  --version=1.0.0 \
+  --description="Provide an example workflow."
+
+aiw plugin validate --directory=plugins/example
+```
+
+Creation writes an English `README.md`, a valid `package.yaml`, and a starter skill. Output is deterministic. Destinations must remain inside the project, invalid definitions are rejected before writes, and existing scaffold files are never overwritten.
+
+Validation checks the package contract and every declared resource path. It does not execute plugin content or grant permissions.
+
+## TypeScript SDK
+
+The package exports `@multileaf/ai-workflow/plugin-sdk` with:
+
+- `definePlugin` for a typed, immutable package definition;
+- `createPluginScaffold` for deterministic in-memory authoring;
+- `writePluginScaffold` for conflict-safe persistence;
+- `validatePluginDirectory` for project-root-confined contract and resource validation;
+- `resolvePluginDirectory` for project-confined paths.
+
+The filesystem boundary is injected, so hosts can test authoring without disk access. Package permissions and organization policies are still enforced by the normal installation and resolution workflow.

package/docs/product-requirements.md

@@ -0,0 +1,57 @@
+# Product Requirements
+
+## Functional requirements
+
+### Installation
+
+- The CLI must install with `npx @multileaf/ai-workflow install`.
+- Installation must support Codex, Claude Code, Cursor, Gemini CLI, GitHub Copilot, and a universal target over time.
+- Installation must be idempotent and preserve user overrides.
+- Installation must create a neutral `.aiw/` source of truth.
+- Generated specifications, plans, docs, and artifacts must live under `.aiw/generated/` and be ignored by Git.
+- Checkpoints must live under `.aiw/checkpoints/` and remain versioned.
+
+### Initialization
+
+- `/ai-init` must scan a repository safely.
+- The scanner must identify languages, frameworks, package managers, commands, tests, linters, formatters, CI, and project structure.
+- The analysis pipeline must combine deterministic detectors with a scoped AI interpreter.
+- Facts and inferences must be stored separately with evidence, confidence, method, and confirmation state.
+- The interpreter must receive filtered context and exclude secrets, dependencies, generated files, Git internals, and checkpoints by default.
+- Recommendations must explain their evidence, capabilities, permissions, and conflicts.
+- The user must select which capabilities to install.
+- Selected resources must be customized using confirmed project facts.
+
+### Development workflow
+
+- The product must support brainstorming, specification, design, planning, implementation, and verification stages.
+- Requirements, decisions, tasks, code changes, tests, and evidence must be traceable.
+- A task must not be considered complete without configured validation evidence.
+
+### Portability
+
+- `aiw target <target>` must migrate generated resources to another target.
+- Unsupported features must be reported and preserved in neutral form.
+- Migration must support dry-run, conflict detection, backups, and rollback.
+
+### Governance
+
+- Packages must declare versions, dependencies, permissions, supported targets, and provenance.
+- Generated files must be distinguishable from user-owned files.
+- Lockfiles must make installations reproducible.
+
+### Local dashboard
+
+- `aiw ui` must expose project profile, recommendations, traceability, and target migration from a loopback-only web interface.
+- The dashboard must render project data safely without external assets, third-party scripts, telemetry, or a separate source of truth.
+- Target migration must require explicit confirmation and use the same workflow service as the CLI.
+- Read-only dashboard requests must not mutate project state.
+
+## Non-functional requirements
+
+- TypeScript code must pass formatting, linting, type checking, and tests.
+- Core services must be independently unit-testable.
+- Scanner access must exclude secrets and ignored paths by default.
+- The runtime must provide useful behavior when an adapter has reduced capabilities.
+- Token budgets and context usage must be observable.
+- Changes must be validated against the AI Workflow repository itself when the relevant capability exists.

package/docs/product-vision.md

@@ -0,0 +1,26 @@
+# Product Vision
+
+## Summary
+
+AI Workflow makes AI-assisted software development reproducible, inspectable, and portable. It turns brainstorming into specifications, specifications into implementation plans, and implementation into verifiable evidence.
+
+## Problem
+
+AI coding tools often depend on implicit prompts, fragmented configuration, repeated context, and vendor-specific files. Teams need a consistent development process without committing to one agent or manually maintaining every integration.
+
+## Product principles
+
+1. Specifications and decisions are the source of truth.
+2. Generated target files are derived artifacts.
+3. The user approves recommendations and meaningful changes.
+4. Every requirement should have validation evidence.
+5. Project artifacts are English by default.
+6. Context is loaded just in time to control token cost.
+7. Unsafe capabilities require explicit permission.
+
+## Product outcomes
+
+- A new repository can be configured through one guided initialization.
+- The same AI development environment can migrate between agents.
+- Project-specific rules are generated from detected and confirmed facts.
+- Teams can review AI behavior through versioned files and traceability.

package/docs/project-intelligence.md

@@ -0,0 +1,59 @@
+# Project Intelligence
+
+AI Workflow uses a hybrid analysis pipeline.
+
+```text
+Deterministic detectors → Detected project profile → Relevant context selection
+→ AI interpreter → Insights and recommendations → User confirmation
+→ Confirmed project profile
+```
+
+## Deterministic layer
+
+Detectors establish observable facts: files, dependencies, versions, package managers, scripts, frameworks, quality tools, tests, CI, workspaces, ignored paths, and configuration files. Each fact includes its source and detection method.
+
+```yaml
+fact: tool.eslint
+value: true
+source: eslint.config.js
+method: deterministic
+confidence: 1.0
+```
+
+## AI interpretation layer
+
+The interpreter handles architecture conventions, naming patterns, testing style, implicit policies, documentation consistency, contradictions, and capability recommendations. It receives filtered context rather than the entire repository.
+
+The runtime exposes a provider-neutral `AiProvider` interface. Provider adapters receive an English system instruction, a scoped prompt, a token ceiling, and a JSON response requirement. The interpreter validates and normalizes that response into evidence facts; provider output cannot choose evidence state or cite a file outside the supplied context.
+
+```yaml
+fact: architecture.style
+value: feature-based
+sources: [src/features]
+confidence: 0.78
+method: ai-inference
+requires_confirmation: true
+```
+
+## Evidence states
+
+- `detected`: observed by a deterministic detector.
+- `inferred`: proposed by the AI interpreter.
+- `confirmed`: accepted or edited by the user.
+
+Only detected and confirmed data may drive automatic generation. Inferred data requires confirmation when it changes generated behavior.
+
+## Context controls
+
+The interpreter excludes secrets, binaries, generated output, dependencies, Git internals, and checkpoints by default. It receives only files relevant to the active analysis task.
+
+The request contract also carries a positive `maxTokens` ceiling and a deterministic `estimatedTokens` measurement capped at that ceiling. Provider calls receive the same ceiling, while token usage can be recorded through the per-stage usage ledger.
+
+Before a provider call, the interpreter:
+
+- normalizes and filters relative paths;
+- reads only eligible text files inside the project root;
+- redacts common credential assignments, bearer tokens, and private keys;
+- rejects inferred evidence that cites any file outside the scoped request.
+
+The workflow accepts an injected interpreter service. A configured interpreter runs during `aiw scan`, and its structured facts are stored in `.aiw/profile.yml` alongside deterministic facts. Facts below the confidence threshold are marked `requires_confirmation: true`. Without a configured provider, scans remain deterministic and do not make a network request.

package/docs/quality.md

@@ -0,0 +1,32 @@
+# Quality and Testing
+
+Development follows TDD:
+
+```text
+Red → Green → Refactor → Verify
+```
+
+## Required checks
+
+- Unit tests for pure functions and domain services.
+- Integration tests for filesystem and package workflows.
+- Contract tests for every adapter.
+- End-to-end tests for install, init, sync, migration, and rollback.
+- ESLint for code quality.
+- Prettier for formatting.
+- TypeScript strict compilation.
+- Dependency and code security scans.
+
+No feature is complete without tests for its happy path, invalid input, conflicts, and safe failure behavior.
+
+## Completion validation
+
+A feature is complete only when all affected layers are validated: domain, module integration, CLI or adapter integration, generated artifacts, end-to-end behavior, documentation, traceability, and security. Domain tests alone are insufficient for changes that affect external behavior or generated project state.
+
+Externally visible tasks also require an isolated integration run by an AI subagent in a separate worktree. That run must use the packaged or executable workflow, record its outcomes, and leave the validation worktree clean.
+
+Every launched subagent must be instructed to send a direct Orca orchestration message to the coordinator terminal when it finishes; a mailbox-only notification is insufficient. The message must include its status, validation summary, failures, and worktree cleanliness.
+
+## Self-validation
+
+AI Workflow must use itself to validate changes whenever the current capabilities support the task. Changes affecting installation, scanning, generation, migration, adapters, or project configuration must be executed against this repository and their generated output must be inspected. Unit tests alone are not sufficient for these changes.

package/docs/release-backlog.md

@@ -0,0 +1,7 @@
+# Release Backlog
+
+## Version 0.1.0
+
+- [x] **REL-001** Prepare a reproducible release candidate. _Acceptance:_ metadata, changelog, package allowlist, clean compilation, automated release checks, exact-tarball smoke tests, and provenance-ready CI are present and validated.
+- [x] **REL-002** Approve the public package license and configure secure npm publishing for `MultiLeaf/aiw`. _Acceptance:_ MIT is approved, the granular bootstrap token is stored only as an environment secret, and the protected GitHub `npm` environment requires review, rejects administrative bypass, and accepts only version tags.
+- [ ] **REL-003** Publish and verify version `0.1.0`. _Acceptance:_ the signed Git tag, GitHub release, npm package, provenance statement, clean `npx` installation, and post-publication smoke tests all agree on the immutable version.

package/docs/release-process.md

@@ -0,0 +1,38 @@
+# Release Process
+
+AI Workflow releases are reproducible, evidence-backed, and published only from a clean protected branch.
+
+## Preconditions
+
+- The release version follows Semantic Versioning and matches the intended Git tag.
+- `CHANGELOG.md` contains the release date and user-visible changes.
+- The package declares the approved MIT License.
+- The npm account is authenticated and authorized for the `@multileaf` scope.
+- The GitHub `npm` environment requires release approval and the tagged commit belongs to `origin/main`.
+- `main` is clean, synchronized with `origin/main`, and the complete backlog remains validated.
+
+## Validation
+
+```bash
+npm ci
+npm run release:check
+```
+
+The release check runs formatting, linting, strict type checks, a build, tests, dependency audit, organization policy enforcement, and package-content validation. The package validator rejects internal state, source files, test output, fixtures, or nested tarballs and requires the executable, public declarations, resources, documentation, README, and changelog.
+
+Install the exact candidate tarball in a new temporary project and exercise at least installation, help, doctor, scan, target migration dry-run, and the public SDK exports. Record its SHA-256 digest in the release evidence.
+
+## Publication
+
+After human review of the package contents and legal license, create and push a signed version tag. The release workflow validates the exact tagged source and publishes with npm trusted publishing and provenance:
+
+```bash
+git tag -s v0.1.0 -m "AI Workflow v0.1.0"
+git push origin v0.1.0
+```
+
+For the first publication only, create a short-lived granular npm token scoped to `@multileaf/ai-workflow` with package read/write access and add it as the `NPM_TOKEN` secret in the protected GitHub `npm` environment. The token is exposed only to the publish step, which still generates provenance from the GitHub-hosted runner. Do not store the token in project files, shell history, workflow output, or documentation.
+
+After `0.1.0` exists, configure organization `MultiLeaf`, repository `aiw`, workflow `release.yml`, and environment `npm` as a trusted publisher in the package settings. Publish a subsequent release through OIDC and verify its provenance on npm before deleting the GitHub bootstrap secret and revoking the granular token. A saved publisher configuration alone is insufficient evidence because npm validates it only during publication.
+
+The workflow uses Node 24 and npm 11.5.1 or newer, strictly validates Semantic Versioning, checks that the tag is `v<package-version>`, requires the approved license, and verifies ancestry from `origin/main`. Publish each tag only once; never reuse, move, or overwrite a published version.

package/docs/security.md

@@ -0,0 +1,18 @@
+# Security and Trust
+
+AI Workflow can install instructions and execute hooks, so packages are supply-chain inputs.
+
+## Controls
+
+- Validate manifests before installation.
+- Pin resolved versions in `lock.yaml`.
+- Record source and checksums where available.
+- Declare filesystem, shell, network, and secret permissions.
+- Require confirmation for privileged hooks.
+- Exclude secret files and ignored paths from scans.
+- Provide `--dry-run`, audit output, and rollback.
+- Run dependency and code security scans in CI.
+- Enforce the tracked organization policy on every push and pull request with `npm run policy:check`.
+- Keep telemetry disabled by default and exclude arguments, paths, content, output, errors, credentials, and identifiers from its event contract.
+
+Packages with critical or high vulnerabilities, malicious provenance, archival status, or stale maintenance should be rejected or require an explicit documented override.

package/docs/telemetry.md

@@ -0,0 +1,28 @@
+# Telemetry and Privacy
+
+AI Workflow telemetry is disabled by default. No event is recorded unless a user explicitly runs `aiw telemetry enable` and a host application provides a telemetry client.
+
+## Controls
+
+```bash
+aiw telemetry status
+aiw telemetry enable --commands=include --outcomes=include
+aiw telemetry enable --commands=exclude --outcomes=include
+aiw telemetry disable
+```
+
+Preferences are stored in `.aiw/telemetry.yml`. Command and outcome collection can be enabled or excluded independently. Disabling telemetry takes effect before the next event can be recorded.
+
+Rejected telemetry administration commands never produce telemetry events, even when a previous valid configuration enabled collection. This keeps malformed consent or privacy changes outside the telemetry stream.
+
+## Data contract
+
+An event contains only:
+
+- schema version;
+- the top-level command name, when allowed;
+- success or failure, when allowed.
+
+Events never contain command arguments, file paths, project names, file contents, environment variables, prompts, output, error messages, credentials, or stable user/project identifiers. Invalid command names are reported as `unknown` instead of being copied into an event.
+
+The telemetry subsystem does not define a network endpoint or transport. Delivery is provided exclusively through the injectable `TelemetryClient` boundary. Other product features, such as private registries, have separate network boundaries and are not telemetry transports. Missing or failing telemetry collectors cannot change a workflow command's result.

package/docs/token-efficiency.md

@@ -0,0 +1,16 @@
+# Token Efficiency
+
+Token efficiency is a runtime concern, not only a prompt-writing concern.
+
+## Strategies
+
+- Store facts, decisions, and conversation summaries separately.
+- Load context by task and dependency rather than sending the whole repository.
+- Use stable identifiers for requirements and decisions.
+- Send deltas after the first context load.
+- Cache project profiles and generated summaries.
+- Track context freshness and invalidate stale summaries.
+- Apply budgets by workflow stage.
+- Measure tokens per agent, package, task, and verification cycle.
+
+The runtime should prefer references such as `AUTH-REQ-04` and retrieve their content only when needed.