@aperant/framework 0.6.2

package/docs/seeds.md

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

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

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