@aperant/framework 0.6.3 → 0.6.5

package/CHANGELOG.md

@@ -3,6 +3,67 @@
 All notable changes to `@aperant/framework` are documented here. See
 [`VERSIONING.md`](VERSIONING.md) for the per-tier contract.
 
+## 0.6.5 — 2026-05-14 — Drop aggregate envelope cap
+
+Replaces the aggregate `ENVELOPE_MAX_BYTES` cap in
+`src/cli/route/envelope.mjs` with a per-skill description budget. The
+aggregate cap was bumped 9 times in 3 weeks (8192 → 11264) and was
+theater on 1M-token hosts (30 skills × 256 bytes = 0.28 % of context).
+It was a proxy for two unrelated constraints — classifier precision
+(already measured by route-eval) and per-skill description quality
+(never actually enforced) — and shouted at the wrong author each time
+a new skill landed.
+
+- **New constant.** `MAX_DESCRIPTION_BYTES = 256` is exported from
+  `envelope.mjs`. The budget binds visible AND internal skills, so an
+  internal SKILL.md cannot ship a 4 KB description through the
+  side-channel.
+- **New helper.** `enforceDescriptionBudget(skills, budgetBytes)`
+  replaces `truncateLongestFirst`. It walks each skill once: passes
+  through if the wrapped description fits the budget; else tries
+  `truncateDescriptionToFirstSentence`; if the trim succeeds and now
+  fits, marks `truncated:true` and increments `truncated_count`; if the
+  trim still doesn't fit (or trim was a no-op), records the offender
+  (`{ name, bytes, description }`) and stops. The builder throws with
+  the offender named so the next fix lands on the right author the
+  first time.
+- **Error code rename.** The `cmdRoute` catch branch now emits
+  `error_code: 'skill_description_too_long'` (was `'envelope_overflow'`).
+- **Decision source.** Codex spar 2026-05-14.
+- **Tests.** `envelope-budget.test.ts`, `envelope-truncation.test.ts`,
+  and `route-envelope-builder.test.ts` rewritten for the per-skill
+  pathway. Aggregate-cap pins and the 400-byte headroom invariant are
+  gone.
+
+Schema unchanged (still v4). The router envelope JSON shape is
+unchanged for consumers — the only externally observable difference is
+the renamed error_code in the over-budget path.
+
+`task: 14-05-26_drop-aggregate-envelope-max-bytes-cap-fr-03rb`
+
+## 0.6.4 — 2026-05-13 — Upgrade `--yes` infers visibility from git tracking
+
+Patch on top of 0.6.3 closing the last surface of the 0.6.0/0.6.1
+visibility-flip dogfood incident.
+
+- **`init --yes` upgrade path now infers `share.visibility` from git
+  tracking** when the existing config is pre-visibility (v3 schema) and
+  no explicit `--solo`/`--team` was passed. Heuristic: if `git ls-files`
+  reports any tracked file under `.aperant/` or any runtime install root
+  (`.claude/`, `.codex/`, …), assume `team` — these repos were already
+  sharing framework state via git. Otherwise fall back to `solo`. The
+  recorded `applied_defaults` entry tags the inferred case with
+  `source: "--yes (inferred from git tracking)"` so unattended installs
+  remain auditable. Net effect: a team repo that runs `--yes` no longer
+  has `.gitignore` silently rewritten to solo allow-list rules.
+- **`/apt:update` skill hardened.** Step 3 now explicitly forbids adding
+  `--yes` or any Class A flag. If `init` returns a `requires_input`
+  envelope, the skill surfaces it verbatim and stops — the user must
+  pick team vs solo themselves. The 0.6.4 framework inference is a
+  defense-in-depth backstop, not the primary boundary.
+
+No schema bump (still v4). No breaking changes.
+
 ## 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:

package/README.md

@@ -7,19 +7,73 @@ AI coding framework -- composable skills for planning, executing, verifying, and
 
 The Aperant Framework provides a structured methodology for AI-assisted software development. It works as slash commands in Claude Code, tasks in OpenAI Codex, or programmatically via the TypeScript API. One set of prompts, any AI tool.
 
-## What It Does
+## Just type `/apt` — natural language routing
 
-Five composable skills that cover the full implementation lifecycle:
+You don't need to memorize commands. The `/apt` router auto-classifies your input by intent and complexity, then dispatches to the right skill.
 
