@aperant/framework 0.6.2 → 0.6.4

package/docs/output-style.md

@@ -1,216 +0,0 @@
-# Output Style & Statusline (C22)
-
-Closes the minor UX polish gap called out in
-[docs/frameworks/spec-gaps.md#c22](../../../docs/frameworks/spec-gaps.md#c22):
-Claude Code exposes `output-style` and a `statusline` as native primitives;
-Aperant's `apt-tools` historically emitted raw JSON envelopes with no
-framework-managed presentation layer.
-
-C22 introduces:
-
-1. A small, dependency-free `output-style` helper module (`packages/framework/src/cli/output-style/`).
-2. A first-class `apt-tools statusline` command for shell prompt / external
-   statusline tool integration.
-3. TTY-only "sidecar previews" on `apt-tools state` and `apt-tools active`
-   that keep the stdout JSON envelope byte-identical while rendering a
-   human-readable block on stderr.
-
-The goal is polish, not a presentation-layer rewrite — every `apt-tools`
-command still speaks JSON as its primary channel.
-
-## Helpers
-
-All helpers live under `src/cli/output-style/` and are re-exported from the
-barrel `output-style/index.mjs`. They accept a `{ color }` option (default
-`true`) — when `color` is `false`, the return value contains no ANSI escape
-sequences, so piping through `jq`, `tee`, or a log file produces identical
-plain-text output.
-
-```js
-import {
-  section,
-  bullet,
-  kv,
-  table,
-  statusLine,
-  supportsColor,
-  relativeTime,
-} from './output-style/index.mjs'
-```
-
-### `supportsColor({ stream, env })`
-
-Pure function — pass explicit stubs in tests, no process-global mutation.
-
-Precedence:
-
-1. `env.NO_COLOR` is set to any non-empty value → `false` ([no-color.org](https://no-color.org/)).
-2. `env.FORCE_COLOR` is set to any non-empty value other than `"0"` → `true`.
-3. Fall through to `stream.isTTY`.
-
-### `section(title, { color })`
-
-Bold header line. Useful for sectioning stderr sidecars.
-
-```js
-section('Aperant State')
-// → "\x1b[1mAperant State\x1b[0m"   (color on)
-// → "Aperant State"                  (color off)
-```
-
-### `bullet(text, status?, { color })`
-
-`· text` bullet with an optional status icon:
-
-| status | icon | color  |
-|--------|------|--------|
-| `'ok'`      | `✓` | green  |
-| `'fail'`    | `✗` | red    |
-| `'pending'` | `⋯` | yellow |
-| anything else / `undefined` | `·` (dim) | gray |
-
-```js
-bullet('typecheck', 'ok')     // → "✓ typecheck" (green)
-bullet('noop')                // → "· noop" (dim bullet)
-```
-
-### `kv(key, value, { color })`
-
-One fact per line. `key` renders dim, `value` renders bold. `null` /
-`undefined` values render as the em-dash so the column stays aligned.
-
-```js
-kv('active tasks', 3)  // → "active tasks: 3"
-kv('last run', null)   // → "last run: —"
-```
-
-### `table(rows, headers?, { color })`
-
-Minimal ASCII table. Returns `''` on empty rows so sidecars don't emit blank
-noise.
-
-```js
-table([
-  { task: 'plan',    status: 'ok' },
-  { task: 'execute', status: 'pending' },
-], ['task', 'status'])
-```
-
-Column widths are `max(header.length, max(cell.length))`. Headers default to
-the keys of the first row when not supplied.
-
-### `statusLine(data, { color, now })`
-
-The compact form embedded in the `apt-tools statusline` command. Every field
-has a fallback so the line retains a fixed shape:
-
-```
-● aperant · tasks 3 · phase executing · team 2 · 5m ago
-```
-
-Inputs:
-
-- `active_tasks` — number or `{ id: record }` map (object keys are counted).
-- `current_phase` — string or `null`.
-- `last_activity` — ISO string, epoch ms, or `null`.
-- `team_count` — number of live agents.
-
-Missing values render as dim em-dashes. Icon swaps to `○` (gray) when there
-are zero active tasks. Pass `{ now }` in tests to pin the relative-time clock.
-
-### `relativeTime(when, now?)`
-
-`"just now"` / `"5s ago"` / `"12m ago"` / `"3h ago"` / `"2d ago"`. Unparseable
-or missing input returns `'—'`. Negative diffs return `"in the future"`.
-
-## `apt-tools statusline` command
-
-```
-apt-tools statusline <project-dir> [--json | --ansi | --plain]
-```
-
-Reads `.aperant/state.json` and the per-agent `team-status/` directory (via
-the `@internal` CoordinationStore seam, R4-liveness filtered) and emits a
-single-line summary.
-
-**Mode precedence:**
-
-1. `NO_COLOR` env set → always plain (wins over `--ansi`).
-2. `--json` → emit envelope (flag-independent of color).
-3. `--plain` → force no ANSI.
-4. `--ansi` → prefer ANSI.
-5. Default → `supportsColor({ stream: stdout, env })` — TTY yields ANSI,
-   pipe yields plain.
-
-### Envelope shape (`--json`)
-
-```json
-{
-  "status": "ok",
-  "command": "statusline",
-  "projectDir": "/abs/path",
-  "line": "● aperant · tasks 2 · phase executing · team 1 · 3m ago",
-  "data": {
-    "active_task_count": 2,
-    "completed_count": 17,
-    "last_activity": "2026-04-15T12:00:00.000Z",
-    "team_count": 1,
-    "current_phase": "executing"
-  },
-  "updated_at": "2026-04-15T12:03:14.000Z"
-}
-```
-
-An uninitialized project (`.aperant/` missing) returns `status: "not-initialized"`
-with the same envelope shape — a consumer can always render a prompt segment.
-
-### Shell prompt integration
-
-```sh
-# zsh PROMPT segment
-APT_LINE="$(apt-tools statusline "$PWD" --ansi)"
-PROMPT="${APT_LINE}"$'\n'"%n@%m %~ %# "
-```
-
-Set `NO_COLOR=1` globally to strip escapes for a logging-friendly prompt.
-
-## TTY-aware sidecar on `state` and `active`
-
-Two existing commands now emit a human-readable block on stderr when
-`process.stdout.isTTY` is true. Stdout JSON is unchanged — safe for
-`| jq`, test snapshots, and scripting.
-
-```sh
-apt-tools state .            # JSON envelope on stdout + sidecar on stderr
-apt-tools state . 2>/dev/null | jq .status   # identical to pre-C22 behaviour
-```
-
-The sidecar:
-
-- Uses the same `{ color }` gating (NO_COLOR / FORCE_COLOR / isTTY).
-- Writes via a `try/catch`; a closed stderr never crashes the command.
-- Does not run when `stdout.isTTY` is false (piping to another tool).
-
-Only `state` and `active` are wired for v1 — rolling the sidecar out to every
-command was explicitly deferred.
-
-## Scope
-
-**Included in v1:**
-
-- Helpers + the `statusline` command.
-- TTY-sidecar on `state` + `active`.
-- Docs and tests.
-
-**Deferred:**
-
-- Color theme config / user-customizable palette.
-- Sidecar on every command.
-- IPC / Electron renderer status integration (project scope, not framework).
-- New dependencies — C22 is pure-Node manual ANSI, no chalk/kleur/etc.
-
-See also:
-
-- Spec gap: [docs/frameworks/spec-gaps.md#c22](../../../docs/frameworks/spec-gaps.md#c22)
-- Source: `src/cli/output-style/`, `src/cli/commands/statusline.mjs`
-- Tests: `src/__tests__/output-style-helpers.test.ts`, `src/__tests__/integration/smoke-statusline.test.ts`

package/docs/plugin-distribution.md

@@ -1,197 +0,0 @@
-# Claude Code Plugin Distribution
-
-Aperant ships as a Claude Code plugin so any Claude Code user can install the
-full `/apt:*` skill suite and all `apt-*` sub-agents with one command:
-
-```
-/plugin install aperant
-```
-
-This document covers what's in the plugin, how the bundle is built, how to
-install / update / uninstall, and the version policy we follow.
-
-> This is the **plugin install path** for Claude Code users. Codex users, CLI
-> users, and anyone who wants the `apt-tools` binary still use
-> `npx @aperant/framework init` — both paths are supported and produce the
-> same skill surface.
-
-## What's in the plugin
-
-The plugin bundles everything the framework exposes to a Claude Code session:
-
-- **22 skills** — one per directory under `packages/framework/skills/apt*/`,
-  each shipped as a `SKILL.md` with YAML frontmatter. These back the
-  `/apt`, `/apt:plan`, `/apt:execute`, `/apt:verify`, `/apt:review`,
-  `/apt:run`, `/apt:debug`, `/apt:design`, `/apt:discuss`, `/apt:docs`,
-  `/apt:mockup`, `/apt:pause`, `/apt:pr-review`, `/apt:quick`, `/apt:resume`,
-  `/apt:roadmap`, `/apt:roundtable`, `/apt:scan`, `/apt:setup`, `/apt:ship`,
-  `/apt:stress-test`, `/apt:verify-proof` slash commands.
-- **15 agents** — every `packages/framework/agents/apt-*.md` (planner,
-  executor, reviewer, verifier, researcher, team-docs-narrator, and the
-  seven-agent PR review roster).
-- **`.claude-plugin/plugin.json`** — manifest mirroring Claude Code's
-  [plugins-reference](https://code.claude.com/docs/en/plugins-reference)
-  format. Schema: `name`, `version`, `description`, `author`, `homepage`,
-  `repository`, `license`, `keywords`, `skills[]`, `agents[]`, `commands[]`,
-  `mcpServers?`, `outputStyles?`, `lspServers?`, `monitors?`.
-- **`LICENSE`** — AGPL-3.0-only.
-- **`README.md`** — pointer back to this doc.
-
-Not in the plugin:
-
-- **`apt-tools` CLI binary.** That's the deterministic router / state
-  engine — installed separately via `npm i @aperant/framework` (or
-  `npx @aperant/framework init`). Plugin-only users who never invoke the
-  CLI get the skills and agents but not the routing binary.
-- **Hooks.** Claude Code v2.1+ auto-loads `hooks/hooks.json` by convention;
-  `plugin.json` must not duplicate that. Our manifest schema rejects a
-  top-level `hooks` key for exactly this reason.
-- **MCP servers.** Aperant doesn't ship one today; the `mcpServers` slot
-  in the manifest exists for forward-compat only.
-
-## How the bundle is built
-
-```bash
-pnpm --filter @aperant/framework run build-plugin
-```
-
-Produces `packages/framework/dist/plugin/` with the layout:
-
-```
-dist/plugin/
-  .claude-plugin/
-    plugin.json
-  skills/
-    apt/SKILL.md
-    apt-execute/SKILL.md
-    ...
-  agents/
-    apt-executor.md
-    apt-planner.md
-    ...
-  README.md
-  LICENSE
-```
-
-The build script (`scripts/build-plugin.mjs`) enumerates skill directories
-and agent files, parses their YAML frontmatter, validates the assembled
-manifest against `PluginManifestSchema` (from
-`src/schemas/plugin-manifest.ts`), and refuses to publish a manifest that
-references components missing from disk.
-
-Then:
-
-```bash
-pnpm --filter @aperant/framework run publish-plugin
-```
-
-Produces `packages/framework/dist/aperant-plugin-<version>.tgz` + a sidecar
-`publish-instructions.md` describing how to ship the bundle to a marketplace
-or a GitHub release. The script never touches the network — it only produces
-local artifacts.
-
-## Install
-
-### From the Aperant marketplace (recommended once published)
-
-```
-/plugin install aperant@Mikalsen-AI/aperant-marketplace
-```
-
-This is the single-command flow. Claude Code resolves the plugin by name
-against the referenced marketplace repo, installs skills and agents into
-the project, and makes every `/apt:*` command available immediately.
-
-### From a GitHub release tarball
-
-```
-/plugin install https://github.com/Mikalsen-AI/aperant-cloud-desktop/releases/download/framework-v<VERSION>/aperant-plugin-<VERSION>.tgz
-```
-
-Useful if the marketplace PR hasn't landed yet or you want to pin a specific
-pre-release.
-
-### Local development (the skills in this repo itself)
-
-The framework's own development flow uses the skill source directly — you
-don't need to install the plugin when working on `packages/framework/`. The
-skills and agents are already discovered at `.claude/agents/` and the
-`/apt` skill is already available in this repo's CLAUDE.md.
-
-## Update
-
-```
-/plugin update aperant
-```
-
-Pulls the latest version from the same source used at install time. Combine
-with `/plugin list` to see which plugins are installed and their versions.
-
-## Uninstall
-
-```
-/plugin uninstall aperant
-```
-
-Removes the plugin's skills and agents from the project. Does not touch
-`.aperant/` state, task directories, or any code you wrote — those remain
-as they are.
-
-## Version policy
-
-We follow semver (`MAJOR.MINOR.PATCH`) with the following plugin-specific
-conventions:
-
-- **MAJOR** — breaking skill/agent contract changes. Examples: a skill
-  removes a required argument; a sub-agent renames. Expect `/apt:*`
-  workflows to fail until callers migrate.
-- **MINOR** — new skills or agents. Existing commands keep working.
-- **PATCH** — body tweaks inside existing skill/agent `SKILL.md` or
-  `.md` files (clarifications, new rationalization tables, additional
-  examples). No behavioral surprises for callers.
-
-The version in `.claude-plugin/plugin.json` is sourced from
-`packages/framework/package.json` so plugin and npm releases stay aligned.
-
-## CI integration
-
-Add the build + package steps to your release workflow. We don't commit the
-`.github/workflows/*` edit here — we just recommend the shape:
-
-```yaml
-- name: Build plugin
-  run: pnpm --filter @aperant/framework run build-plugin
-- name: Package plugin
-  run: pnpm --filter @aperant/framework run publish-plugin
-- name: Upload tarball
-  uses: actions/upload-artifact@v4
-  with:
-    name: aperant-plugin
-    path: packages/framework/dist/aperant-plugin-*.tgz
-```
-
-For marketplace publishing, follow `publish-instructions.md` inside the
-built bundle (`dist/plugin/publish-instructions.md`) — it's regenerated on
-every `publish-plugin` run with the current version baked in.
-
-## Coexistence with `npx @aperant/framework init`
-
-Both paths remain supported and install the same skills:
-
-| Install path | For | Installs |
-|---|---|---|
-| `/plugin install aperant` | Claude Code users | Skills + agents into the Claude Code project, managed via `/plugin` lifecycle commands |
-| `npx @aperant/framework init` | Codex users, CLI-only users, anyone who wants `apt-tools` | Skills into `.claude/commands/aperant/` + `apt-tools` CLI binary via pnpm/npm |
-
-If you use both, the plugin's skills take precedence inside Claude Code
-sessions because Claude Code resolves plugin-scoped commands before
-project-scoped ones.
-
-## References
-
-- [Claude Code Plugins reference](https://code.claude.com/docs/en/plugins-reference)
-- [anthropics/claude-plugins-official](https://github.com/anthropics/claude-plugins-official)
-- Schema: [`packages/framework/src/schemas/plugin-manifest.ts`](../src/schemas/plugin-manifest.ts)
-- Build script: [`packages/framework/scripts/build-plugin.mjs`](../scripts/build-plugin.mjs)
-- Publish script: [`packages/framework/scripts/publish-plugin.mjs`](../scripts/publish-plugin.mjs)
-- Spec gap: [`docs/frameworks/spec-gaps.md#c5`](../../../docs/frameworks/spec-gaps.md#c5)

package/docs/profiles.md

@@ -1,128 +0,0 @@
-# Profiles (C19)
-
-**Status:** v1 shipped.
-
-Profiles are a lightweight composition vehicle for framework standards. A
-profile is a YAML file that optionally `extends` another profile, producing a
-cascade chain that the framework resolves into a single flat record.
-
-The v1 shape is intentionally tiny — profiles are a **composition vehicle**,
-not a config kitchen sink. They solve the mono-repo-with-sub-teams problem
-without inventing a new config surface.
-
-## Storage
-
-```
-.aperant/profiles/<name>.yaml
-```
-
-- File format is **YAML** (reuses the `yaml` dep already used by C17 wfrun).
-- The filename slug must match the `name` field inside the document.
-- Slug regex: `/^[a-z0-9][a-z0-9-]*$/`.
-
-## Schema
-
-```yaml
-name: team-platform            # required, slug
-extends: default               # optional, slug — single parent
-description: "Platform team"   # optional
-obligations:                   # optional — each mirrors a parsed AGENTS.md principle
-  - id: <slug>
-    title: <string>
-    text: <string>
-    severity: must | should | never | principle | obligation
-conventions:                   # optional — flat string map
-  imports: extensionless
-tooling:                       # optional — flat string map
-  linter: biome
-
-# Fold-control sentinels. Default = false = child replaces parent entirely.
-merge_obligations: true        # concat + dedup by id, child wins on collision
-merge_conventions: true        # shallow object merge, child wins per key
-merge_tooling: true            # shallow object merge, child wins per key
-```
-
-All object keys are `.strict()` — unknown top-level keys are rejected.
-
-## Inheritance model
-
-- **Single-parent linear chain** via `extends: <name>`. Diamond inheritance
-  is out of scope for v1.
-- **Depth cap:** `MAX_PROFILE_DEPTH = 8`. Exceeding this fails with
-  `reason: 'max profile depth exceeded (8)'`.
-- **Cycle detection:** cycles like `a → b → a` fail with
-  `reason: 'cycle detected: a → b → a'`.
-- **Dangling extends:** an `extends: <ghost>` where `<ghost>.yaml` is missing
-  fails with `reason: 'unknown parent profile: ghost'`.
-
-## Resolution (fold order)
-
-The cascade is folded left-to-right from root to target:
-
-```
-default → team-platform → my-feature
-```
-
-1. Start with the root profile (no merge flags read — it has no parent).
-2. For each child, for each of `obligations | conventions | tooling`:
-   - If the child **has** the key and `merge_<field>: true` → merge with
-     parent value (concat+dedup by `id` for obligations, shallow object
-     merge for conventions/tooling).
-   - If the child **has** the key and the merge sentinel is false/unset →
-     child replaces parent entirely for that field.
-   - If the child **omits** the key → parent's value flows through.
-3. The final `name`, `extends`, and `description` come from the target.
-4. `merge_*` sentinels are stripped from the resolved output.
-
-## CLI
-
-All commands emit a JSON envelope on stdout.
-
-```bash
-# Enumerate every profile under .aperant/profiles/
-apt-tools profile list <project-dir>
-# → { status, command: 'profile-list', count, profiles: [...] }
-
-# Verify a profile resolves cleanly (chain + cycles + schema + depth)
-apt-tools profile validate <project-dir> --name <n>
-# → { status: 'ok', chain: [...] }  |  { status: 'fail', reason, errors? }
-
-# Return the merged resolved record
-apt-tools profile resolve <project-dir> --name <n>
-# → { status: 'ok', chain, resolved }  |  { status: 'fail', ... }
-```
-
-## Constitution hook
-
-The v1 consumer is `apt-tools constitution list`:
-
-```bash
-apt-tools constitution list <project-dir> --profile team-platform
-```
-
-When `--profile` is set, the resolved profile's `obligations[]` are normalized
-into the same `Principle` shape that `parseAgentsMd` emits and appended to the
-AGENTS.md-derived principle list. Dedup is by normalized title — if a profile
-obligation collides with an existing AGENTS.md principle, **AGENTS.md wins**
-(so profiles cannot silently shadow hard-coded project principles).
-
-Profile-sourced principles carry `source.section = "profile:<name>"` and
-`source.line = -1` so downstream consumers can tell them apart from
-file-derived principles.
-
-Without `--profile`, the output is unchanged — the flag is strictly opt-in.
-
-## Out of scope (v1)
-
-- Multi-parent inheritance / mixins.
-- JSON / TOML profile formats.
-- Automatic profile discovery / selection.
-- Making planner / executor / reviewer profile-aware beyond the constitution
-  hook.
-- Writing / editing profiles via CLI (`profile init`, `profile set`).
-- Profile inheritance across repos (registry lookup).
-
-## Examples
-
-See `packages/framework/examples/profiles/` for a worked `default.yaml` +
-`team-platform.yaml` pair.