@aperant/framework 0.6.2 → 0.6.4

package/docs/seeds.md

@@ -1,221 +0,0 @@
-# Seeds
-
-> **Status:** Shipped 2026-04-16 (C12).
-> **Spec reference:** [`docs/frameworks/spec-gaps.md#c12`](../../docs/frameworks/spec-gaps.md#c12).
-
-Seeds are the long-running thematic tier **above** milestones in the Aperant
-hierarchy. A seed groups 1..N milestones that share a theme — "close
-competitor-parity gaps", "launch the cloud beta", "kill the flaky CI" —
-even when those milestones live in different scopes (framework, project,
-platform, …).
-
-The hierarchy now has three levels:
-
-```
-seed          — months-long thematic container (cross-scope)
-  milestone   — weeks-long feature cluster (scoped)
-    phase     — days-long shippable increment (scoped)
-```
-
-Each tier has a clear decision rule: a milestone exists when you need a
-goal you can rally the team around; a phase exists when you need a
-commit-level checkpoint. A seed exists when the same goal keeps showing
-up across milestones for months — you need a single place to see the
-whole initiative's health without scanning every scope's
-`ROADMAP.md`.
-
-## When to create a seed
-
-Rule of thumb: **create a seed when ≥3 milestones across ≥1 scope share
-a north star that would otherwise live only in a Slack thread or a
-README heading**.
-
-Signals that a seed is appropriate:
-
-- The initiative spans weeks-to-months (not a single sprint).
-- Progress is tracked in terms of milestones completed, not phases.
-- Stakeholders ask "how's the X initiative going?" and the answer
-  requires reading through multiple milestones.
-- You want a single `SEEDS.md` summary page for stakeholders who don't
-  live in the roadmap day-to-day.
-
-Signals that a seed is **not** needed:
-
-- A single milestone covers everything — just use the milestone title.
-- The work spans <2 weeks — milestones + phases are enough.
-- The initiative is internal-only and has no external stakeholders.
-
-Seeds are **optional**. The framework never requires them; existing
-projects and single-milestone initiatives work exactly as before.
-
-## CLI reference
-
-All seed commands live under `apt-tools seed <subcommand>`:
-
-| Command | Purpose |
-|---------|---------|
-| `seed init .` | Create the empty `.aperant/roadmap/seeds.json` stub. Idempotent. |
-| `seed create . --id <id> --title <t> [--goal <g>] [--notes-url <url>]` | Add a new seed (status=active). |
-| `seed list . [--status <s>]` | List seeds with milestone + task counts. |
-| `seed get . --id <id> [--include-tasks]` | Detail view — optionally walks `state.json` for every task under the seed. |
-| `seed assign . --id <id> --milestone <m> [--scope <s>]` | Attach a milestone to a seed. Scope auto-resolves when unique. Requires `--force --reason` to override a conflict. |
-| `seed unassign . --id <id> --milestone <m> [--scope <s>]` | Detach a milestone. Leaves the seed in place even when it becomes empty (AC8). |
-| `seed close . --id <id>` | Mark a seed `status=completed` without cascading to its milestones (AC10). |
-| `seed archive . --id <id>` | Mark a seed `status=archived`. Reversible by `--force` on create with the same id. |
-| `seed validate .` | Walk seeds.json ↔ every scope's milestones.json and report drift. Exit 1 on any drift (AC6). |
-| `roadmap render --seeds` | Emit `.aperant/roadmap/SEEDS.md` — the cross-scope companion to each scope's `ROADMAP.md`. |
-
-### Flags recap
-
-- `--force --reason <why>` — required together for overriding a conflict
-  (assigning a milestone already owned by another seed). Writes history
-  entries on both sides of the move. Matches the C28 `roadmap move`
-  semantics.
-- `--scope <s>` — explicit scope; usually omitted because the resolver
-  auto-finds the single scope owning the milestone id. Pass it when the
-  same milestone id exists in multiple scopes.
-
-## Worked example: `parity-sprint`
-
-This repo uses a seed named `parity-sprint` to group the four
-framework-track milestones that close the C1..C30 parity gap cluster.
-The setup is the canonical "created once, referenced forever" flow:
-
-```bash
-# 1. Bootstrap (done once — `apt-tools init` now auto-creates the stub).
-apt-tools seed init .
-
-# 2. Create the seed.
-apt-tools seed create . \
-  --id parity-sprint \
-  --title 'Close competitor-parity gaps (C1–C30)' \
-  --goal 'Ship the C1..C30 cluster that brings Aperant to parity with mature coding-agent frameworks.' \
-  --notes-url docs/frameworks/spec-gaps.md
-
-# 3. Attach every milestone in the cluster.
-for ms in fw-p0-critical fw-p1-next-sprint fw-p2-polish fw-p3-deferred; do
-  apt-tools seed assign . --id parity-sprint --milestone "$ms"
-done
-
-# 4. Render the human-readable summary.
-apt-tools roadmap render . --seeds
-# → writes .aperant/roadmap/SEEDS.md
-```
-
-`SEEDS.md` now carries:
-
-```markdown
-# Seeds
-
-*1 active · 0 other · Last updated: 2026-04-16T...*
-
-## Close competitor-parity gaps (C1–C30)
-
-**Goal:** Ship the C1..C30 cluster that brings Aperant to parity with
-  mature coding-agent frameworks.
-**ID:** `parity-sprint` · **Status:** active
-**Tasks:** N active / M completed
-*Notes: docs/frameworks/spec-gaps.md*
-
-| Scope | Milestone | Phases (done / total) | Tasks |
-|-------|-----------|-----------------------|-------|
-| framework | **Framework P0 — Ship by next milestone** (`fw-p0-critical`) | 11 / 12 | 0 / 0 |
-| framework | **Framework P1 — Next sprint**                (`fw-p1-next-sprint`) | 5 / 5 | 0 / 0 |
-| framework | **Framework P2 — Follow-up polish + parity** (`fw-p2-polish`)     | 7 / 7 | 0 / 0 |
-| framework | **Framework P3 — Deferred nice-to-haves**    (`fw-p3-deferred`)   | 4 / 5 | 1 / 0 |
-```
-
-Every `seed assign` runs a post-check against `seeds.json` + every
-scope's `milestones.json`. If a prior hand-edit left the two files out
-of sync, the assign still succeeds but the reply carries a
-`drift_warning` envelope. That warning points operators at the specific
-row to fix.
-
-## Storage layout
-
-```
-.aperant/roadmap/
-  seeds.json                      ← top-level, cross-scope
-  SEEDS.md                        ← rendered by roadmap render --seeds
-  project/
-    milestones.json               ← legacy blob (wave 2)
-    phases/<phase-id>.json        ← per-phase layout (wave 2+)
-    ROADMAP.md
-  framework/
-    milestones.json
-    phases/<phase-id>.json
-    ROADMAP.md
-```
-
-`seeds.json` shape (schema v1):
-
-```json
-{
-  "version": 1,
-  "updated_at": "2026-04-16T...",
-  "seeds": [
-    {
-      "id": "parity-sprint",
-      "title": "Close competitor-parity gaps (C1–C30)",
-      "goal": "...",
-      "status": "active",
-      "milestones": [
-        { "scope": "framework", "milestone_id": "fw-p0-critical" }
-      ],
-      "created_at": "2026-04-16T...",
-      "closed_at": null,
-      "notes_url": "docs/frameworks/spec-gaps.md",
-      "history": [ /* --force --reason audit entries */ ]
-    }
-  ]
-}
-```
-
-On the milestone side, `milestones.json` records the back-link as a
-single `seed_id` field. The two sides are kept in sync by a two-sided
-atomic write: `seed assign` locks `seeds.json` first (outer), then
-`{scope}/milestones.json` (inner via `saveRoadmapForScope`) — the same
-lock ordering used by `roadmap move` so the two commands never deadlock
-when running concurrently.
-
-## FAQ
-
-**Q: Can a milestone belong to more than one seed?**
-No. A milestone has at most one `seed_id`. If you need a cross-cutting
-view, render two SEEDS.md pages or tag milestones differently — don't
-double-assign.
-
-**Q: Does `seed close` cascade to milestone status?**
-No (AC10). Closing a seed is a lifecycle event on the seed record
-only; its milestones stay at whatever status they were. Use
-`roadmap set-phase-status` to move phases/milestones forward.
-
-**Q: What about tasks? Do they know which seed they belong to?**
-Tasks do not carry `seed_id` (D-04). The seed → milestone → task chain
-is looked up on demand: `apt-tools seed get --include-tasks` walks
-`state.json`'s `active_tasks` + `completed_tasks` and filters by the
-`(scope, milestone_id)` pairs on the seed. This keeps `state.json` thin
-and avoids a 30+ completed-task backfill every time the hierarchy
-changes.
-
-**Q: What if I hand-edit `seeds.json` or `milestones.json`?**
-Run `apt-tools seed validate .` — it reports the drift taxonomy:
-`missing-seed-id`, `wrong-seed-id`, `dangling-seed-id`,
-`orphan-seed-ref`, `duplicate-membership`. Each drift row names the
-specific milestone or seed that's off. Every `seed assign/unassign`
-also runs validate internally and surfaces lingering drift on the
-reply envelope (`drift_warning`).
-
-**Q: Is `seeds.json` shared with the team?**
-By default no — the solo-preset `.aperant/.gitignore` keeps both
-`seeds.json` and `SEEDS.md` private. Flip `share.roadmap=team` in
-`.aperant/config.json` (or run `/apt:setup` and pick `team`) to commit
-them alongside the per-scope `milestones.json` files.
-
-**Q: Why 3 levels and not 4 (`seed → thread → plant → sprout`)?**
-D-01 (see `.aperant/tasks/{this-task}/spec.md` §3): the 4-level GSD
-vocabulary duplicates existing concepts — `thread` is a milestone,
-`plant` is a phase, `sprout` is a subtask. Adding three new words
-required rewriting every `SKILL.md`, every commit prefix convention,
-and every agent prompt — negative ROI. The 3-level version keeps the
-battle-tested vocabulary and only adds a single new word (`seed`).

package/docs/skill-authoring.md

@@ -1,172 +0,0 @@
-# Skill Authoring (C4)
-
-> Author new Aperant skills test-first. Scaffold → structural test → fill in the TODOs.
-
-The framework ships a meta-skill (`apt:author-skill`) and a deterministic CLI
-(`apt-tools author-skill`) that together let authors produce a new skill with
-the canonical SKILL.md shape and a matching structural test in one shot. The
-skill author then fills in the TODO stubs, iterating against the generated test
-until it passes.
-
-This document is the human-readable reference for the canonical SKILL.md
-contract. The single machine-readable source of truth lives at
-[`../src/cli/skill-author/contract.mjs`](../src/cli/skill-author/contract.mjs)
-and the validator at
-[`../src/cli/skill-author/validate.mjs`](../src/cli/skill-author/validate.mjs).
-
-## The test-first authoring flow
-
-```
-1. apt-tools author-skill <slug> --description "..."
-   ↓
-   packages/framework/skills/apt-<slug>/SKILL.md        (stub with TODOs)
-   packages/framework/src/__tests__/apt-<slug>-skill-structure.test.ts
-   ↓
-2. Fill in the TODO stubs in SKILL.md
-   ↓
-3. pnpm --filter @aperant/framework test --run <test-path>
-   ↓
-4. Extend the generated test with skill-specific assertions
-```
-
-The generated test is minimal by design — it pins the contract basics
-(frontmatter name, four required section tags). Skill-specific assertions (task
-directory references, mode flags, template placeholders) are the author's job
-to add as the body stabilizes.
-
-## Canonical SKILL.md contract
-
-Every new SKILL.md authored via this flow MUST match the contract below.
-
-### Frontmatter
-
-The file starts with a YAML frontmatter block delimited by `---` lines.
-
-**Required keys:**
-
-| Key | Type | Rule |
-|-----|------|------|
-| `name` | string | Must match `/^apt:[a-z][a-z0-9-]*$/` — e.g. `apt:foo`, `apt:author-skill` |
-| `description` | string | Non-empty |
-
-**Optional keys (no-op if absent):**
-
-| Key | Type | Use |
-|-----|------|-----|
-| `triggers` | string[] | `/apt:<slug>`, `apt:<slug>` — what the router matches |
-| `argument-hint` | string | Hint text shown to the user |
-| `user-invocable` | boolean | Whether the skill is exposed to the user via `/apt:<slug>` |
-| `allowed-tools` | string | CSV of Claude Code tool names |
-
-### Required body sections
-
-Every SKILL.md MUST contain these four XML-style tag pairs (order-free):
-
-| Tag | Purpose |
-|-----|---------|
-| `<objective>` … `</objective>` | One-paragraph statement of what the skill does and when to use it |
-| `<your_environment>` … `</your_environment>` | Bullet list of file paths, env vars, and tools the skill depends on |
-| `<state_files>` … `</state_files>` | `**Reads:**` / `**Writes:**` sub-sections enumerating every file the skill touches |
-| `<process>` … `</process>` | Numbered-step walkthrough — `## 1. Foo`, `## 2. Bar`, … |
-
-### Soft-required body sections
-
-These emit a **warning** (not an error) when missing:
-
-| Tag | Purpose |
-|-----|---------|
-| `<rationalization>` … `</rationalization>` | Per-skill table of "I'll skip X because Y" patterns the agent might rationalize — and why each rationalization is wrong. See [C1](../../../docs/frameworks/spec-gaps.md#c1). |
-| `<autonomy_interaction>` … `</autonomy_interaction>` | How the skill respects the autonomy level in `.aperant/config.json` — plan-only (0) vs ask-before-destructive (1) vs full auto (2) |
-
-### Process block shape
-
-- At least two numbered step headings (`^## \d+\. `)
-- Numbering monotonically increasing from 1 (gaps or sub-steps like `## 2b.` emit a warning, not an error — apt:design uses them legitimately)
-
-### Rules NOT enforced
-
-The validator is grep-style. It intentionally does not check:
-
-- The exact contents of the process steps
-- Cross-section references (e.g. "as described in step 3")
-- Alignment between frontmatter `name` and `triggers` entries
-- Prose quality inside any section
-
-Extend the generated structural test with skill-specific assertions for
-anything the validator misses.
-
-## Usage
-
-```bash
-# Minimal — uses default description
-node packages/framework/bin/apt-tools.mjs author-skill my-skill
-
-# With a description
-node packages/framework/bin/apt-tools.mjs author-skill my-skill \
-  --description "Does my thing"
-
-# Dry run — prints the paths that would be written, writes nothing
-node packages/framework/bin/apt-tools.mjs author-skill my-skill --dry-run
-
-# Alternate framework root (used by integration tests)
-node packages/framework/bin/apt-tools.mjs author-skill my-skill \
-  --framework-root /tmp/sandbox-framework
-```
-
-Flags:
-
-| Flag | Default | Use |
-|------|---------|-----|
-| `--description <text>` | `TODO: describe the skill` | One-line skill description |
-| `--dry-run` | `false` | Preview without writing |
-| `--framework-root <path>` | shipping `packages/framework/` | Alternate framework root (tests, sandboxes) |
-
-The CLI refuses to overwrite an existing skill directory or structural test
-file. Delete them by hand if you need to restart from scratch.
-
-## What to fill in after scaffolding
-
-The generated SKILL.md has `TODO:` markers in every section. A minimum
-viable skill fills in:
-
-1. **Objective** — one sentence on purpose, one sentence on when to use
-2. **Environment** — concrete file paths, not generic placeholders
-3. **State files** — every file the skill reads AND every file it writes
-4. **Rationalization** — at least one entry if the skill executes destructive actions
-5. **Autonomy interaction** — even a single line ("non-destructive, safe at any level") beats silence
-6. **Process** — replace every TODO step with concrete imperatives, not "think about X"
-
-## Running the generated test
-
-```bash
-pnpm --filter @aperant/framework test --run \
-  packages/framework/src/__tests__/apt-<slug>-skill-structure.test.ts
-```
-
-Re-run after every SKILL.md edit. Extend the test with skill-specific
-assertions once the body is stable — for example:
-
-- `expect(contents).toContain('{task_dir}')` for skills that write to the task dir
-- `expect(contents).toContain('--continue')` for skills that advertise modes
-- `expect(contents).toMatch(/iteration-\d{3}/)` for the mockup-style iteration naming
-
-## Migration note for existing skills
-
-**Existing `apt-*` skills are NOT required to pass `validateSkillMarkdown`.**
-The contract applies to skills authored through this flow. Existing skills
-(apt-design, apt-mockup, apt-plan, apt-execute, …) keep their bespoke
-structural tests as-is.
-
-If you do want to migrate an existing skill to the contract, run
-`validateSkillMarkdown` against its SKILL.md and add the missing sections.
-Do NOT regenerate a skill's structural test from the template — the
-existing tests often encode skill-specific invariants the template-generated
-test cannot know about.
-
-## See also
-
-- [`../skills/apt-author-skill/SKILL.md`](../skills/apt-author-skill/SKILL.md) — the meta-skill that wraps the CLI
-- [`../src/cli/skill-author/contract.mjs`](../src/cli/skill-author/contract.mjs) — the machine-readable contract
-- [`../src/cli/skill-author/validate.mjs`](../src/cli/skill-author/validate.mjs) — `validateSkillMarkdown`
-- [`../src/cli/skill-author/scaffold.mjs`](../src/cli/skill-author/scaffold.mjs) — the scaffold generator
-- [spec-gaps.md C4](../../../docs/frameworks/spec-gaps.md#c4) — motivation (vs Superpowers)

package/docs/standalone.md

@@ -1,168 +0,0 @@
-# Zero-Orchestration Standards Discovery (C20)
-
-**Status:** v1 shipped.
-
-The standalone module exposes a read-only view of every "standards" artifact
-Aperant collects — the project constitution (`AGENTS.md`), an optional resolved
-profile chain, the feature registry, design tokens, and design taste — as a
-single bundle that any downstream orchestrator (Continue, Aider, a custom
-agent, a CI step) can consume without opting into the full router / skill /
-pipeline surface.
-
-This closes spec-gap C20 (`docs/frameworks/spec-gaps.md#c20`).
-
-## Why this exists
-
-Teams who have already standardized on another AI orchestrator still benefit
-from Aperant's authored artifacts: the AGENTS.md principle extractor, the
-profile cascade, and the feature registry are all pure read paths. The
-standalone surface gives those teams a stable, side-effect-free entry point
-so they can:
-
-- Feed AGENTS.md principles into their own system prompts.
-- Merge per-team profile obligations with AGENTS.md.
-- Enumerate wired / stubbed features before generating tests.
-- Share design tokens and design-taste text with a design-system agent.
-
-No orchestration, no writes, no skill invocation — just the standards.
-
-## Programmatic usage
-
-```ts
-import { discoverStandards } from '@aperant/framework/standalone'
-
-const bundle = discoverStandards(process.cwd(), { profile: 'team-platform' })
-
-if (bundle.ok) {
-  // bundle.constitution.principles is AGENTS.md principles, with the profile
-  // cascade's obligations folded in (AGENTS.md wins on title collision).
-  for (const p of bundle.constitution.principles) {
-    console.log(p.severity, p.title)
-  }
-  // bundle.feature_registry.areas is strictly schema-validated.
-  // bundle.feature_registry.invalid holds any files that failed parse/schema.
-} else {
-  console.error('standards discovery failed:', bundle.error)
-}
-```
-
-The function is **pure**: it never throws, never calls `process.exit`, and
-never writes to disk or to `.aperant/state.json`. Missing sections degrade to
-`null` instead of failing the whole call. The one exception is an explicit
-`opts.profile` that cannot be resolved — that is a caller contract violation,
-not a missing section, and is returned as a whole-bundle failure envelope.
-
-## CLI usage
-
-```bash
-# JSON envelope (default in a pipe, or when --json is explicit).
-apt-tools standards . --json | jq
-
-# Merge a profile's obligations into the constitution.
-apt-tools standards . --profile team-platform
-
-# Human-readable summary (only when stdout is a TTY and --json not set).
-apt-tools standards .
-```
-
-In a pipe (no TTY) the CLI always emits JSON. Passing `--no-color` also forces
-JSON. A missing project directory or an invalid `--profile` exits with status
-`1` and prints `{status: "fail", command: "standards", reason, ...}`.
-
-## Bundle shape
-
-```ts
-type StandardsBundle =
-  | {
-      ok: true
-      project_dir: string
-      constitution: {
-        source: string | null     // "AGENTS.md" | "agents.md" | "CLAUDE.md" | "claude.md" | null
-        count: number
-        principles: Principle[]
-      }
-      profile: {
-        name: string | null
-        chain: string[]           // [root, …, target]
-        resolved: Record<string, unknown> | null
-      } | null                    // null when opts.profile not requested
-      feature_registry: {
-        count: number
-        areas: FeatureRegistryArea[]
-        invalid: FeatureRegistryInvalid[]
-      } | null                    // null when .aperant/features/ is absent
-      design_tokens: Record<string, unknown> | null
-      design_taste: { raw: string } | null
-    }
-  | {
-      ok: false
-      error: string
-      project_dir: string
-    }
-
-type Principle = {
-  id: string
-  title: string
-  text: string
-  source: { section: string; line: number }
-  keywords: string[]
-  severity: 'must' | 'should' | 'never' | 'principle' | 'obligation' | string
-}
-
-type FeatureRegistryInvalid = {
-  path: string
-  errors: { path: string; message: string }[]
-}
-```
-
-The CLI JSON envelope wraps the bundle with `status` and `command`:
-
-```jsonc
-{
-  "status": "ok",
-  "command": "standards",
-  "project_dir": "/abs/path",
-  "constitution": { ... },
-  "profile": { ... } /* or null */,
-  "feature_registry": { ... } /* or null */,
-  "design_tokens": { ... } /* or null */,
-  "design_taste": { "raw": "…" } /* or null */
-}
-```
-
-Failure envelope (invalid profile, missing project dir):
-
-```jsonc
-{
-  "status": "fail",
-  "command": "standards",
-  "reason": "profile not found: ghost"
-}
-```
-
-## Worktree support
-
-The standalone module uses the same coordination-store shared-root lookup as
-every other apt-tools command, so running it from inside a git worktree
-correctly resolves `.aperant/` at the main repo root. `AGENTS.md` is read
-from the shared root too.
-
-## What is explicitly out of scope
-
-- **No orchestration.** The module never spawns planners, executors,
-  reviewers, or any other skill.
-- **No writes.** No mutation of `.aperant/state.json`, no new files, no
-  side effects of any kind.
-- **No skill invocation.** This is not a hidden `apt-tools run` — it is a
-  data read.
-- **No caching.** Every call reads fresh from the filesystem. Caching is
-  the consumer's concern.
-- **No profile auto-discovery.** `opts.profile` is always explicit. Callers
-  that want to walk every profile can use the `apt-tools profile list` CLI.
-- **No YAML schema for `taste.yaml`.** C26 v1 ships a raw-text passthrough —
-  the consumer picks its own parser.
-- **No feature-registry rollup stats.** Consumers get the raw validated
-  areas plus any files that failed schema check. Wired% / stubbed% is a
-  downstream computation.
-- **No design-tokens schema enforcement on read.** C27 validates on write;
-  the standalone surface is a passthrough.