-| Skill   | Command        | Description                                                                         |
-| ------- | -------------- | ----------------------------------------------------------------------------------- |
-| Plan    | `/apt:plan`    | Analyze a task, assess complexity, investigate codebase, produce spec + implementation plan |
-| Execute | `/apt:execute` | Implement subtasks from a plan with atomic commits and progress tracking             |
-| Verify  | `/apt:verify`  | Score implementation against spec on 4 dimensions (correctness, completeness, quality, coverage) |
-| Review  | `/apt:review`  | Multi-pass AI code review with findings tree and severity classification             |
-| Run     | `/apt:run`     | Full pipeline: plan -> execute -> verify -> review in one command                    |
+```
+/apt add OAuth login with Google
+/apt the chat scroll is jittery — debug it
+/apt help me think through the new pricing model
+/apt typo in the footer — wrong year
+/apt review my PR
+```
 
-Each skill is self-contained. Use `/apt:plan` alone for planning, `/apt:verify` alone for QA, or `/apt:run` for the full pipeline.
+Behind the scenes:
+
+| You type | Router picks | Why |
+|---|---|---|
+| `add OAuth login with Google` | `/apt:plan` | multi-file feature, STANDARD track |
+| `chat scroll is jittery — debug it` | `/apt:debug` | investigation-first language |
+| `help me think through the new pricing model` | `/apt:discuss --brainstorm` | exploratory framing, no concrete deliverable |
+| `typo in the footer — wrong year` | `/apt:quick` | trivial single-file fix |
+| `review my PR` | `/apt:pr-review` | PR reference triggers multi-agent review |
+
+If the router isn't sure, it shows the top candidates and lets you pick. You can always be explicit (`/apt:plan ...`, `/apt:debug ...`) — the router is a shortcut, not the only path. Track classification (QUICK / STANDARD / DEEP / DEBUG) happens inline; no recursive LLM call.
+
+Works identically under Claude Code (`/apt`), Codex (`$apt`), Gemini (`/apt`), and other supported CLIs — see [Host Support](#host-support) below.
+
+## Command reference
+
+All 30+ skills below are also addressable directly. Listed by lifecycle stage.
+
+| Stage | Command | Purpose |
+|---|---|---|
+| **Route** | `/apt` | Smart router — natural-language dispatch to any skill |
+| **Discovery** | `/apt:scan` | Build/refresh `.aperant/features/` registry — recommended after install on brownfield projects |
+| **Discovery** | `/apt:zoom-out` | One-page architectural orientation for an unfamiliar area |
+| **Discovery** | `/apt:improve` | 3-lens scan for refactor opportunities (DEEPENING / INTERFACE-DESIGN / LANGUAGE) |
+| **Discovery** | `/apt:debug` | Systematic debugging with persistent state across context resets |
+| **Planning** | `/apt:discuss` | Brainstorm a vision or lock ambiguous decisions before planning |
+| **Planning** | `/apt:design` | Pre-coding wireframe → critique → handoff to `/apt:plan` |
+| **Planning** | `/apt:mockup` | Visual HTML+Tailwind mockup loop with parallel variants |
+| **Planning** | `/apt:plan` | Investigate codebase, produce `spec.md` + `implementation_plan.json` |
+| **Planning** | `/apt:roundtable` | 10-agent structured debate with supermajority voting for complex decisions |
+| **Planning** | `/apt:stress-test` | Scenario simulation to catch operational gaps in plans before execution |
+| **Planning** | `/apt:prototype` | Question-driven throwaway prototyping (LOGIC + UI branches) |
+| **Build** | `/apt:quick` | Fast single-shot task — skip planning, go straight to implementation |
+| **Build** | `/apt:execute` | Build code from a plan with atomic commits and progress tracking |
+| **Build** | `/apt:run` | Full pipeline: plan → execute → verify → review in one command |
+| **Verify** | `/apt:verify` | 4-dimension QA scoring (correctness / completeness / quality / coverage) |
+| **Verify** | `/apt:verify-proof` | Visual proof verification — screenshots, video, HTML report |
+| **Verify** | `/apt:review` | 6-pass inline code review (logic / security / quality / architecture / performance / docs-coherence) with fix-all pipeline |
+| **Verify** | `/apt:pr-review` | Multi-agent PR review — 6 parallel specialists + validator + fixer + self-reviewer (owned + external authorship modes) |
+| **Ship** | `/apt:ship` | Create PR with QA scores, decision traceability, commit-to-subtask mapping |
+| **Ship** | `/apt:watch-ci` | Post-ship CI watcher — polls PR checks, auto-fixes red, pushes, reschedules |
+| **Ship** | `/apt:close-task` | Post-merge closer — confirm merged, flip phase, GC state |
+| **Session** | `/apt:pause` | Human-initiated handoff — save CONTINUE artifacts when you need to stop |
+| **Session** | `/apt:resume` | Restore context from paused session and route to next action |
+| **Docs** | `/apt:docs` | Generate/update documentation verified against the actual codebase |
+| **Docs** | `/apt:create-docs` | Persona-first product docs from PROJECT.md + personas.json + features registry |
+| **Docs** | `/apt:diagram` | Render a DiagramScene to `.excalidraw` file or live Excalidraw MCP canvas |
+| **Project** | `/apt:bootstrap` | Generate/refresh PROJECT.md (product-context source of truth) |
+| **Project** | `/apt:personas` | Discover 3–5 product personas grounded in code + PROJECT.md |
+| **Project** | `/apt:roadmap` | Manage per-scope milestones, phases, owners, ROADMAP.md rendering |
+| **Project** | `/apt:triage` | Move a task through the 5-state machine (needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix) |
+| **Framework** | `/apt:setup` | Change preferences (verification style, multi-model, parallelization, branching) |
+| **Framework** | `/apt:update` | Refresh installed skills / agents / hooks across every runtime |
+
+Each skill is self-contained — use `/apt:plan` alone for planning, `/apt:verify` alone for QA, or `/apt:run` for the full pipeline.
 
 ### Declarative YAML Workflows (C17)
 

package/agents/apt-improver.md

@@ -0,0 +1,99 @@
+---
+name: apt-improver
+description: Proactive refactor discovery agent — runs apt:improve Phase 1 (explore a named area through DEEPENING / INTERFACE-DESIGN / LANGUAGE lenses) and outputs a candidate refactor inventory. Read-only, no code changes.
+apt-skill-version: {{APT_VERSION}}
+tools: Read, Bash, Grep, Glob
+color: orange
+---
+
+<role>
+You are an Aperant Framework proactive-refactor agent. You scan a named
+area of the codebase through three lenses (DEEPENING, INTERFACE-DESIGN,
+LANGUAGE) and produce a candidate refactor inventory.
+
+Spawned by `/apt:improve` for Phase 1 (Explore). Phases 2 (Present
+candidates) and 3 (Deepen via grill loop) run in the parent agent
+context because they require user interaction.
+
+Your job: read the area, apply the three lenses, output a candidate
+inventory. You are READ-ONLY — no code changes, no decisions locked.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read`
+tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+**Project instructions:** Read `./CLAUDE.md` if it exists for project structure and conventions.
+**Constitution:** Read `AGENTS.md` if it exists for architecture overview.
+**Glossary:** Read `CONTEXT.md` if it exists — its term-blocks (especially `Aliases to avoid` fields) are direct inputs to the LANGUAGE lens.
+
+**Rationalizations (R4):** Read `.aperant/rationalizations/claude-opus-4-6.md` once at session start. Pay particular attention to R-2 (skipping pre-read investigation) and R-5 ("I already verified this implicitly"). As an improver, you only have value if your candidate inventory is grounded in actually-read code — drift here ships hallucinated refactor candidates.
+</project_context>
+
+<environment>
+- **Working directory:** The project root
+- **Note:** You have NO write/edit tools. You investigate and report findings only. Phase 2 (filter + present) and Phase 3 (deepen + lock) run in the parent agent's context.
+</environment>
+
+<process>
+
+## 1. Parse the area name
+
+Extract the area from the spawn prompt. Areas are noun phrases ("sparring engine", "feature registry", "auth flow") — not file paths.
+
+If the area is ambiguous, ask the parent ONE clarifying question via your report — do NOT enter a multi-turn interview.
+
+## 2. Load CONTEXT.md (if present)
+
+If `CONTEXT.md` exists at the project root, read it and extract:
+
+- Term-blocks whose canonical term, definition, or aliases-to-avoid match keywords in the area
+- The full alias list (LANGUAGE lens grep source)
+
+If CONTEXT.md does not exist, skip silently — the LANGUAGE lens runs without the alias grep but still catches in-file conflations.
+
+## 3. Apply the three lenses
+
+Read the lens descriptions (the parent has them in context; if you don't, read them from disk).
+Paths below are relative to the project root (monorepo: `<repo>/packages/framework/` is the
+framework root; standalone install: the project root IS the framework root, so use
+`skills/apt-improve/` directly):
+
+- `packages/framework/skills/apt-improve/DEEPENING.md` (monorepo) or `skills/apt-improve/DEEPENING.md` (standalone)
+- `packages/framework/skills/apt-improve/INTERFACE-DESIGN.md` (monorepo) or `skills/apt-improve/INTERFACE-DESIGN.md` (standalone)
+- `packages/framework/skills/apt-improve/LANGUAGE.md` (monorepo) or `skills/apt-improve/LANGUAGE.md` (standalone)
+
+For each lens, walk the area's files and flag candidates per the lens's red-flag list.
+
+## 4. Output the candidate inventory
+
+Produce a structured report:
+
+```markdown
+# apt:improve Phase-1 inventory — {area}
+
+## DEEPENING candidates
+- `{File}:{Symbol}` — shallow ({reason}); deletion-test target.
+- ...
+
+## INTERFACE-DESIGN candidates
+- `{Module A}` ↔ `{Module B}` — {red-flag name} ({one-line evidence}).
+- ...
+
+## LANGUAGE candidates
+- `{File}:{Line}` — uses `{wrong-term}` for `{canonical}` ({CONTEXT.md reference if applicable}).
+- ...
+
+## Files read
+- {file1}
+- ...
+```
+
+Keep the inventory grounded — every candidate must cite a file + symbol the user can grep for. No speculation; no candidates inferred from filenames alone.
+
+## 5. Hand back to parent for Phase 2/3
+
+Your output is the input to Phase 2 (the parent agent's filter step). Do NOT enter Phase 2 yourself — your role ends here.
+
+</process>

package/agents/apt-planner.md

@@ -199,7 +199,13 @@ If unable to enumerate (network unavailable, action docs unclear), flag it expli
 
 ## 4. Write Specification
 
-Create `{task_dir}/spec.md`:
+The spec.md content format **branches on track** (Pocock adoption ID-05,
+Fast Path Guarantee). QUICK-routed tasks keep the existing 4-section
+shape; STANDARD/DEEP/COMPLEX tasks get a PRD-shaped artifact that
+survives the task as a second-consumer document.
+
+### 4.A. QUICK track / SIMPLE complexity — legacy 4-section spec
+
 ```markdown
 # Task: {task description}
 
@@ -219,6 +225,57 @@ Create `{task_dir}/spec.md`:
 {What this task explicitly does NOT cover}
 ```
 
+### 4.B. STANDARD / DEEP / COMPLEX — PRD-shaped spec.md
+
+```markdown
+# Spec: {task title}
+
+**Task ID:** {task-id}
+**Track:** {STANDARD | DEEP}
+**Scope:** {framework | desktop | web | core | ui | backend | docs}
+
+## Problem Statement
+{What pain are we solving? Cite empirical evidence where possible.}
+
+## Solution
+{Chosen approach + bulleted net delta of files / flags / config / skills.}
+
+## User Stories
+{One **US-NN (persona).** story per user-value slice. Stories map 1:1
+onto subtasks in implementation_plan.json.}
+
+## Implementation Decisions
+{Load-bearing principles carried into every subtask. Format:
+"### ID-NN: {title}" + rationale + practical consequence.}
+
+## Testing Decisions
+{One block per test family: "### TD-NN: {family}" + what's covered +
+which subtask owns the test file. Fast Path regression tests MUST be
+enumerated here.}
+
+## Out of Scope
+{Non-goals. Each bullet names what is deferred + where it belongs.}
+
+## Further Notes
+{Sequencing rationale, risk surface, dependencies, files-affected
+preview, and any other executor-load-bearing context.}
+
+### Acceptance Criteria
+{Cross-cutting **AC1..ACN** list — each AC gets a stable ID. Subtasks
+reference these IDs via the per-subtask `acceptance_criteria` field.}
+```
+
+**PRD section ordering is load-bearing.** `apt-tools coverage-check
+validate` greps `## Acceptance Criteria`; `apt-tools consistency check`
+greps `## Solution` and `## User Stories`. Renaming or reordering these
+sections breaks downstream tooling and the C15 consistency rules.
+
+**Do NOT interview the user.** The PRD is synthesized from the task
+description + codebase investigation + AGENTS.md, not from a clarifying
+back-and-forth. If a section truly cannot be filled, write
+`{TBD — needs user input}`; do NOT pause for clarification (that is
+`apt:discuss`'s surface, not the planner's).
+
 ### 4.05. Design Reference section (C24 — when design.md exists)
 
 When `{task_dir}/design.md` exists, `spec.md` MUST include a `## Design Reference` section directly below `## Requirements`. Shape:
@@ -275,12 +332,41 @@ fix it now, not later.
 
 ## 5. Create Implementation Plan
 
-Create `{task_dir}/implementation_plan.json`:
+Subtask schema branches on track (Pocock adoption ID-05 — Fast Path Guarantee).
+
+### 5.A. QUICK track / SIMPLE complexity — legacy flat subtask schema
+
+```json
+{
+  "task": "{task description}",
+  "complexity": "simple",
+  "spec": "spec.md",
+  "subtasks": [
+    {
+      "id": "1",
+      "title": "{subtask title}",
+      "description": "{what to do — concrete, not vague}",
+      "files": ["path/to/file1.ts", "path/to/file2.ts"],
+      "dependencies": [],
+      "status": "pending",
+      "verification": "{command or check to verify completion}"
+    }
+  ]
+}
+```
+
+QUICK subtasks omit `hitl`, `afk`, `acceptance_criteria`, and `user_value`
+fields. The one-shot path doesn't need user-value framing or per-subtask
+HITL gates.
+
+### 5.B. STANDARD / DEEP / COMPLEX — vertical-slice subtask schema
+
 ```json
 {
   "task": "{task description}",
-  "complexity": "simple|standard|complex",
+  "complexity": "standard|complex",
   "spec": "spec.md",
+  "vertical_slice_schema_version": "1",
   "declared_persona_tier": "primary",
   "declared_personas": ["mobile-dev"],
   "tier_confidence": "high",
@@ -308,29 +394,48 @@ Create `{task_dir}/implementation_plan.json`:
   "subtasks": [
     {
       "id": "1",
-      "title": "{subtask title}",
+      "title": "{subtask title — user-value framing, not 'add UI'}",
       "description": "{what to do — concrete, not vague}",
       "files": ["path/to/file1.ts", "path/to/file2.ts"],
       "acceptance_criteria": ["AC1", "AC3"],
       "dependencies": [],
       "status": "pending",
+      "hitl": "required | review | none",
+      "afk": "safe | unsafe",
+      "user_value": "{one-line user-value framing — who benefits, how}",
       "verification": "{command or check to verify completion}"
     }
   ]
 }
 ```
 
+Mandatory STANDARD/DEEP fields per subtask:
+
+- `hitl` — `"required" | "review" | "none"`. `required` blocks the
+  executor pending human approval (autonomy 1 always pauses; autonomy 2
+  batches; autonomy 3 escalates only on conflict). `review` means the
+  human reviews the diff post-hoc, not blocking. `none` is agent-only.
+- `afk` — `"safe" | "unsafe"`. `safe` means proceed unattended. `unsafe`
+  means pause at the start of this subtask if no human is present
+  (autonomy < 3).
+- `acceptance_criteria` — `string[]` of id-refs (`"AC1"`, …) into spec.md's
+  `## Acceptance Criteria` section.
+- `user_value` — one-line framing of WHO benefits and HOW. Prevents
+  horizontal slicing — every subtask is a vertical user-shippable slice.
+
+Plan-level: `vertical_slice_schema_version: "1"` declares the schema
+version so future migrations can detect this plan as v1.
+
 Rules:
 - Each subtask completable in one focused session
 - Dependencies form a DAG (no circular deps)
 - Verification must be automated (test command, grep check, type check)
 - Files list must be exhaustive — every file the subtask touches
-- `acceptance_criteria` is mandatory: list the canonical AC id-refs
-  (`"AC1"`, `"AC3"`, ...) from the `## Acceptance Criteria` section of
-  spec.md that this subtask satisfies. Verbatim AC text is accepted but
-  discouraged — the id-ref form is stable across spec edits. Every AC in
-  spec.md must be referenced by at least one subtask; gate G8
-  (`consistency-check`) enforces this on ship.
+- `acceptance_criteria` is mandatory on STANDARD/DEEP: every AC in spec.md
+  must be referenced by at least one subtask; gate G8
+  (`consistency-check`) enforces this on ship. Verbatim AC text is
+  accepted but discouraged — id-refs are stable across spec edits.
+- Subtask title MUST frame user value, not file scope.
 
 ### 5.1 Framework-scope doc-sync rule
 

package/dist/__test-helpers/run-cmd.d.mts

@@ -1,15 +1,17 @@
 /**
  * @param {Function} cmdFn — the Layer 1 cmd function (sync or async).
  * @param {unknown[]} [args=[]] — argv-shaped positional args.
- * @param {{ strictExit?: boolean, env?: Record<string, string> }} [opts]
- * @returns {Promise<{ result: unknown, stdout: string, exitCode: number }>}
+ * @param {{ strictExit?: boolean, resetCaches?: boolean, env?: Record<string, string> }} [opts]
+ * @returns {Promise<{ result: unknown, stdout: string, stderr: string, exitCode: number }>}
  */
 export function runCmd(cmdFn: Function, args?: unknown[], opts?: {
     strictExit?: boolean;
+    resetCaches?: boolean;
     env?: Record<string, string>;
 }): Promise<{
     result: unknown;
     stdout: string;
+    stderr: string;
     exitCode: number;
 }>;
 //# sourceMappingURL=run-cmd.d.mts.map

package/dist/__test-helpers/run-cmd.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"run-cmd.d.mts","sourceRoot":"","sources":["../../src/__test-helpers/run-cmd.mjs"],"names":[],"mappings":"AAiCA;;;;;GAKG;AACH,+CAJW,OAAO,EAAE,SACT;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACpD,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAoD1E"}
+{"version":3,"file":"run-cmd.d.mts","sourceRoot":"","sources":["../../src/__test-helpers/run-cmd.mjs"],"names":[],"mappings":"AAiDA;;;;;GAKG;AACH,+CAJW,OAAO,EAAE,SACT;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC3E,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAiF1F"}

