@aperant/framework 0.6.2 → 0.6.3

package/docs/workflows.md

@@ -1,194 +0,0 @@
-# Declarative YAML Workflows (C17)
-
-Aperant's router encodes skill chains imperatively in TypeScript. That works,
-but it means every new composition requires editing `route.mjs` and the skill
-markdown. C17 adds a **complementary**, declarative mode: a YAML DAG where
-each node names a skill or agent invocation and edges encode dependencies.
-
-The declarative runner (`apt-tools wfrun`) can either:
-
-1. Execute the graph **inline** when every node is a `kind: tool` invocation
-   (deterministic `apt-tools …` subprocess calls), or
-2. Emit a **JSON run-plan** describing the waves a calling LLM/skill must
-   execute sequentially — the "invoke-point" mode for `kind: agent` and
-   `kind: skill` nodes.
-
-This page is the schema + invocation reference.
-
-## Overview
-
-YAML workflows complement the router — they don't replace it. The router
-handles autonomy, routing decisions, and session state. YAML workflows are
-for reusable, shareable chain-of-steps recipes that don't need the router's
-decision surface. Think: "plan → execute → verify" as a pattern you'd like
-to run on demand, or a diamond DAG of diagnostic tool invocations.
-
-## Schema Reference
-
-```yaml
-apiVersion: aperant.dev/v1     # reserved for forward compat; only this value accepted today
-kind: Workflow
-
-metadata:
-  id: <slug>                   # [a-z0-9][a-z0-9-]* — used as workflow_id in run artifacts
-  description: |               # optional free-text
-    …
-
-inputs:                        # optional; every name referenced as ${inputs.<name>} must appear here
-  - name: <identifier>         # [a-z0-9][a-z0-9_-]* — underscores allowed
-    required: true             # default true
-    default: <string>          # optional literal default
-    description: <string>      # optional
-
-nodes:                         # at least one
-  - id: <slug>                 # unique within nodes[]
-    kind: skill | agent | tool
-    depends_on: [<node-id>, …] # optional; every entry must match another node.id
-    outputs: [<identifier>, …] # optional; keys this node promises to produce
-
-    # Body fields are kind-discriminated:
-
-    # kind: skill
-    skill: <skill-name>
-    prompt: <string>           # optional, supports ${…} interpolation
-
-    # kind: agent
-    agent: <agent-name>
-    prompt: <string>           # optional, supports ${…} interpolation
-
-    # kind: tool
-    run:
-      command: <apt-tools subcommand>   # must be in the tool-command allowlist
-      args: [<string>, …]               # every entry supports ${…} interpolation
-```
-
-### Interpolation grammar
-
-Two reference forms are supported — nothing else:
-
-- `${inputs.<name>}` — resolves to the value supplied via `--input <name>=<value>`
-  (or the input's declared `default`).
-- `${<node-id>.outputs.<key>}` — resolves to an output captured from a
-  previous node. In **plan mode** (and inside `wfrun plan`), these references
-  are left literal because agent nodes haven't run yet; the caller is
-  responsible for substituting them before spawning downstream nodes.
-
-`\${…}` is left literal (the backslash is stripped). A bare `$` not followed
-by `{` is untouched.
-
-## Example Walkthrough — `diamond.yaml`
-
-```yaml
-apiVersion: aperant.dev/v1
-kind: Workflow
-metadata:
-  id: diamond
-
-nodes:
-  - id: a
-    kind: tool
-    run:
-      command: state
-      args: ["."]
-
-  - id: b
-    kind: tool
-    depends_on: [a]
-    run: { command: state, args: ["."] }
-
-  - id: c
-    kind: tool
-    depends_on: [a]
-    run: { command: state, args: ["."] }
-
-  - id: d
-    kind: tool
-    depends_on: [b, c]
-    run: { command: state, args: ["."] }
-```
-
-Line-by-line:
-
-- **`apiVersion` / `kind`** — structural discriminators. Missing either is a
-  hard error.
-- **`metadata.id: diamond`** — identifies this workflow; used in the
-  `workflow_id` field of all run artifacts and the first component of the
-  `run_id` (`wf-YYYYMMDD-HHmmss-<4-hex>`).
-- **`nodes[0]`** — the root. No `depends_on`, so it's placed in wave 1.
-- **`nodes[1]` + `nodes[2]`** — both depend on `a` only, so they end up in
-  wave 2 side-by-side. Nodes within a wave are executed **in parallel**
-  during `wfrun run` (each spawned as a separate `node apt-tools state .`
-  subprocess).
-- **`nodes[3]`** — the join. Waits for both b and c.
-
-Running `apt-tools wfrun plan packages/framework/workflows/examples/diamond.yaml`
-produces `waves: [[a], [b, c], [d]]` — exactly the shape above.
-
-## Invocation Recipes
-
-```bash
-# Parse + schema + DAG check, no execution:
-apt-tools wfrun validate packages/framework/workflows/examples/diamond.yaml
-
-# Resolve inputs + interpolate bodies + emit run-plan JSON:
-apt-tools wfrun plan packages/framework/workflows/examples/plan-execute-verify.yaml \
-  --input task_description="add a settings toggle"
-
-# Execute an inline workflow (all kind:tool) end-to-end; writes
-# .aperant/wfrun/{run-id}/{manifest,plan,result}.json:
-apt-tools wfrun run packages/framework/workflows/examples/diamond.yaml \
-  --project-dir .
-```
-
-All output is JSON. Non-zero exit status + a `{ "status": "error", … }`
-envelope signals a validation or runtime failure.
-
-## Run Artifacts
-
-A `wfrun run` writes three files under `.aperant/wfrun/{run-id}/`:
-
-| File             | Contents                                                                                      |
-| ---------------- | --------------------------------------------------------------------------------------------- |
-| `manifest.json`  | Run metadata: workflow_id, inputs, started_at, node/wave counts.                              |
-| `plan.json`      | The same envelope returned by `wfrun plan`: waves, inline_executable, reason, inputs.          |
-| `result.json`    | Only present for inline runs. Per-node `{node_id, command, args, exit_code, stdout_tail, stderr_tail, started_at, completed_at}`. |
-
-All writes go through `atomicWriteJson` (R3) and sit under the R11 outputs
-allowlist entry `.aperant/wfrun/**`.
-
-## v1 Limits
-
-| Feature                             | v1 Status          |
-| ----------------------------------- | ------------------ |
-| Loops / `forEach` over inputs       | NO                 |
-| `when:` conditionals                | NO                 |
-| Expression language (`${x+y}` etc.) | NO — literal paths only |
-| Output capture from `agent` nodes   | NO (follow-up task — caller reports outputs via a forthcoming `wfrun advance` command) |
-| Inline execution of `agent`/`skill` | NO — emitted as invoke points only |
-| Cross-machine / distributed runs    | NO                 |
-| Workflow versioning migrations      | NO (stay on `aperant.dev/v1`) |
-
-Hitting one of these is usually a sign you want the imperative router, not
-the declarative runner — or that the gap should graduate to a follow-up
-spec.
-
-## Naming Collision — `wfrun` vs `workflow`
-
-The existing `apt-tools workflow` subcommand is the C29 **phase-enforcement**
-runner: it tracks whether a lifecycle phase (plan / execute / verify / …)
-has been advanced correctly and gates downstream work on the right ordering.
-It has nothing to do with YAML composition.
-
-The declarative YAML runner therefore lives under a **new** top-level verb,
-`apt-tools wfrun`, rather than overloading `workflow`. This keeps both
-concepts individually discoverable (`wfrun = workflow-run`) and avoids
-breaking any script calling `workflow create / advance / status / destroy`
-today. The phase-enforcement command's tests remain green untouched.
-
-## Related
-
-- Spec-gaps entry: [C17](../../../docs/frameworks/spec-gaps.md#c17)
-- Phase-enforcement command (distinct): [`apt-tools workflow`](./workflow.md)
-  (if / when that page exists; source lives at
-  `packages/framework/src/cli/commands/workflow.mjs`).
-- DAG cycle-detection helper reused from: `src/cli/graph/depends-on.mjs`.

package/docs/worktree-ecosystems.md

@@ -1,345 +0,0 @@
-# Multi-language worktree ecosystems — cheatsheet
-
-This document explains the per-ecosystem quirks, anti-patterns, and flag
-matrices that drove the C54 worktree-bootstrap implementation. Read it when
-you're wiring a new ecosystem into the installer, debugging a hung install,
-or deciding whether to write a `task_isolation.bootstrap_cmd` override.
-
-**Enabled when?** `task_isolation.bootstrap_worktree: true` in
-`.aperant/config.json`. Off by default — existing projects get zero
-behavior change until they opt in via `/apt:setup` or by editing the
-config directly.
-
-**Per-task opt-out:** pass `--no-bootstrap` on `apt-tools worktree create`
-or match a `task_isolation.skip_bootstrap_for: ["<glob>"]` entry.
-
-**Custom command:** `task_isolation.bootstrap_cmd: ["./custom-install.sh"]`
-replaces the auto-detected invocation entirely — still runs under the
-same env-isolation + detached-child envelope.
-
----
-
-## Per-ecosystem notes
-
-### pnpm
-
-**Canonical install:** `pnpm install --frozen-lockfile`
-
-**Why `--frozen-lockfile`?** Pins resolution to the exact versions in
-`pnpm-lock.yaml`. Without it, pnpm may update the lockfile silently if the
-`package.json` has drifted. `--frozen-lockfile` exits non-zero on drift,
-which is exactly the signal we want in a deterministic install path.
-
-**CAS safety across worktrees.** pnpm keeps a content-addressable store
-under `~/.local/share/pnpm/store/v3/` (or platform equivalent) that is
-shared across projects. Worktrees on the same host share the CAS safely
-because it's hashed by content. **Do not symlink `node_modules/` between
-worktrees** — pnpm's internal `node_modules/.pnpm/` directory contains
-per-project virtualized dependency graphs. Symlinking short-circuits the
-CAS and leaves the receiving worktree with a corrupted install.
-
-**`--prefer-frozen-lockfile`?** A softer variant that prefers but doesn't
-require an exact match. We don't use it: the bootstrap's contract is "the
-worktree is reproducible from the lockfile or the install fails loud."
-
----
-
-### npm
-
-**Canonical install:** `npm ci`
-
-**`npm ci` vs `npm install`.** `npm ci` deletes `node_modules/` and
-reinstalls from `package-lock.json`. `npm install` resolves from
-`package.json` and updates the lockfile if needed. For a bootstrap we
-want deterministic — `npm ci` is mandatory. It also runs ~2x faster on
-cold caches because it skips the resolution pass.
-
-**Requires `package-lock.json`.** On a fresh repo with only
-`package.json`, `npm ci` refuses to run. That's surfaced as
-`install_status: "failed"` with the npm error text in the log.
-
----
-
-### yarn classic
-
-**Canonical install:** `yarn install --frozen-lockfile`
-
-Yarn classic (1.x) is a legacy ecosystem that many repos still run. The
-`--frozen-lockfile` flag is the equivalent of `npm ci` — refuses to
-update `yarn.lock`.
-
----
-
-### yarn-berry
-
-**Canonical install:** `yarn install --immutable`
-
-**PnP mode + no `node_modules/`.** Yarn Berry's default mode is Plug'n'Play:
-no `node_modules/` tree, dependencies resolved via `.pnp.cjs` at runtime.
-Detected via `.yarnrc.yml` with `nodeLinker: pnp` (or `pnpm`). Under PnP
-the post-install tree is dramatically smaller (no copy per project) but
-some tools (editors, eslint resolvers) need PnP-aware plugins.
-
-**`.yarn/cache/` sharing.** Berry caches packed tarballs under
-`.yarn/cache/` inside each project. Worktrees on the same host can safely
-share the cache via symlink IF they're on the same Berry version — but we
-do NOT do this automatically because a version-mismatch silently corrupts
-the cache. If you need the share, do it by hand, make sure every
-worktree runs the same Berry version, and re-check after a `corepack`
-upgrade.
-
----
-
-### bun
-
-**Canonical install:** `bun install --frozen-lockfile`
-
-**Lockfile format migration.** Pre-Jan 2025, bun shipped `bun.lockb` — a
-binary format bun could read/write natively but git diff tools couldn't
-show line-by-line changes. Post-Jan 2025, bun defaults to `bun.lock` — a
-text format that diffs cleanly. The detector handles both; if only
-`bun.lockb` is present it surfaces a non-fatal warning in the ecosystem
-entry recommending migration.
-
-**Migrate by running:** `bun install --save-text-lockfile` (or in modern
-bun, a bare `bun install` on a repo with `bun.lockb` produces `bun.lock`
-automatically). Commit both files until your team is on a bun version
-that reads `bun.lock`, then delete `bun.lockb`.
-
----
-
-### uv vs poetry
-
-**Canonical uv install:** `uv sync --frozen`
-**Canonical poetry install:** `poetry install --no-root --sync`
-
-**pyproject.toml coexistence hazards.** A single `pyproject.toml` can
-declare BOTH `[tool.uv]` and `[tool.poetry]` blocks and each tool will
-happily act on its own without warning the other. This is a foot-gun: the
-two tools disagree on how to resolve `dependencies` in the PEP-621
-`[project]` block vs the Poetry-style `[tool.poetry.dependencies]`. The
-detector picks `uv` when a `uv.lock` is present, else `poetry` when
-`poetry.lock` is present, else whichever `[tool.*]` block exists. If
-neither lockfile exists and both tool blocks are present, pick one in
-the PROJECT.md or the install will be non-deterministic.
-
-**uv caches aggressively.** `~/.cache/uv/` shares wheels across projects,
-similar to pnpm's CAS. Worktrees share safely.
-
----
-
-### pip-venv
-
-**Canonical install:** `python -m venv .venv && .venv/bin/pip install -r requirements.txt`
-
-**Two-step wrapper.** Implemented as `shell_wrapper` in ecosystem-commands.mjs
-because there's no single-invocation pip command that creates a venv AND
-installs into it.
-
-**Never copy `venv/` between worktrees.** `.venv/bin/python` and
-`.venv/bin/pip` are shebang-linked to absolute paths:
-`#!/home/you/project-A/.venv/bin/python`. Copy the directory into
-project-B and every executable stops working — or worse, silently runs
-project-A's interpreter against project-B's code. Create a fresh venv
-per worktree. Hard-link the wheel cache if you want the speed.
-
----
-
-### cargo
-
-**Canonical install:** `cargo fetch --locked`
-
-**NEVER `cargo build`.** `build.rs` is arbitrary Rust code that runs at
-build time — it can do anything a Rust program can do, including reading
-env vars, opening network connections, and writing to the filesystem.
-Moving `build` to install time would broaden the RCE attack surface
-without commensurate gain. We defer `build` to the verify stage where it
-runs under the same env envelope but with a cleaner expectation.
-
-**`target/` size impact.** Rust's incremental build directory explodes
-over time: per-worktree `target/` directories can cost 10+ GB each. The
-CI answer is sccache; the local-dev answer is `cargo sweep --time 30` or
-occasionally blasting `target/` between worktree switches. **Never share
-`target/` between worktrees on different branches.** Rust's incremental
-compilation cache invariant assumes all edges of a single source graph —
-a `target/` built from branch A reused on branch B can silently produce
-miscompiled code with no warning.
-
----
-
-### go
-
-**Canonical install:** `go mod download`
-
-**`go.sum` is a checksum file**, not the resolution source of truth.
-`go.mod` declares dependencies; `go.sum` locks content hashes. `go mod
-download` uses both to prefetch the module graph; it does not require
-`go.sum` to exist (it will create one on first run).
-
-**Module proxy.** `GOPROXY=proxy.golang.org,direct` by default. The env
-allowlist drops this to just the proxy — you can't shell out to arbitrary
-git hosts during install.
-
----
-
-### bundler (Ruby)
-
-**Canonical install:** `bundle install --jobs 4 --retry 3`
-
-**Gemfile.lock.** Lockfile presence is optional; bundler happily resolves
-from `Gemfile` alone. We don't pass `--frozen` by default because many
-Ruby monorepos rely on the install updating the lockfile — gate via
-config if your project requires frozen behavior.
-
----
-
-### composer (PHP)
-
-**Canonical install:** `composer install --no-interaction --prefer-dist`
-
-**`--no-interaction`** is mandatory; `--prefer-dist` pulls pre-built
-archives instead of cloning via git, which avoids needing git access
-inside the install env.
-
----
-
-### gradle
-
-**Canonical install:** `./gradlew --no-daemon dependencies`
-
-**`--no-daemon` is MANDATORY.** Gradle's daemon keeps a JVM hot across
-invocations. Without `--no-daemon`, parallel worktrees hitting the same
-daemon deadlock on the lock file in `~/.gradle/daemon/`. The crash mode
-is silent: the second install hangs, eventually timing out with a cryptic
-"Daemon is stopped" error.
-
-**Users can keep their daemon for interactive work.** The `--no-daemon`
-flag only affects our invocation; user shells don't inherit it. We do
-NOT kill orphaned daemons the user left running — that's beyond scope.
-
-**GRADLE_OPTS env.** The spawn helper sets `GRADLE_OPTS=
--Dorg.gradle.daemon=false` belt-and-suspenders so even a `build.gradle`
-that tries to re-enable the daemon via `gradle.properties` can't.
-
----
-
-### CocoaPods (iOS)
-
-**NOT AUTOMATED.** The cheatsheet covers this ecosystem because it's a
-common question, but the installer does NOT orchestrate `pod install`.
-Reasons:
-
-1. **`.xcworkspace` mutation hazard.** `pod install` mutates the
-   `.xcworkspace/` Xcode project descriptor in place. Multiple parallel
-   pod runs racing on the same workspace corrupt the project.
-2. **Platform-specific toolchain.** CocoaPods needs Ruby + the cocoapods
-   gem + `pod setup` having run once. We don't want to drag those deps
-   into the install envelope.
-
-If you need iOS bootstrap, set `task_isolation.bootstrap_cmd:
-["./ios-bootstrap.sh"]` and own the sequencing in your own script.
-
----
-
-## Cross-cutting matrices
-
-### Frozen-install flag matrix
-
-| Ecosystem | Frozen-install flag | Behavior on drift |
-|---|---|---|
-| pnpm | `--frozen-lockfile` | exits non-zero |
-| npm | `ci` (implicit) | exits non-zero |
-| yarn classic | `--frozen-lockfile` | exits non-zero |
-| yarn-berry | `--immutable` | exits non-zero |
-| bun | `--frozen-lockfile` | exits non-zero |
-| uv | `--frozen` | exits non-zero |
-| poetry | `--sync` | updates to match lockfile (no "fail on drift") |
-| pip-venv | n/a | pip has no frozen flag; pin via `requirements.txt` |
-| cargo | `--locked` | exits non-zero on Cargo.lock mismatch |
-| go | n/a | go.sum acts as checksum only |
-| bundler | `--frozen` (not default) | exits non-zero when passed |
-| composer | `--no-install` + `--install` split | lockfile consulted when present |
-| gradle | `--no-daemon` (not frozen-related) | uses dependency constraints |
-
-### Offline-prefer flag matrix
-
-| Ecosystem | Offline flag | Required for | 
-|---|---|---|
-| pnpm | `--offline` | fully offline install (cache-only) |
-| npm | `--prefer-offline` | best-effort offline |
-| yarn | `--offline` | fully offline install |
-| bun | `--offline` | fully offline install |
-| uv | `--offline` | fully offline install |
-| cargo | `--offline` | fully offline (cache-only) |
-| go | `GOFLAGS=-mod=mod` + `GOPROXY=off` | offline, module cache only |
-
-We don't pass offline flags by default — the bootstrap is expected to
-have network. Set these via `bootstrap_cmd` if you're in an air-gapped
-env.
-
-### Lifecycle-script exec matrix (which ecosystems run arbitrary code)
-
-| Ecosystem | Runs arbitrary code during install? | Mitigated by |
-|---|---|---|
-| pnpm | YES (postinstall, preinstall, scripts) | env allowlist + HOME stub |
-| npm | YES | env allowlist + HOME stub |
-| yarn | YES | env allowlist + HOME stub |
-| bun | YES | env allowlist + HOME stub |
-| uv | NO (wheels are static) | n/a |
-| poetry | rarely (setup.py build hooks) | env allowlist |
-| cargo | n/a (`fetch` doesn't build) | we skip `cargo build` |
-| go | NO (`mod download` is metadata+archive) | n/a |
-| bundler | YES (extconf.rb native builds) | env allowlist |
-| composer | rarely (scripts block in composer.json) | --no-scripts is NOT default; allow scripts so `composer install` works on real repos |
-| gradle | YES (build.gradle is Groovy/Kotlin) | --no-daemon + env allowlist |
-
-The env allowlist + stubbed HOME means even "runs arbitrary code"
-ecosystems can't exfiltrate credentials or talk to non-allowlisted
-registries.
-
----
-
-## Anti-patterns
-
-### Never symlink `node_modules/` between worktrees
-
-pnpm's CAS bypass → corrupted install. The `.pnpm/` hoisting tree
-under `node_modules/.pnpm/` contains per-worktree virtualized dependency
-graphs. Sharing it across worktrees leaves both in a half-reset state
-after the next `pnpm install`.
-
-If you really need to save space across 12 parallel worktrees, rely on
-pnpm's content-addressable store (already shared globally under
-`~/.local/share/pnpm/store/`) — that's the intended sharing surface.
-
-### Never copy venv between worktrees
-
-Python venvs hardcode absolute paths in their bin shebangs:
-`#!/home/you/project-A/.venv/bin/python`. Copy the directory to
-project-B and `.venv/bin/pip` points at project-A's interpreter — or
-worse, at a path that no longer exists. The symptoms are subtle
-("why does my import fail? I'm in the right venv"). Create a fresh venv
-per worktree; hard-link the wheel cache if speed matters.
-
-### Never share target between worktrees on different branches
-
-Rust's incremental compilation cache invariant assumes every edge of a
-single source graph. When you point two worktrees on different branches
-at the same `target/`, the incremental cache's assumption is violated
-and the compiler can silently produce miscompiled code — no warning, no
-build error, just incorrect runtime behavior.
-
-If you want to share build output, use `sccache` (distributed
-compilation cache that's branch-aware) or use the cargo workspace
-feature where all crates share a single `target/` within one repo —
-that's supported, and the invariant holds.
-
----
-
-## Framework references
-
-- Implementation: `packages/framework/src/cli/install/ecosystem-commands.mjs`
-- Security scanner: `packages/framework/src/cli/install/manifest-scanner.mjs`
-- Spawn envelope: `packages/framework/src/cli/install/detached-spawn.mjs`
-- Config: `.aperant/config.json → task_isolation.*`
-- Skill guidance: `packages/framework/skills/apt-execute/SKILL.md` (step 2a)