@multileaf/ai-workflow 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-09-12
+
+### Fixed
+
+- Keep first install limited to the `ai-init` bootstrap and neutral AI Workflow state; install optional capabilities only after the project scan and explicit user selection.
+- Materialize only selected skills, rules, agents, hooks, and templates, and personalize supported rules with detected project commands.
+- Allow non-interactive recommendation previews without silently selecting or installing capabilities.
+
+## [0.1.1] - 2026-09-12
+
+### Fixed
+
+- Activate the complete bundled workflow package during installation instead of installing only `ai-init`.
+- Preserve user edits during migration rollback and remove migration checkpoints during uninstall.
+- Match Git ignore rules consistently when scanning projects.
+
+### Security
+
+- Validate package manifests and resource paths, verify local package integrity, and redact credentials from scanned context.
+- Track installed-file ownership so uninstall and migration only remove unchanged AI Workflow files.
+- Require organization approval and explicit consent before loading remote package sources.
+
+### Changed
+
+- Update runtime and development dependencies and expand install, migration, rollback, and security coverage.
+
 ## [0.1.0] - 2026-09-04
 
 ### Added
@@ -18,5 +44,7 @@ All notable changes to this project are documented in this file. The format foll
 
 - Path confinement, symlink protection, explicit permission gates, secret redaction, strict parsers, atomic migrations, and immutable execution checkpoints.
 
-[Unreleased]: https://github.com/MultiLeaf/aiw/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/MultiLeaf/aiw/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/MultiLeaf/aiw/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/MultiLeaf/aiw/releases/tag/v0.1.1
 [0.1.0]: https://github.com/MultiLeaf/aiw/releases/tag/v0.1.0

package/README.md

@@ -1,32 +1,335 @@
 # AI Workflow
 
-Portable spec-driven development workflow for AI coding agents.
+AI Workflow is a portable, spec-driven development system for AI coding agents. It gives a repository a repeatable path from discovery and brainstorming to requirements, implementation plans, code, and verification evidence without coupling the project to one AI provider.
+
+It can configure Codex, Claude Code, Cursor, Gemini CLI, GitHub Copilot, or a provider-neutral layout from the same canonical project state.
+
+## Why AI Workflow
+
+AI-assisted development often relies on implicit prompts, duplicated configuration, and tool-specific files that drift over time. AI Workflow makes that process explicit and reviewable:
+
+- project facts are detected before recommendations are made;
+- inferred conventions require confirmation before they drive generation;
+- specifications and decisions remain the source of truth;
+- skills, rules, agents, hooks, and templates are versioned resources;
+- target-specific files are generated through adapters;
+- quality gates and checkpoints provide completion evidence;
+- context is filtered and loaded only when needed to reduce token usage;
+- package-declared sensitive capabilities are evaluated by policy boundaries.
 
 ## Installation
 
+The published package supports Node.js 18 or newer. Full development checks require Node.js 20.19 or newer for the current lint and test toolchain; CI runs on Node.js 20 and release validation runs on Node.js 24. Node.js 18 remains the declared runtime floor but is not currently in the release validation matrix.
+
 ```bash
 npx @multileaf/ai-workflow install --target codex
 ```
 
-Replace `codex` with `claude`, `cursor`, `gemini`, `copilot`, or `universal` when needed. Every command follows `npx @multileaf/ai-workflow <command> <options>`.
+Then run `/ai-init` in Codex. The bootstrap scans the repository, explains project-specific recommendations, and waits for the user's selections before installing optional resources.
 