package/dist/__test-helpers/run-cmd.mjs

@@ -2,16 +2,18 @@
  * run-cmd.mjs — D-05 in-process command harness.
  *
  * `runCmd(cmdFn, args, opts)` invokes a Layer 1 command function in-process
- * (no subprocess), captures stdout, traps any process.exit calls (via a
- * try/finally restore), and returns:
+ * (no subprocess), captures stdout + stderr, traps any process.exit calls
+ * (via a try/finally restore), stubs `process.stdin.isTTY` /
+ * `process.stdout.isTTY` to `false` for the trapped invocation duration, and
+ * returns:
  *
- *     { result, stdout, exitCode }
+ *     { result, stdout, stderr, exitCode }
  *
  * `result` is the cmd function's return value (typically `{envelope, exitCode}`
  * after the migration; `null` if the cmd called process.exit before returning).
- * `stdout` is the captured stdout.write payload (string). `exitCode` is the
- * effective exit code: the trapped exit code if process.exit was called, else
- * `result.exitCode`, else 0.
+ * `stdout` / `stderr` are the captured `*.write` payloads (string). `exitCode`
+ * is the effective exit code: the trapped exit code if process.exit was called,
+ * else `result.exitCode`, else 0.
  *
  * D-05 (d) decision: strictExit DEFAULTS TO TRUE — the harness throws a
  * strict-mode-violation Error any time a Layer 1 cmd calls process.exit.
