@aperant/framework 0.6.2

package/docs/output-style.md

@@ -0,0 +1,216 @@
+# 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

@@ -0,0 +1,197 @@
+# 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

@@ -0,0 +1,128 @@
+# 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.