-## Development
+Supported targets are `codex`, `claude`, `cursor`, `gemini`, `copilot`, and `universal`. Every command uses the same entry point:
 
 ```bash
-npm install
-npm run build
-node dist/cli.js install --target codex
-node dist/cli.js ui
+npx @multileaf/ai-workflow <command> <options>
+```
+
+The initial installation creates workflow state and a target-specific `ai-init` skill. Run it in a repository that does not already use the reserved bootstrap paths shown below: first installation currently writes the base ADR index and target `ai-init` file at those paths. Reinstallation detects existing AI Workflow state and preserves it.
+
+## What gets created
+
+For a Codex installation, the base layout is:
+
+```text
+.agents/
+└── skills/
+    └── ai-init/SKILL.md
+.context/
+└── adrs/
+    └── INDEX.md
+.aiw/
+├── checkpoints/
+├── context/
+├── generated/
+│   ├── artifacts/
+│   ├── docs/
+│   ├── plans/
+│   └── specs/
+├── lock.yml
+├── manifest.yml
+└── profile.yml
+```
+
+`.aiw/` stores the provider-neutral manifest, profile, lockfile, checkpoints, bootstrap skill, selected resources, and generated working artifacts. ADRs are stored under `.context/adrs/`. The installer intentionally adds only `ai-init` and the base project state.
+
+Run `/ai-init` in the selected coding agent to scan the project and review evidence-based recommendations for skills, rules, agents, hooks, and templates. AI Workflow installs only the resources the user selects, then generates project-specific quality guidance from the detected stack and tools. Existing user files are preserved; conflicts are reported instead of overwritten. Hook resources are rendered according to each adapter's native or compatibility support.
+
+The installer does not modify `.gitignore`. Add `.aiw/generated/` yourself if generated specifications, plans, and artifacts should remain local. Versioned files under `.aiw/checkpoints/` are designed to remain reviewable project history.
+
+### Installation and configuration flow
+
+```mermaid
+flowchart TD
+    A[Run aiw install] --> B{Target provided?}
+    B -->|Yes| C[Validate selected target]
+    B -->|No| D[Detect installed AI tools]
+    D --> E{One supported target?}
+    E -->|Yes| C
+    E -->|No| F[Request or require target selection]
+    F --> C
+
+    C --> G[Create base directories]
+    G --> H[Write manifest, profile, and lock state]
+    H --> I[Create ADR index]
+    I --> J[Render ai-init through target adapter]
+    J --> K[Installed project]
+
+    K --> L[Run ai-init or aiw scan]
+    L --> M[Ignore-aware deterministic scan]
+    M --> N[Optional filtered AI interpretation]
+    N --> O[Write confirmed and inferred facts to profile.yml]
+    O --> P[Generate recommendations.yml]
+    P --> Q{User selection and confirmation}
+    Q -->|Accept or edit| R[Resolve packages and resources]
+    Q -->|Reject| S[Persist override decision]
+    R --> T[Update lock.yml]
+    T --> U[Generate project-specific resources]
+    U --> V[Render resources through active adapter]
+    V --> W[Record applicable checkpoint evidence]
+
+    K --> X[Run aiw target TARGET]
+    X --> Y[Dry-run and conflict review]
+    Y --> Z[Write migration checkpoint]
+    Z --> AA[Render destination resources]
+    AA --> AB[Update active target in manifest.yml]
+    AB --> AC{Rollback requested?}
+    AC -->|Yes| AD[Restore files and manifest from checkpoint]
+    AC -->|No| AE[Continue with new target]
+
+    H -. project state .-> STATE[(.aiw/*.yml)]
+    W -. session and validation history .-> LOGS[(.aiw/checkpoints/)]
+    I -. decisions index .-> ADRS[(.context/adrs/INDEX.md)]
 ```
 