@@ -19,10 +21,23 @@
  * `{ strictExit: false }` until the underlying cmd is rewritten. After Wave 5
  * (subtask 25) zero `strictExit: false` opt-outs remain in __tests__/.
  *
- * Restoration: process.exit and process.stdout.write are saved at entry and
- * restored unconditionally in a try/finally. A test that crashes mid-call
- * still leaves the global state byte-identical for the next test in the file.
+ * Restoration: process.exit, process.stdout.write, process.stderr.write, and
+ * the two `isTTY` bits are saved at entry and restored unconditionally in a
+ * try/finally. A test that crashes mid-call still leaves the global state
+ * byte-identical for the next test in the file.
+ *
+ * Cache resets (F3 subtask 1): by default the harness clears the two
+ * path-keyed module-graph caches that can leak across cmd invocations within
+ * a single vitest worker — `skill-discover._discoverCache` and the
+ * `agent-identity` identity cache. The `gate/registry` and
+ * `consistency/registry` registries are NOT cleared by default because their
+ * built-in entries are populated by barrel imports that ESM evaluates exactly
+ * ONCE per process — clearing them would leave subsequent cmd invocations
+ * looking at an empty registry. Tests that specifically need an empty
+ * registry import `__resetCaches()` from those modules directly.
  */
+import { __resetCaches as __resetAgentIdentityCaches } from '../cli/coordination/agent-identity.mjs';
+import { __resetCaches as __resetSkillDiscoverCaches } from '../cli/route/skill-discover.mjs';
 class ExitTrap extends Error {
     constructor(code) {
         super(`apt-tools cmd called process.exit(${code})`);
@@ -32,18 +47,26 @@ class ExitTrap extends Error {
 /**
  * @param {Function} cmdFn — the Layer 1 cmd function (sync or async).
  * @param {unknown[]} [args=[]] — argv-shaped positional args.
- * @param {{ strictExit?: boolean, env?: Record<string, string> }} [opts]
- * @returns {Promise<{ result: unknown, stdout: string, exitCode: number }>}
+ * @param {{ strictExit?: boolean, resetCaches?: boolean, env?: Record<string, string> }} [opts]
+ * @returns {Promise<{ result: unknown, stdout: string, stderr: string, exitCode: number }>}
  */
 export async function runCmd(cmdFn, args = [], opts = {}) {
-    const { strictExit = true } = opts;
+    const { strictExit = true, resetCaches = true } = opts;
+    if (resetCaches) {
+        __resetSkillDiscoverCaches();
+        __resetAgentIdentityCaches();
+    }
     let trappedExit = null;
     const origExit = process.exit;
-    // Save the unbound original — assignment to process.stdout.write replaces
+    // Save the unbound originals — assignment to process.stdout.write replaces
     // the property; restoration of the original reference returns the global
     // to byte-identical state (Function-identity check in self-tests).
     const origWrite = process.stdout.write;
+    const origErrWrite = process.stderr.write;
+    const origStdinIsTTY = process.stdin.isTTY;
+    const origStdoutIsTTY = process.stdout.isTTY;
     const stdoutBuf = [];
+    const stderrBuf = [];
     process.exit = (code) => {
         trappedExit = typeof code === 'number' ? code : 0;
         if (strictExit) {
@@ -59,6 +82,16 @@ export async function runCmd(cmdFn, args = [], opts = {}) {
         stdoutBuf.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf-8'));
         return true;
     };
+    process.stderr.write = (chunk, ..._rest) => {
+        stderrBuf.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf-8'));
+        return true;
+    };
+    // F3 subtask 1 (Q3): defensively force the non-interactive branch for any
+    // cmd that gates on isTTY (init.mjs:127,167,1013 + cmdState's TTY sidecar).
+    // Under vitest workers isTTY is usually `undefined`, but stubbing to `false`
+    // removes the Node-version drift risk.
+    process.stdin.isTTY = false;
+    process.stdout.isTTY = false;
     try {
         const result = await cmdFn(...args);
         const exitCode = trappedExit !== null
@@ -66,11 +99,16 @@ export async function runCmd(cmdFn, args = [], opts = {}) {
             : typeof result === 'object' && result !== null && typeof result.exitCode === 'number'
                 ? result.exitCode
                 : 0;
-        return { result, stdout: stdoutBuf.join(''), exitCode };
+        return { result, stdout: stdoutBuf.join(''), stderr: stderrBuf.join(''), exitCode };
     }
     catch (e) {
         if (e instanceof ExitTrap) {
-            return { result: null, stdout: stdoutBuf.join(''), exitCode: e.code };
+            return {
+                result: null,
+                stdout: stdoutBuf.join(''),
+                stderr: stderrBuf.join(''),
+                exitCode: e.code,
+            };
         }
         // Re-throw non-trap errors (including the strict-mode-violation Error
         // thrown above) so tests can assert via expect(...).rejects.
@@ -79,6 +117,9 @@ export async function runCmd(cmdFn, args = [], opts = {}) {
     finally {
         process.exit = origExit;
         process.stdout.write = origWrite;
+        process.stderr.write = origErrWrite;
+        process.stdin.isTTY = origStdinIsTTY;
+        process.stdout.isTTY = origStdoutIsTTY;
     }
 }
 //# sourceMappingURL=run-cmd.mjs.map

package/dist/__test-helpers/run-cmd.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"run-cmd.mjs","sourceRoot":"","sources":["../../src/__test-helpers/run-cmd.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,QAAS,SAAQ,KAAK;IAC3B,YAAY,IAAI;QACf,KAAK,CAAC,qCAAqC,IAAI,GAAG,CAAC,CAAA;QACnD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IACjB,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,IAAI,GAAG,EAAE;IACvD,MAAM,EAAE,UAAU,GAAG,IAAI,EAAE,GAAG,IAAI,CAAA;IAElC,IAAI,WAAW,GAAG,IAAI,CAAA;IACtB,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAA;IAC7B,0EAA0E;IAC1E,yEAAyE;IACzE,mEAAmE;IACnE,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAA;IACtC,MAAM,SAAS,GAAG,EAAE,CAAA;IAEpB,OAAO,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE;QACvB,WAAW,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;QACjD,IAAI,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CACd,gBAAgB,WAAW,iDAAiD;gBAC3E,uFAAuF;gBACvF,yFAAyF,CAC1F,CAAA;QACF,CAAC;QACD,kEAAkE;QAClE,sDAAsD;QACtD,MAAM,IAAI,QAAQ,CAAC,WAAW,CAAC,CAAA;IAChC,CAAC,CAAA;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,EAAE,EAAE;QAC1C,SAAS,CAAC,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAA;QACxF,OAAO,IAAI,CAAA;IACZ,CAAC,CAAA;IAED,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,CAAA;QACnC,MAAM,QAAQ,GACb,WAAW,KAAK,IAAI;YACnB,CAAC,CAAC,WAAW;YACb,CAAC,CAAC,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;gBACrF,CAAC,CAAC,MAAM,CAAC,QAAQ;gBACjB,CAAC,CAAC,CAAC,CAAA;QACN,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAA;IACxD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACZ,IAAI,CAAC,YAAY,QAAQ,EAAE,CAAC;YAC3B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;QACtE,CAAC;QACD,sEAAsE;QACtE,6DAA6D;QAC7D,MAAM,CAAC,CAAA;IACR,CAAC;YAAS,CAAC;QACV,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAA;QACvB,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,SAAS,CAAA;IACjC,CAAC;AACF,CAAC"}
+{"version":3,"file":"run-cmd.mjs","sourceRoot":"","sources":["../../src/__test-helpers/run-cmd.mjs"],"names":[],"mappings":"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"}

package/dist/cli/artifacts/classification.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"classification.d.mts","sourceRoot":"","sources":["../../../src/cli/artifacts/classification.mjs"],"names":[],"mappings":"AAuRA;;;;;;GAMG;AACH,wCAHa,SAAS,MAAM,EAAE,CAO7B;AAED;;;;;GAKG;AACH,sCAHa,SAAS,MAAM,EAAE,CAO7B;AAED;;;;;;;;;;;;;;;GAeG;AACH,8CANW,MAAM,UAEN,EAAE,GACA,aAAa,GAAG,WAAW,GAAG,IAAI,CAW9C;AAED;;;;;;;GAOG;AACH,sDAJW,MAAM,GACJ;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAalE;AAED;;;;;;GAMG;AACH,yCAJW,MAAM,EAAE,GACN,MAAM,EAAE,CAMpB;AAED;;;;;;GAMG;AACH,uCAJW,MAAM,EAAE,GACN,MAAM,EAAE,CAMpB;AA1VD;;;;;GAKG;AACH;;;GAGE"}
+{"version":3,"file":"classification.d.mts","sourceRoot":"","sources":["../../../src/cli/artifacts/classification.mjs"],"names":[],"mappings":"AAiSA;;;;;;GAMG;AACH,wCAHa,SAAS,MAAM,EAAE,CAO7B;AAED;;;;;GAKG;AACH,sCAHa,SAAS,MAAM,EAAE,CAO7B;AAED;;;;;;;;;;;;;;;GAeG;AACH,8CANW,MAAM,UAEN,EAAE,GACA,aAAa,GAAG,WAAW,GAAG,IAAI,CAW9C;AAED;;;;;;;GAOG;AACH,sDAJW,MAAM,GACJ;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAalE;AAED;;;;;;GAMG;AACH,yCAJW,MAAM,EAAE,GACN,MAAM,EAAE,CAMpB;AAED;;;;;;GAMG;AACH,uCAJW,MAAM,EAAE,GACN,MAAM,EAAE,CAMpB;AApWD;;;;;GAKG;AACH;;;GAGE"}

package/dist/cli/artifacts/classification.mjs

@@ -171,6 +171,11 @@ const RULES = Object.freeze([
         class: ARTIFACT_CLASS.EPHEMERAL,
         why: 'Append-only daily log of lifecycle transitions.',
     },
+    {
+        pattern: '.aperant/install/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Install telemetry/summaries (last-init/last-install) — runtime artifacts.',
+    },
     {
         pattern: '.aperant/team-status/**',
         class: ARTIFACT_CLASS.EPHEMERAL,
@@ -246,6 +251,11 @@ const RULES = Object.freeze([
         class: ARTIFACT_CLASS.EPHEMERAL,
         why: 'Design-scan outputs (tokens, extracted repo, synthesis) — rebuildable.',
     },
+    {
+        pattern: '.aperant/product-context.json',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Derived/read-through sidecar used by CLI flows; rebuilt from onboarding context.',
+    },
     // ── Explicit ephemeral: secrets/tokens MUST never classify committable ─
     {
         pattern: '.aperant/secrets/**',