@aperant/framework 0.6.2 → 0.6.3

package/CHANGELOG.md

@@ -0,0 +1,595 @@
+# @aperant/framework — Changelog
+
+All notable changes to `@aperant/framework` are documented here. See
+[`VERSIONING.md`](VERSIONING.md) for the per-tier contract.
+
+## 0.6.3 — 2026-05-12 — README license + tarball slim
+
+Follow-up patch on top of the 0.6.2 first-public release. Three fixes:
+
+- **License consistency.** README badge + footer corrected from MIT to
+  AGPL-3.0-only to match `package.json` and the actual `LICENSE` file.
+  No license change — only the README claim was wrong.
+- **README docs references removed.** The framework's `docs/` directory
+  is not currently shared; links pointing into it (workflows.md,
+  plugin-distribution.md, api.md, the aperant-framework-spec deep link)
+  have been dropped from the README.
+- **Tarball slimmed.** Added negation globs to `files` to exclude
+  `__tests__/`, `*.test.*`, `*.spec.*`, and the test sourcemap variants
+  from the published tarball. Dropped the framework's own `docs/` and
+  `CONTRIBUTING.md` from `files`; added `CHANGELOG.md`. Result: 2.5 MB
+  → 1.8 MB tarball, 11.8 MB → 7.9 MB unpacked, 3498 → 2040 files (~42%
+  reduction).
+
+## 0.6.2 — 2026-05-12 — First public npm release + router envelope cap bump
+
+First publish to the public npm registry (`registry.npmjs.org`). Prior
+versions (0.1.0 – 0.6.1) were only published to a local Verdaccio proxy
+during dogfood development; they are not retrievable from public npm.
+Public history starts here.
+
+Also lands PR #92: `ENVELOPE_MAX_BYTES` bumped 9216 → 9472 in
+`src/cli/route/envelope.mjs`. The compact JSON routing payload crossed
+9234 bytes after recent skill additions; the old 9216 cap rejected
+otherwise-valid inputs with `envelope_overflow`. Same 256-byte step as
+prior bumps (C47/C48/C49/C56); ~240 bytes of fresh headroom matches the
+"≥1 more small skill" target documented in the cap-bump history.
+
+## 0.6.1 — 2026-05-01 — Agent-aware non-TTY install + schema-drift detection
+
+Closes the dogfood incident where `apt-tools init . --claude --codex` from
+inside a Claude Code session silently defaulted to `visibility:'solo'`,
+which made `injectProjectGitignore` write a blanket `.aperant/` ignore line
+that clobbered the team-mode allow-list. Class A settings (visibility,
+runtimes, scanNow) now fail loudly in non-TTY mode unless the user opts in.
+
+Also adds first-class detection of schema drift between the user's
+`.aperant/config.json` and the shipped `templates/config.json` — new keys
+no longer accumulate as `undefined` in the user's config without a path to
+review them.
+
+### Highlights
+
+- New flags on `apt-tools init`: `--team` / `--solo` (mutually exclusive
+  visibility), `--autonomy <0..3>` (default autonomy level),
+  `--accept-new-defaults` (apply Class A template defaults during a
+  schema migration), `--yes` (CI escape hatch — accept all Class A
+  defaults silently, recorded as `source:"--yes"` in `applied_defaults`).
+- New envelope variant: `{"status":"requires_input", ...}` returned at
+  exit code 2 when a Class A setting is missing in non-TTY. Includes
+  `requires_explicit`, `applied_defaults`, `agent_runtime`, and a
+  copy-pasteable `rerun_with` command. Mirrors the
+  `config/upgrade-layout.mjs` `exitWith(envelope, 2)` convention.
+- New envelope variant: `{"status":"up_to_date", ...}` returned when an
+  existing config matches the template schema (no drift). Skips the
+  runtime install — `/apt:update` is the right surface for refreshing
+  skills on a no-drift run.
+- `init` envelope on success grows four fields: `applied_defaults`,
+  `explicit_inputs`, `agent_runtime`, `migration` (the last summarizes
+  schema drift handled). `configMigrated:bool` joins `configCreated`.
+- TTY upgrade gate: when `init` runs interactively against an existing
+  config with drift, clack prompts ONLY for the new Class A keys
+  (existing-key widgets are NOT re-rendered). No drift → "Already up to
+  date" note + outro, install skipped. Class B / auto_added only →
+  summary note + silent apply.
+
+### Migration notes
+
+- **Breaking for unattended `apt-tools init` callers** (CI, scripted
+  installs). A non-TTY `init` with no flags and no existing config now
+  exits 2 with a `requires_input` envelope instead of silently defaulting
+  to `visibility:'solo'`. To restore the old behavior:
+  - **Pass the explicit Class A flags**: `apt-tools init . --team --claude --codex`
+  - **Or pass `--yes`** to accept all Class A defaults: `apt-tools init . --yes`
+- **Existing configs at `version < 4`** will trip the schema-migration
+  gate on the next `init` call. Pass `--accept-new-defaults` (Class B
+  fills) or `--yes` (Class A + Class B fills) to clear it
+  non-interactively, or run interactively to be prompted.
+- The dogfood incident the new gate prevents: `apt-tools init . --claude --codex`
+  from a Claude Code session, which silently defaulted to
+  `visibility:'solo'` and wrote a blanket `.aperant/` ignore line that
+  clobbered the team-mode `.aperant/.gitignore` allow-list. After this
+  release that command exits 2 until visibility is named explicitly.
+
+### Internals
+
+- New: `packages/framework/src/cli/install/setting-class.mjs` — single
+  source of truth for Class A vs Class B classification + flag mapping +
+  per-key `classify()` helpers.
+- New: `packages/framework/src/cli/config/schema-migrate.mjs` — pure
+  function that walks the template's leaf paths, buckets each into
+  `applied_defaults` (Class B) / `requires_explicit` (Class A or invalid)
+  / `auto_added` (template-internal additions). Bumps `migrated.version`
+  only when `requires_explicit` is empty.
+- New: `packages/framework/src/cli/util/agent-runtime.mjs` —
+  `detectAgentRuntime()` env-var sniff returning
+  `'claude-code' | 'cursor' | 'aider' | 'unknown'` with deterministic
+  precedence. Messaging-only (never affects which codepath runs).
+- Modified: `packages/framework/src/cli/commands/init.mjs` —
+  `parseInstallFlags` extended with the new flag surface;
+  `nonInteractiveAnswers` rewritten as a fork between fresh-install and
+  upgrade paths; `interactiveInterview` gains an upgrade gate at the top
+  while staying byte-identical for fresh installs; `cmdInit` handles the
+  three new sentinels (`requiresInput`, `upgrade_noop`, plus the existing
+  `cancelled`).
+- Tests: `setting-class.test.ts` (19), `agent-runtime.test.ts` (6),
+  `schema-migrate.test.ts` (9), `init-non-tty-class-a.test.ts` (6,
+  including 2 env-parity cases for spec R4),
+  `init-upgrade-drift.test.ts` (4 — the R3 matrix). Existing
+  `init-flag-parser.test.ts` extended from 12 to 22 cases.
+
+## 0.6.0 — 2026-04-27 — CLI layering refactor (envelope/exitCode shape)
+
+Internal refactor of `apt-tools` into three explicit layers — Layer 1 cmd
+bodies, Layer 2 wrappers, Layer 3 dispatcher — closing the
+"`process.exit()` scattered across cmd files" footgun that prevented
+in-process unit testing of cmd branches.
+
+### Highlights
+
+- Every Layer 1 cmd in `src/cli/commands/` now returns a `CommandResult`
+  tuple (`{ envelope, exitCode }` for JSON output OR `{ rawText, exitCode }`
+  for non-JSON output) instead of calling `process.exit()` directly.
+  Verified: `grep -rn 'process\.exit' packages/framework/src/cli/commands/`
+  returns 0 lines (excluding comments).
+- New `src/__tests__/cmd-pure/<cmd>.test.ts` set covers every migrated cmd
+  in-process via the D-05 `runCmd` harness with `strictExit:true` default —
+  any forgotten `process.exit` trips the harness immediately.
+- Slim subprocess gate (`src/__tests__/cli-contract-<cmd>.test.ts`)
+  preserves byte-identical CLI contract end-to-end. Replaces the legacy
+  `smoke-*.test.ts` set (now empty).
+- 3 new e2e-pipeline lifecycle chain tests (`task-lifecycle`,
+  `pr-review-lifecycle`, `roadmap-lifecycle`) pin cross-cmd state-flow
+  contracts in-process.
+- D-03 closure: `process.argv[1]` is read in exactly one place
+  (`src/cli/util/bin-path.mjs:resolveAptToolsBin`). All other consumers
+  (worktree, worktree-install, task) go through that helper.
+
+### Wall-time impact
+
+_Final wall-time numbers measured in S26 — TBD; numbers will be filled in
+after the wall-time + final coverage gate runs._ The expected outcome is
+the framework test suite p99 ≤ 2 min on CI (vs ~10 min pre-refactor)
+because cmd branch coverage no longer requires per-test subprocess
+spawn-and-tear-down.
+
+### Migration notes
+
+- External callers parsing apt-tools stdout: zero break. The envelope
+  shape is byte-identical pre-refactor; the JSON contract is the public
+  surface. Internal layering changes are transparent to consumers.
+- Internal callers that previously imported `cmdX` and expected stdout
+  side-effects: they now get the `CommandResult` tuple back. The
+  `PipelineHarness` (the only known internal consumer outside the test
+  suite) was already on the new shape via `core/src/pipeline/harness.ts`'s
+  `runCli` shim and stays green throughout the refactor (verified by
+  `pipeline-harness-cli-spawn.test.ts` running on every commit).
+- The `process.argv[1]` deprecation in cmd bodies is a soft API change —
+  any external script that imported a cmd and depended on `process.argv[1]`
+  reflecting the apt-tools entrypoint must now pass `projectDir` to
+  `resolveAptToolsBin` directly.
+
+## 0.5.0 — 2026-04-24 — C56 artifact lifecycle closeout (mechanistic + systemic; absorbs C59)
+
+Minor release closing the post-ship artifact leaks surfaced after PR #62
+merged on 2026-04-23. Combines what was originally planned as two phases
+(C56 mechanistic + C59 systemic) into one PR because they share ~5
+source files and C59 depends on C56's classification contract. Six
+subsystem changes across four altitudes — CLI primitives, skill
+contracts, lifecycle state machine, and documentation surface.
+
+### Root cause eliminated
+
+The framework split **producers** (apt:plan / execute / review / ship /
+pr-review — write artifacts while an agent is present) from **closers**
+(roadmap set-phase-status / task close / workflow destroy — should run
+post-merge when no agent is present). No skill walked the closer side
+because merge happens on GitHub hours/days after `/apt:ship` exits. C56
+introduces the missing closer (`/apt:close-task`), the state machine
+waypoint it transitions through (`shipped-pending-merge`), and the
+per-subtask drift audit that prevents leaks from accumulating during
+execution.
+
+### New: classification contract (B4)
+
+`packages/framework/src/cli/artifacts/classification.mjs` exports the
+single authoritative committable-vs-ephemeral table for every `.aperant/`
+subpath. See [`docs/artifact-lifecycle.md`](docs/artifact-lifecycle.md)
+for the full matrix. Self-staging helpers, the audit CLI, pr-review
+close-round cleanup, and the per-subtask drift check all consume this
+contract — one source of truth, extension = one file.
+
+### New: `apt-tools audit pending-artifacts` (B2)
+
+Enumerates uncommitted changes under `.aperant/` and splits them into
+`committable[]` / `ephemeral[]` / `unknown[]` via the classification
+contract. `--stage` auto-`git add`s committable paths. `unknown[]` is
+the planner-gap signal: a path touched by the subtask that the contract
+doesn't recognize yet.
+
+### New: `apt-tools task prune --older-than <duration>` (A4)
+
+Retention for `.aperant/tasks/{id}/` directories. Accepts durations like
+`30d`, `6w`, `1y`; refuses to prune tasks still in `active_tasks[*]`.
+Gitignored by design, so safe default is user-opt-in.
+
+### New: `apt-tools workflow destroy --archive` (A1 reframed)
+
+Investigation found `workflow destroy` already unlinks the file — the
+real bug was that **nobody called destroy post-merge**. `--archive`
+moves the workflow state JSON into `.aperant/workflows/archive/` with
+retention. B6 below wires the caller into `pr-review close-round`.
+
+### New: `/apt:close-task` skill (B1)
+
+Post-merge closer. Enumerates `shipped-pending-merge` tasks, polls
+`gh pr view` for PR merge state, and performs closeout on `MERGED`:
+phase flip, authorship override strip, worktree GC, task archive,
+`task.closed.merged` event. Offline / rate-limited invocations are
+tolerated (tasks skipped with reason, user re-runs). Supports
+`--all` / `--task <id>`. Spawns the ROADMAP.md narrator (moved from
+`/apt:ship`) when a closed task has a phase_id.
+
+### New: `shipped-pending-merge` lifecycle phase (B5)
+
+Additive enum between `reviewing` and `completed`. `/apt:ship` flips
+tasks to this waypoint on PR open; `/apt:close-task` flips to
+`completed` on confirmed merge. Tasks stay in `active_tasks[*]` until
+`/apt:close-task` runs — addresses the "shipped == landed" lie that
+produced the original drift.
+
+### Changed: pr-review authorship overrides (A3 migration)
+
+Authorship overrides now write to per-PR `.aperant/pr-reviews/pr-{N}/pr-state.json`
+instead of global `.aperant/config.json`. Precedence: `pr-state.json` →
+legacy `config.authorship_overrides['pr-{N}']` (deprecated, removed
+next release) → global `config.authorship_override`. `init-pr` promotes
+legacy entries on first call. Closes the stale-per-PR-config class of
+drift.
+
+### Changed: `apt-tools task close` auto-phase-flip (A2)
+
+Opt-in via `task_isolation.auto_close_phase: true`. When the task has
+`milestone_id` + `phase_id` linkage AND the linked PR is merged AND the
+phase is `in-progress`, close auto-flips the phase to `completed` with a
+`chore(aperant): roadmap sync` commit. Off by default for safety.
+
+### Changed: `apt-tools pr-review close-round` post-merge cleanup (B6)
+
+When `gh pr view` reports the PR is `MERGED` / `CLOSED`, close-round
+best-effort unlinks matching `.aperant/workflows/pr-<N>-*.json` files
+and strips `config.pr_review.authorship_overrides['pr-<N>']`. Uses
+`APT_GH_FIXTURE_JSON` for deterministic test runs. Offline degrades to
+`cleanup: {skipped: true}`, never fails close-round itself.
+
+### Changed: `/apt:ship` SKILL.md (B2/B5)
+
+- New §0.5 Pre-PR Committable Drift Check (runs audit pending-artifacts
+  --stage before PR creation; hard-stops on unknown[]).
+- §6 records `pr_url` on the task record via `task update --pr-url`
+  after `gh pr create` succeeds.
+- §8 replaces `task close --verdict approved` with `task update
+  --lifecycle-phase shipped-pending-merge`.
+- §9 narrator spawn removed; narration moves to `/apt:close-task`.
+
+### Changed: `/apt:execute` SKILL.md (B3)
+
+- New §3e-drift runs audit pending-artifacts --stage after every atomic
+  subtask commit. Committable drift is amended in; `unknown[]` routes to
+  `{task_dir}/execution-decisions.md` as a `classification-gap`.
+
+### Self-staging (B4, internal)
+
+State-mutating CLI commands (`roadmap add-milestone` /
+`add-phase` / `set-phase-status` / `delete-phase` / `delete-milestone`
+/ `render`, `pr-review init-pr` / `detect-authorship` /
+`record-comment` / `close-round`) now `git add -f` their committable
+file writes automatically. Caller's next commit picks them up — no more
+"I forgot to stage the roadmap sync" drift class.
+
+### Fixed
+
+- `apt-close-task/SKILL.md` frontmatter used `stage: close` + `intent:
+  close-task`, both outside the allowed enums. Every `apt-tools init`
+  was hard-failing. Changed to `stage: ship` + `intent: x-close-task`
+  (custom x- prefixed intent, schema-valid). Existing installs should
+  run `/apt:update` to pick up the fix.
+
+### Documentation
+
+- New: [`docs/artifact-lifecycle.md`](docs/artifact-lifecycle.md) —
+  authoritative reference for the classification contract, the
+  `shipped-pending-merge` lifecycle waypoint, self-staging contract,
+  authorship-override migration window, and retention model.
+- Updated: [`docs/docs-coherence.md`](docs/docs-coherence.md) links the
+  artifact-lifecycle reference from the "How the planner enforces this"
+  section.
+- Updated: `CLAUDE.md` "Multi-Agent Workflow" section gains the
+  shipped-pending-merge note + `/apt:close-task` entry in the skills
+  table + one-paragraph self-staging-contract subsection.
+
+---
+
+## 0.4.1 — 2026-04-23 — C53 warning silencer + C54 language-agnostic worktree bootstrap + C55 multi-language ecosystems cheatsheet
+
+Patch release closing out the fw-p6-product-context cleanup bundle on PR #61
+(post-fw-p6). All 0.4.0 behavior is preserved; 0.4.1 adds:
+
+- **C53 — YAML warning silencer on install.** Silences the "Keys with
+  collection values" warning from `yaml` during worktree-install YAML parsing
+  (manifest-scanner + toolchain-detect). Cosmetic-only; no behavior change.
+
+- **C54 — language-agnostic worktree bootstrap.** New opt-in
+  `task_isolation.bootstrap_worktree: true` config turns `apt-tools worktree
+  create --task <id>` into a language-agnostic bootstrap that detects every
+  ecosystem at the worktree path (pnpm/npm/yarn/yarn-berry/bun/uv/poetry/
+  pip-venv/cargo/go/bundler/composer/gradle) and spawns a detached install
+  child per ecosystem under a per-task env isolation envelope (PATH/LANG/
+  LC_ALL/TMPDIR only; HOME stubbed to `.aperant/tasks/<id>/install/home/`
+  with skeleton configs referencing only allowlisted registries). A URL
+  allowlist + lockfile scanner rejects `git+ssh://`, `git@`, `git+http(s)://`,
+  tarball URLs outside the registry allowlist, `file:` / `link:` / TOML
+  `path=` locals, and multi-lockfile coexistence BEFORE spawning any install.
+  New commands: `apt-tools worktree-install <dir> --task <id>` and
+  `apt-tools detect-ecosystem <dir>` (path-scoped). New events:
+  `install.started` / `install.ok` / `install.failed`. New statusline chip
+  `installing [<eco>] <Ns>` (or `install failed` in red on any task with a
+  failed install). Escape hatches: `--no-bootstrap` flag,
+  `task_isolation.skip_bootstrap_for: [globs]` config,
+  `task_isolation.bootstrap_cmd: [script]` config. Cargo uses
+  `cargo fetch --locked` only (never `cargo build`); Gradle always uses
+  `--no-daemon` to avoid cross-worktree daemon deadlocks.
+
+- **C55 — multi-language worktree ecosystems cheatsheet.** New doc at
+  `packages/framework/docs/worktree-ecosystems.md` covers all 12 v1
+  ecosystems with anti-patterns (never symlink `node_modules`, never copy
+  `venv/`, never share `target/` across branches), a frozen-install flag
+  matrix, an offline-prefer flag matrix, and a lifecycle-script-exec matrix.
+  `CLAUDE.md` gets a new "Multi-language worktree workflow" section pointing
+  at the cheatsheet.
+
+### Zero-regression guarantee
+
+With `task_isolation.bootstrap_worktree: false` (the default), `apt-tools
+worktree create` behavior is byte-identical to pre-0.4.1; `state.active_tasks
+[<id>]` keys are unchanged. C54 is strictly opt-in.
+
+## 0.4.0 — 2026-04-22 — fw-p6 production release + C51 discuss --auto
+
+Minor version bump closing out the fw-p6-product-context milestone (C47–C51)
+and the associated infrastructure fixes shipped via PR #60. All 0.3.x
+behaviour from the 0.3.x entry below remains present; 0.4.0 adds:
+
+- **`apt:discuss --auto` + `--review-auto`** (C51) — joint-reasoning batch
+  mode that resolves all gray areas in one LLM call instead of per-decision,
+  with optional single pause-at-end confirmation. DEEP tasks auto-run
+  advanced elicitation. Triggered by `--auto`, parent `--yolo`, or
+  `autonomy=3` config (precedence: flag > parent > config).
+- **`--runtime <id>`** override on `apt-tools route` — completes the D-02
+  unknown-host hint that previously pointed at a non-existent flag. Validates
+  against `supported_hosts`, overrides `detectHost().cli`.
+- **Route-eval OAuth token support** — the precision-smoke script
+  `run-route-eval.mjs` now speaks Anthropic's API directly (via `fetch`) with
+  auto-detected auth: OAuth tokens (`sk-ant-oat*`) use `Authorization: Bearer`
+  + `anthropic-beta` header; API keys (`sk-ant-api*`) use `x-api-key`. Long-
+  lived OAuth tokens from `claude setup-token` work end-to-end in CI.
+- **`--no-fail` flag on run-route-eval.mjs** — downgrades the D-01 kill
+  criterion from blocking exit to advisory warning. CI uses this pending C52
+  paraphrase-set re-baseline (labels are too opinionated about plan-first-vs-
+  full-auto; both opus and sonnet route "build a feature" → `apt:plan` not
+  `apt:run`).
+- **Review-loop quality fixes** — 21 findings from `/apt:pr-review` on PR #60
+  landed including path-traversal containment on `create-docs --output-dir`,
+  TOCTOU guard on `canonical_source`, r7-persona-alignment rule rename to
+  convention, and CLAUDE.md skills-table coverage for the three new skills.
+
+### Known limitations
+
+- **C52 follow-up** — `.github/workflows/route-eval-gate.yml` is advisory-only
+  until the paraphrase set is re-labeled with multi-reviewer agreement.
+  Re-enables as blocking when baselines stabilize.
+
+## 0.3.x — 2026-04-22 — Product-context ecosystem (C47–C50)
+
+Adds the four-skill product-context chain shipped in fw-p6. All new content is
+additive; no existing behaviour changed.
+
+### New skills
+
+- **`apt:bootstrap`** (C47) — generate or refresh `PROJECT.md` (the
+  product-context source of truth). Supports greenfield (7-section interview)
+  and brownfield (recon-and-infer) postures, controlled by the D-03 compound
+  heuristic. Derives `.aperant/product-context.json` sidecar on every write.
+  CLI surface: `apt-tools bootstrap <detect|scaffold|derive-sidecar|run>`.
+- **`apt:personas`** (C48) — discover 3-5 product personas grounded in code
+  signal (deterministic role-scan) and strategic intent from PROJECT.md. Writes
+  `.aperant/personas.json` with `team_id: 'framework-local'` sentinel; respects
+  D-10 canonical-source guard (refuses `--fresh` when the app wrote
+  `canonical_source: 'cloud'`). CLI surface: `apt-tools personas
+  <scan|rubric|read|write|record-run>`. Custom intent: `x-personas`.
+- **`apt:create-docs`** (C49) — generate persona-first product docs at
+  `docs/product/` from PROJECT.md + personas.json + the features registry.
+  Deterministic `StructurePlan` phase (CLI) + per-feature prose (apt-docs-author
+  agent). D-05 section-level diff-and-confirm on re-invocation. CLI surface:
+  `apt-tools create-docs <plan|render-nav|read|run>`. Custom intent:
+  `x-document`.
+
+### New gate
+
+- **`r-persona-alignment`** (C50) — G10 gate checking that a planned task's
+  `declared_persona_tier` aligns with its milestone's `focus_tier` list. Fires
+  at `stage=execute` and `stage=ship`. Skips when `personas.json` is absent
+  (D-06) or the task predates C50 (D-07). D-05 severity is `warn` by default;
+  escalates to `fail` when the milestone sets `focus_tier_enforcement:
+  "blocking"`. Structured D-08 rejection picker (Defer / Reassign / Promote /
+  Force) carried in `evidence.rejection_options[]` for UX consumption.
+
+### New consistency rule
+
+- **`r7-persona-alignment`** — plan ↔ personas.json internal consistency
+  rule (cross-artifact check that `declared_personas[]` IDs resolve to real
+  personas and declared tier strings are valid). Severity: `warn`. Stages:
+  plan, execute, ship.
+
+### New custom intents registered
+
+`x-personas` (`apt:personas`) and `x-document` (`apt:create-docs`) are the
+first `x-*` dogfood custom intents validating the router-0.3.0 extension path.
+Both are listed in `docs/intents.md`.
+
+### `--runtime` flag (all skills)
+
+`apt-tools route` now accepts `--runtime <host>` to override the detected
+runtime. `SUPPORTED_HOSTS` is the exhaustive allowlist; unknown values exit 1
+with a structured error envelope.
+
+---
+
+## 0.3.0 — 2026-04-22 — Breaking: router envelope redesign
+
+Router rewrite from a code-first classifier (hardcoded skill tables,
+regex keyword matching) to an LLM-first context provider (filesystem
+scan → thin envelope → host LLM picks a skill inline). Upgrade path:
+run `/apt:update` after pulling; the framework installer
+(`apt-tools init`) now refuses to install when any canonical SKILL.md
+fails schema validation, so the upgrade is safe even on multi-runtime
+trees.
+
+### Envelope fields removed
+
+- `mode: "task"` — free-text input used to produce a `mode: "task"`
+  envelope with `track`, `primary_skill`, `options`, and friends. The
+  deterministic flag-override path (`--quick` / `--deep` / `--debug`)
+  is now the only way a route call returns a resolved track; free-text
+  input lands on `mode: "classify"` with the host LLM picking.
+- `mode: "question"` — the regex-based question heuristic is gone.
+  Host LLMs route inquiry-shaped prompts to `apt:discuss` via the
+  envelope, so questions now get a real investigation loop instead of
+  a bare "answer inline" handler.
+- `KNOWN_SKILLS` / `AGENT_SKILLS` / `INLINE_SKILLS` / `AGENT_NAME_MAP` /
+  `QUESTION_PATTERNS` — these duplicates of per-skill metadata were
+  deleted outright. `src/cli/commands/route.mjs` no longer carries any
+  hardcoded skill set.
+
+### Envelope fields added
+
+- `mode: "classify"` — the new default envelope shape for free-text
+  input. Carries `skills[]`, `classification_meta`, `host_capabilities`,
+  `task_isolation`, `update_check`, `task_description`,
+  `autonomy_override`, `execution_mode`, `needs_autonomy_prompt`, and
+  `classification.source` (`"flag-override"` or `"host-model-deferred"`).
+- `classification_meta.trust_notice` — instruction string telling the
+  host LLM that skill descriptions are untrusted user-supplied data
+  wrapped in `«...»` delimiters. Mitigates prompt injection in skill
+  descriptions (red-team finding on third-party skills).
+- `classification_meta.discovered_roots` — the list of trusted
+  `trusted_skill_sources` roots that were scanned. Host LLMs can lazy-
+  load a full SKILL.md at `discovered_roots[skill.root]/<skill.rel>`.
+- Per-skill `stage`, `intent`, `spawns_agent`, `agent_name`,
+  `default_execution_mode`, `execution_modes`, `gates` — read straight
+  from the skill's fat frontmatter instead of from a central lookup.
+
+### New commands + APIs
+
+- `apt-tools check [<project-dir>] [--skills-root <path>]` — validates
+  every canonical `packages/framework/skills/apt-<slug>/SKILL.md` against
+  the new `SkillFrontmatterSchema` and cross-references every
+  `gates: [...]` entry against the live gate registry. Exits 1 on any
+  error. `apt-tools init` runs the same check before every install as
+  a pre-flight guard.
+- `trusted_skill_sources` in `.aperant/config.json` — optional allowlist
+  of absolute or project-relative paths the router's skill scan will
+  accept. Omit the field to let `getTrustedSkillSources()` compute safe
+  defaults (framework repo skills, monorepo dev path, consumer deps
+  install, host-CLI's install root). Set it to narrow the discovery
+  surface (e.g. only the vendored `@aperant/framework` copy). See
+  [`docs/intents.md`](docs/intents.md) for when to narrow.
+- `CORE_INTENTS` + `CUSTOM_INTENT_REGEX` exported from
+  `src/cli/skill-author/contract.mjs`. Core intents:
+  `implement | capture | discuss | investigate | design | ship | configure | debug`.
+  Custom intents use the `x-*` prefix (e.g. `x-marketing-draft`) and
+  graduate to the core enum after appearing in ≥3 shipping skills. See
+  [`docs/intents.md`](docs/intents.md) for the promotion path.
+- `detectHost()` (`src/cli/host/detect.mjs`) recognizes all 14 installed
+  runtimes by their env vars: existing (claude-code, codex, gemini-cli,
+  opencode, pi) plus 10 new (cursor, windsurf, kilo, copilot,
+  antigravity, augment, trae, qwen, cline, codebuddy). `cli: 'unknown'`
+  combined with free-text input now emits a structured error envelope
+  (`error_code: "unknown_host"`) listing the supported hosts.
+- `src/cli/install/cli-to-install-root.mjs` — shared `cliToInstallRoot(cli)`
+  mapping that both the router (skill scan) and the install pipeline
+  consume via a new `cliId` field on every RUNTIMES entry.
+
+### Frontmatter contract
+
+Every `apt-<slug>/SKILL.md` frontmatter must now validate against
+`packages/framework/schemas/skill-frontmatter.json` (JSON Schema
+Draft-07, mirrored by `SkillFrontmatterSchema` in
+`src/cli/skill-author/contract.mjs`). The 14 required keys:
+
+- `name` (regex `^apt(?::[a-z][a-z0-9-]*)?$` — bare `apt` or `apt:<slug>`)
+- `description` (non-empty one-line string; wrapped in `«...»` in the
+  envelope)
+- `stage` — enum of 14 lifecycle stages
+- `intent` — core enum or `x-*` custom
+- `when_to_use` — one-sentence trigger heuristic
+- `user_invocable` / `internal` / `spawns_agent` — state flags
+- `agent_name` — required non-null when `spawns_agent: true`
+- `allowed-tools` / `argument-hint` — GSD-style
+- `gates` — gate IDs only; cross-referenced at install time
+- `default_execution_mode` / `execution_modes` — 5-mode set:
+  auto | step | plan-mode | plan-only | research
+
+Legacy keys (`triggers`, `color`, `apt-skill-version`, `user-invocable`)
+stay as optional pass-throughs. Install transforms preserve them.
+
+### Upgrade step
+
+In every installed project:
+
+```bash
+/apt:update          # refresh skills/agents/hooks across every runtime
+```
+
+The `/apt:update` flow reads `~/.cache/aperant/apt-update-check.json`
+(written by the SessionStart worker), runs `apt-tools init . --<installed-runtimes>`,
+and clears the update chip from the statusline. No manual migration.
+
+### Statusline chip behavior
+
+Unchanged. The update chip surfaces via the SessionStart hook's cache
+file; the chip clears automatically after `/apt:update`. C34/C35
+infrastructure shipped ahead of this release for exactly this upgrade.
+
+### Host-model classification precision baseline
+
+The 0.3.0 release is gated on `packages/framework/scripts/run-route-eval.mjs`
+producing `precision_overall >= 0.85` against claude-opus-4-7 on a
+40-line paraphrase eval set. The baseline result file is committed
+under `.aperant/benchmarks/route-eval/`. If the number drops below
+0.85 in a future release, D-01's kill criterion fires and routing
+reverts to a subprocess classifier fallback.
+
+**Known limitation — track precision (non-blocking).** The 0.3.0
+baseline posts `precision_skill = 0.872` (release gate — MET) but
+`precision_track = 0.660` on the same eval set. Track inference
+(QUICK / STANDARD / DEEP / DEBUG) is fuzzier than skill pick because
+a single skill often spans multiple tracks depending on prompt scope
+— e.g. "open a PR for the OAuth work" (`apt:ship`) can legitimately
+be QUICK or STANDARD depending on whether there's already a draft to
+finalize. The release gate (AC-RC-3) is on skill precision only; the
+lower track number is captured as a follow-up to either (a) tighten
+SKILL.md `when_to_use` phrasing to disambiguate tracks, or (b) move
+track to a second-pass classification separate from the skill pick.
+Runner output carries both numbers (`precision_skill`, `precision_track`)
+so the follow-up has a reproducible baseline to improve against.
+
+---
+
+## Earlier versions
+
+Prior history lives in commit messages on `main`. The router rewrite in
+0.3.0 is the first entry in this CHANGELOG because it's the first break
+significant enough to need one. Earlier semver bumps were additive
+(`/apt:design`, `/apt:mockup`, `/apt:verify-proof`, etc.) and are
+documented in `VERSIONING.md`'s pre-1.0 stability section.

package/README.md

@@ -1,7 +1,7 @@
 # Aperant Framework
 
 [![npm](https://img.shields.io/npm/v/@aperant/framework)](https://www.npmjs.com/package/@aperant/framework)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)
 
 AI coding framework -- composable skills for planning, executing, verifying, and reviewing code with any LLM provider.
 
@@ -25,9 +25,8 @@ Each skill is self-contained. Use `/apt:plan` alone for planning, `/apt:verify`
 
 In addition to the imperative skill chains above, the framework ships a
 **declarative** runner: author a YAML DAG of skill/agent/tool nodes and
-execute or emit it via `apt-tools wfrun {validate|plan|run}`. See
-[`docs/workflows.md`](./docs/workflows.md) for the schema, examples, and
-v1 limits. Example workflows live under `workflows/examples/`.
+execute or emit it via `apt-tools wfrun {validate|plan|run}`. Example
+workflows live under `workflows/examples/`.
 
 ## Quickstart
 
@@ -52,7 +51,7 @@ If you use Claude Code and prefer the `/plugin install` flow, Aperant ships as a
 /plugin install aperant
 ```
 
-See [`docs/plugin-distribution.md`](./docs/plugin-distribution.md) for the full install / update / uninstall guide, version policy, and marketplace publishing instructions. Both install paths are supported and install the same skills — the plugin path also ships the `apt-*` sub-agents.
+Both install paths are supported and install the same skills — the plugin path also ships the `apt-*` sub-agents.
 
 ### Step 2: Add project constitution (optional)
 
@@ -165,8 +164,6 @@ const manifest: FrameworkManifest = {
 };
 ```
 
-See [docs/api.md](docs/api.md) for the full type reference and mapper authoring guide.
-
 ## Project Structure
 
 ```
@@ -241,9 +238,7 @@ Presets:
 
 `apt-tools init` resolves the effective policy, renders the `.aperant/.gitignore`
 from it, and warns when a public remote (github.com / gitlab.com / bitbucket.org)
-is combined with any sharing toggle. See the [Aperant Framework spec §13.3](https://github.com/Mikalsen-AI/aperant-cloud-desktop/blob/main/docs/frameworks/aperant-framework-spec.md#133-artifact-sharing-taxonomy)
-for the 5-class artifact taxonomy (ephemeral / derived / shared-source /
-durable-source / local-private) that underpins each toggle.
+is combined with any sharing toggle.
 
 ## Part of Aperant
 
@@ -251,4 +246,4 @@ This framework powers the [Aperant IDE](https://github.com/Mikalsen-AI/aperant-c
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+AGPL-3.0-only. See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aperant/framework",
-	"version": "0.6.2",
+	"version": "0.6.3",
 	"description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
 	"author": "Mikalsen AI <hello@mikalsen.ai>",
 	"type": "module",
@@ -71,10 +71,14 @@
 		"context/",
 		"workflows/",
 		"examples/",
-		"docs/",
 		"LICENSE",
 		"README.md",
-		"CONTRIBUTING.md"
+		"CHANGELOG.md",
+		"!**/__tests__/**",
+		"!**/*.test.*",
+		"!**/*.spec.*",
+		"!**/*.test.d.ts.map",
+		"!**/*.test.js.map"
 	],
 	"keywords": [
 		"ai",