-The project configuration lives in `.aiw/`; target-specific files are generated by adapters.
+## The SDD workflow
+
+AI Workflow supports an end-to-end specification-driven development cycle:
+
+```mermaid
+flowchart TD
+    A[Project request] --> B[Scan repository]
+    B --> C[(.aiw/profile.yml)]
+    C --> D[Recommend capabilities]
+    D --> E[(.aiw/recommendations.yml)]
+    E --> F{User confirms scope}
+    F -->|Revise| B
+    F -->|Proceed| G[Brainstorm]
+
+    G --> H[(generated/specs/brainstorm.md)]
+    H --> I{Brainstorm gate}
+    I -->|Incomplete| G
+    I -->|Complete| J[Write specification]
+
+    J --> K[(generated/specs/specification.md)]
+    K --> L{Specification gate}
+    L -->|Incomplete| J
+    L -->|Complete| M{Architecture decision needed?}
 
-Telemetry is disabled by default. Use `aiw telemetry status`, `enable`, or `disable` to manage explicit privacy preferences. See [Telemetry and Privacy](docs/telemetry.md).
+    M -->|Yes| N[Create ADR]
+    N --> O[(.context/adrs/ADR-NNN-title.md)]
+    O --> P[Update ADR index]
+    P --> Q[(.context/adrs/INDEX.md)]
+    M -->|No| R[Create implementation plan]
+    Q --> R
+
+    R --> S[(generated/plans/implementation-plan.md)]
+    S --> T{Plan gate}
+    T -->|Incomplete| R
+    T -->|Ready| U[Implement tasks with TDD]
+
+    U --> V[Write code and tests]
+    V --> W[Run task validation commands]
+    W --> X{Validation passes?}
+    X -->|No| U
+    X -->|Yes| Y[Record completion evidence]
+
+    Y --> Z[(generated/artifacts and checkpoint evidence)]
+    Z --> AA[Verify declared evidence]
+    AA --> AB{Verification gate}
+    AB -->|Missing evidence| U
+    AB -->|Complete| AC[Build traceability graph]
+
+    AC --> AD[Requirement → ADR → Task → Code → Test → Evidence]
+    AD --> AE[(generated artifacts and trace output)]
+    AE --> AF[Run repository self-validation]
+    AF --> AG[(.aiw/checkpoints/self-validation-TICKET.yml)]
+    AG --> AH{Review outcome}
+    AH -->|Changes required| U
+    AH -->|Accepted| AI[Commit and independent integration validation]
+
+    B -. command history and evidence .-> LOGS[(.aiw/checkpoints/)]
+    D -. command history and evidence .-> LOGS
+    U -. implementation session evidence .-> LOGS
+    AI -. final validation result .-> LOGS
+```
+
+```bash
+# Detect the repository stack, tools, scripts, and conventions.
+npx @multileaf/ai-workflow scan
+
+# Review recommendations interactively in a TTY.
+npx @multileaf/ai-workflow recommend
+
+# In CI, provide comma-separated recommendation IDs detected for that project.
+npx @multileaf/ai-workflow recommend --select=typescript-quality,vitest-testing
+
+# Create structured product artifacts.
+npx @multileaf/ai-workflow brainstorm --title="Feature name"
+npx @multileaf/ai-workflow spec --title="Feature requirements"
+npx @multileaf/ai-workflow adr --id=001 --title="Technical decision"
+npx @multileaf/ai-workflow plan --title="Implementation plan"
+
+# Fill the generated scaffold sections before running their quality gates.
+npx @multileaf/ai-workflow gate specification
+npx @multileaf/ai-workflow verify
+npx @multileaf/ai-workflow trace
+```
+
+Scaffold commands write deterministic files at fixed paths and a repeated invocation replaces that scaffold. Complete and review each artifact before advancing. Requirements use stable identifiers and Given/When/Then acceptance criteria. Plans link tasks to requirements, tests, risks, dependencies, and expected evidence. `gate` performs textual completeness checks, `verify` validates the expected verification fields rather than running a test command, and `trace` records declared links between requirements, decisions, tasks, code, tests, and evidence.
+
+## Project intelligence
+
+Analysis uses two complementary layers:
+
+1. Deterministic detectors identify observable facts such as languages, package managers, workspaces, frameworks, scripts, tests, linters, CI, and configuration files.
+2. An optional provider-neutral AI interpreter examines a filtered context to suggest architecture conventions and capabilities.
+
+Detected facts cannot be replaced by conflicting AI output. Inferred facts remain unconfirmed until the user accepts, rejects, or edits them. Context selection excludes known sensitive filenames, binaries, dependencies, Git internals, generated output, and checkpoints, then applies pattern-based redaction. This is a defense-in-depth filter, not a general secret scanner; review eligible text before enabling an external AI provider.
+
+## Resource packages and recommendations
+
+Resources are distributed as versioned packages that may contain:
+
+- skills for repeatable workflows;
+- rules for project and organization policy;
+- specialist agent definitions;
+- lifecycle hooks;
+- artifact templates;
+- dependencies, permissions, target support, and provenance metadata.
+
+```bash
+npx @multileaf/ai-workflow registry
+npx @multileaf/ai-workflow skills search --query=react
+
+# Install locally before addressing files inside the package's node_modules path.
+npm install --save-dev @multileaf/ai-workflow
+npx @multileaf/ai-workflow audit-package \
+  --package=node_modules/@multileaf/ai-workflow/resources/package.yaml
+npx @multileaf/ai-workflow resolve \
+  --package=node_modules/@multileaf/ai-workflow/resources/package.yaml
+```
+
+The registry can combine local packages, configured private registries, and Vercel Skills metadata. Vercel operations invoke the external `npx skills` CLI and therefore require network access outside AI Workflow's package-permission gate. Lock entries record the provider, reported version, source, permissions, and available integrity metadata. Local package entries contain a SHA-256 digest of the manifest and declared resource bytes; upstream providers may use their own integrity format.
+
+## Switching AI targets
+
+The neutral state can be rendered for another supported agent:
+
+```bash
+npx @multileaf/ai-workflow target claude --dry-run
+npx @multileaf/ai-workflow target claude
+```
+
+Migration provides a deterministic dry-run, reports malformed neutral resources and conflicts, writes a rollback checkpoint, and handles the active `ai-init` transition. Neutral package resources are rendered to the destination adapter. It removes obsolete target files only when `.aiw/ownership.yml` proves AIW created them and their bytes are unchanged; unowned or modified files are preserved and reported. Older installations without ownership records cannot safely clean up legacy target files, so review the dry-run and resolve conflicts before migrating. If needed:
+
+```bash
+npx @multileaf/ai-workflow rollback
+```
+
+Use `capabilities --target=<target>` to inspect aggregate supported resource types, lifecycle events, and whether the target uses fallback compatibility. See [Adapter Model](docs/adapter-model.md) for the native and compatibility path matrix.
+
+## Health, recovery, and visibility
+
+```bash
+npx @multileaf/ai-workflow status
+npx @multileaf/ai-workflow doctor
+npx @multileaf/ai-workflow repair
+npx @multileaf/ai-workflow uninstall --dry-run
+npx @multileaf/ai-workflow uninstall
+npx @multileaf/ai-workflow ui
+```
+
+Install records hashes for the neutral and target resources it creates in `.aiw/ownership.yml`. Uninstall's dry-run lists files it would remove and modified or unsafe files it would preserve. Uninstall deletes only resources whose current bytes still match the inventory, removes the migration rollback checkpoint, then removes AIW state; modified resources are preserved and reported. For older installations without an ownership inventory, uninstall refuses to delete target resources because their ownership cannot be established. The local dashboard binds only to `127.0.0.1`, reads project state from `.aiw/`, and requires the exact `MIGRATE` confirmation before changing targets. `doctor` checks the required installation structure, ownership inventory, manifest schema, and active target. `repair` recreates a defined subset of required directories and files; it does not repair arbitrary malformed profile or lock content, and a missing profile may still require reinstallation or regeneration.
+
+## Multi-agent orchestration
+
+AI Workflow can preview and execute a strict, versioned task graph:
+
+Create `orchestration.yml` using the schema in [Multi-agent Orchestration](docs/orchestration.md), then preview it:
+
+```bash
+npx @multileaf/ai-workflow orchestrate --plan=orchestration.yml
+npx @multileaf/ai-workflow orchestrate --plan=orchestration.yml --execute --max-parallel=4
+```
+
+Preview is deterministic and read-only. Execution is opt-in and requires an application host to inject an `AgentOrchestrator`; the standalone CLI does not configure one, so its `--execute` form fails clearly until integrated by a host. Dependencies, bounded concurrency, failure propagation, replay protection, and checkpoint evidence are handled by the orchestration domain. The typed contract is exported from `@multileaf/ai-workflow/orchestration`.
+
+## Plugins and SDK
+
+Create portable extensions without coupling them to the CLI implementation:
+
+```bash
+npx @multileaf/ai-workflow plugin create \
+  --directory=plugins/plugin-name \
+  --id=owner/plugin-name \
+  --version=1.0.0 \
+  --description="Provide a portable workflow."
+npx @multileaf/ai-workflow plugin validate --directory=plugins/plugin-name
+```
+
+The typed SDK is available from `@multileaf/ai-workflow/plugin-sdk`. It exports scaffold and validation helpers that accept an injected filesystem boundary. Those helpers validate project-relative paths and preflight scaffold conflicts; AI Workflow does not currently host arbitrary plugin runtime code or inject a filesystem into executing plugins. See [Plugin Authoring](docs/plugin-authoring.md).
+
+## Privacy and security
+
+Telemetry is disabled by default and requires explicit consent. It records only approved aggregate fields through an injectable transport.
+
+```bash
+npx @multileaf/ai-workflow telemetry status
+npx @multileaf/ai-workflow telemetry enable
+npx @multileaf/ai-workflow telemetry disable
+```
+
+Package contracts, declared permissions, and organization policy are validated at documented workflow boundaries, but not every external subprocess is covered by one global preflight. In particular, Vercel Skills delegates to `npx skills`, and Git sources may be checked out before their package manifest can be inspected. Treat third-party sources as untrusted and review dry-runs and package audits. Published npm releases include registry signatures and SLSA provenance that consumers can verify with `npm audit signatures`. See [Security and Trust](docs/security.md) and [Telemetry and Privacy](docs/telemetry.md).
+
+## Developing this repository
+
+This project uses itself to validate its own workflow. Product changes follow TDD, pass the complete quality pipeline, run against this repository, and produce ticket-specific checkpoint evidence.
+
+```bash
+npm ci
+npm run check
+node dist/cli.js self-validate --ticket=TYPE-000
+```
+
+Release candidates additionally require:
+
+```bash
+npm run release:check
+```
 
-Create portable plugins with `aiw plugin create` and validate them with `aiw plugin validate`. The typed SDK is exported from `@multileaf/ai-workflow/plugin-sdk`; see [Plugin Authoring](docs/plugin-authoring.md).
+## Documentation
 
-Inspect project state in the local dashboard with `aiw ui`. It binds to `127.0.0.1`, loads only `.aiw/` project state, and requires explicit confirmation before target migration.
+- [Documentation index](docs/README.md)
+- [Product vision](docs/product-vision.md)
+- [Product requirements](docs/product-requirements.md)
+- [Architecture](docs/architecture.md)
+- [Project intelligence](docs/project-intelligence.md)
+- [Package and resource model](docs/package-model.md)
+- [Adapter model](docs/adapter-model.md)
+- [Quality and testing](docs/quality.md)
+- [Token efficiency](docs/token-efficiency.md)
+- [Multi-agent orchestration](docs/orchestration.md)
+- [Release process](docs/release-process.md)
 
-Preview a versioned multi-agent task graph with `aiw orchestrate --plan=orchestration.yml`. Execution is opt-in through `--execute`, uses a host-provided agent adapter, limits concurrency with `--max-parallel`, and records results under `.aiw/checkpoints/`. The scheduler and adapter contract are exported from `@multileaf/ai-workflow/orchestration`; see [Multi-agent Orchestration](docs/orchestration.md).
+## License
 
-Release candidates must pass `npm run release:check`. AI Workflow is available under the MIT License.
+[MIT](LICENSE) © 2026 MultiLeaf

package/dist/adapter.d.ts

@@ -3,6 +3,7 @@ import type { ResourceType } from "./package-contract.js";
 export declare function isTarget(value: string): value is Target;
 export declare function detectTarget(root: string, fs: FileSystem): Target | undefined;
 export declare function generateAiInit(root: string, target: string, fs: FileSystem): void;
+export declare function renderAiInit(target: string): string;
 export declare function renderAiInitPath(target: Target): string;
 export declare function renderResourcePath(target: Target, type: ResourceType, id: string): string;
 export type AdapterResourceType = ResourceType | "context";

package/dist/adapter.js

@@ -21,10 +21,46 @@ export function detectTarget(root, fs) {
     return markers.find(([, marker]) => fs.exists(join(root, marker)))?.[0];
 }
 export function generateAiInit(root, target, fs) {
+    if (!isTarget(target))
+        throw new Error(`Unsupported target: ${target}`);
+    fs.write(join(root, renderAiInitPath(target)), renderAiInit(target));
+}
+export function renderAiInit(target) {
     if (!isTarget(target))
         throw new Error(`Unsupported target: ${target}`);
     getAdapterCapabilities(target);
-    fs.write(join(root, renderAiInitPath(target)), `---\nname: ai-init\ndescription: Analyze the project and configure AI Workflow.\n---\n\n# AI Init\n\nAnalyze the repository safely and recommend project-specific capabilities.\n\n## Language Policy\n\nAll generated AI Workflow artifacts must be written in English unless the user explicitly requests another language.\n`);
+    return `---
+name: ai-init
+description: Initialize AI Workflow and run its specification-driven development setup.
+---
+
+# AI Workflow Initialization
+
+This skill is the bootstrap for AI Workflow. The installer intentionally installs only this skill and the provider-neutral project state. Do not copy or activate the full resource package automatically.
+
+## First-run setup
+
+1. Inspect the repository's existing AI instructions and project structure. Preserve user-authored files and do not expose secrets.
+2. Run \`aiw scan\`. Explain the detected facts and their evidence; ask the user to confirm uncertain inferences before they influence generated content.
+3. Run \`aiw recommend\`, then read \`.aiw/recommendations.yml\` and \`.aiw/profile.yml\`. Explain why each suggested skill, rule, agent, hook, or template fits and identify external permissions. Ask which capabilities to install, and ask separately before granting an external permission such as \`network:external\`.
+4. Record the user's choices with \`aiw recommend --select=id,id\`; use \`aiw recommend --select=\` when all recommendations are declined. If at least one capability is selected, run \`aiw sync\`; when the user separately approved external network access, pass \`--allow=network:external\`. Sync installs only selected resources and fills supported project rules with detected stack and quality-tool details. Do not add unselected resources or overwrite existing files.
+5. Review the installed resource list and the generated project-specific files with the user. Ask before changing project policy or tailoring any other skill/rule.
+6. Introduce the selected workflow gates: brainstorming → specification → architecture decision when needed → implementation plan → implementation with tests → verification → traceability → review. Use only gates supported by the resources the user chose.
+
+If the user declines all recommendations, leave the project with only the bootstrap skill and scan state. Do not treat scanning or recommendation as consent to install.
+
+## For each feature request after setup
+
+- Start with the brainstorming skill when scope, users, constraints, or assumptions are unclear.
+- Create and complete a specification with stable requirement IDs and Given/When/Then acceptance criteria; pass \`aiw gate specification\` before planning.
+- Record consequential architecture choices as ADRs. Create an implementation plan that links tasks to requirements, tests, risks, and validation commands; pass \`aiw gate plan\` before coding.
+- Follow the TDD policy and project quality rules. Use specialist agents for requirements, architecture, implementation, tests, security, documentation, and review when useful.
+- Run the declared checks, then \`aiw verify\`, \`aiw trace\`, and the review gate. Do not claim completion without evidence.
+
+## Language policy
+
+All generated AI Workflow artifacts must be written in English unless the user explicitly requests another language.
+`;
 }
 export function renderAiInitPath(target) {
     const paths = {

package/dist/bundled-resources.d.ts

@@ -0,0 +1,9 @@
+import { type ResourceType } from "./package-contract.js";
+import type { Target } from "./types.js";
+export type BootstrapResource = {
+    type: ResourceType;
+    id: string;
+    path: string;
+    content: string;
+};
+export declare function loadBundledResources(target: Target): BootstrapResource[];

package/dist/bundled-resources.js

@@ -0,0 +1,29 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { renderResourcePath } from "./adapter.js";
+import { RESOURCE_TYPES, validatePackageContract } from "./package-contract.js";
+const resourceRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../resources");
+export function loadBundledResources(target) {
+    const manifestPath = join(resourceRoot, "package.yaml");
+    const manifest = readFileSync(manifestPath, "utf8");
+    const contract = validatePackageContract(manifest, (path) => {
+        const candidate = resolve(resourceRoot, path);
+        const rel = relative(resourceRoot, candidate);
+        return rel !== ".." && !rel.startsWith(`..${sep}`) && existsSync(candidate);
+    });
+    if (contract.targets && !contract.targets.includes(target))
+        throw new Error(`The bundled workflow resources do not support target: ${target}`);
+    return RESOURCE_TYPES.flatMap((type) => contract.resources[type].map(({ id, path }) => {
+        const source = resolve(resourceRoot, path);
+        const rel = relative(resourceRoot, source);
+        if (rel === ".." || rel.startsWith(`..${sep}`))
+            throw new Error(`Bundled resource path escapes the package: ${path}`);
+        return {
+            type,
+            id,
+            path: renderResourcePath(target, type, id),
+            content: readFileSync(source, "utf8"),
+        };
+    }));
+}

package/dist/constants.js

@@ -6,5 +6,6 @@ export const BASE_DIRECTORIES = [
     "generated/docs",
     "generated/artifacts",
     "context",
+    "resources",
 ];
 export const INSTALL_USAGE = "aiw install [--target target] | scan | status | target <target> | validate";

package/dist/files.d.ts

@@ -1,2 +1,12 @@
 import type { FileSystem } from "./types.js";
 export declare const nodeFileSystem: FileSystem;
+export type ProjectFileWrite = {
+    path: string;
+    content: string;
+};
+/** Apply project containment and symlink checks to every workflow filesystem mutation. */
+export declare function withSafeProjectWrites(fs: FileSystem, projectRoot: string): FileSystem;
+/** Reject writes that escape the project or cross any existing/dangling symbolic link. */
+export declare function assertSafeProjectPath(fs: FileSystem, projectRoot: string, destination: string): void;
+/** Create a set of new project files as one rollback-capable transaction. */
+export declare function writeProjectFilesAtomically(fs: FileSystem, projectRoot: string, writes: readonly ProjectFileWrite[], requiredDirectories?: readonly string[]): void;