@iceinvein/agent-skills 0.21.4 → 0.22.0

package/skills/scope-estimate/references/deliverables.md

@@ -0,0 +1,60 @@
+# Architecture and proposal checks
+
+## Architecture pages
+
+Each page is Markdown first, HTML generated from it.
+
+- **`architecture/current-architecture.md`:** runtime, background processing,
+  delivery and reference data, each its own Mermaid diagram, plus a numbered
+  table of the problems the architecture causes: hosting, data storage,
+  processing harness, delivery, reference data and edge security. Application
+  defects belong in the capability map, not here.
+- **`architecture/target-architecture.md`:** the same views for the new
+  platform, a sequence diagram for the main flow with numbered steps, and a
+  "what changes from today" table keyed to the problems.
+- **`architecture/<name>-architecture-comparison.md`:** side by side pairs of
+  the same view, glance cards for the headline differences, and the problems
+  table. Its job is to show the target is stronger and simpler. Say under the
+  table that these are the architecture problems only, with the count of
+  capability changes and risk findings and links to them, so the page never
+  reads as the whole job.
+- **`architecture/design-<topic>.md`** for each fork with the most
+  requirements behind it (typically identity, audit, machine identity): the
+  options, the decision or the Pending recommendation, the gaps still open.
+
+Mermaid in local HTML: load it from a pinned CDN version, use the base theme
+with colours from CSS variables, and show the diagram source when offline.
+Wide diagrams become unreadable, and in a side by side pair every diagram is
+half width: keep to about three nodes per rank, shorten edge labels, move
+detail into bullets, or split one diagram into two. `direction` inside a
+subgraph is ignored once edges link to nodes inside it, so link subgraphs to
+each other instead.
+
+## Reviewing a proposal
+
+Write `build-plan/<vendor>-proposal-review.md`. Judge the proposal against how
+the team builds (platform, tooling, delivery, identity, security services,
+compliance claims, cost gaps), as numbered judgements: replace, change, drop,
+correct, missing. List what to keep and the questions it raises for the
+client. The proposal's own figures may be quoted with a page reference; our
+figures come from `schedule.json` and the capability map.
+
+Always check the framing: count the scheduled requirements in areas the
+proposal never mentions. A list of hosting or architecture problems presented
+as the scope undersells an application rebuild. When the proposal quotes our
+estimate, also check every figure against the latest schedule output and the
+team shape it assumes.
+
+An editable document (Word, Google Docs) is changed only in a copy, with
+tracked changes under the user's name; commercial calls (fees, role titles,
+rates) get comments, not edits. A PDF or other fixed document gets the review
+file only.
+
+## Keeping it in sync
+
+A decision changes requirements, which changes packages, which changes the
+schedule, which changes every page quoting a number. After each decision:
+mark it Decided in `decisions.md`, update the requirement files, re-run the
+scheduler, then update the slices page, the capability map's open questions
+and risks, the architecture pages and any proposal review. Search the
+engagement folder for the old figures before saying it is done.

package/skills/scope-estimate/references/requirements.md

@@ -0,0 +1,104 @@
+# Functional requirements
+
+## Fix the vocabulary first
+
+Area agents run in parallel and reference each other, so before dispatching
+write the first draft of `build-plan/plan.json` (from
+`templates/plan.example.json`) with:
+
+- **`dependsOn.layers`:** every layer key the requirements may use, each with
+  an empty list for now. Use the register's layer set.
+- **`aliases`:** the shorthand agents may write in `Depends on` (`Auth`, `DB`,
+  `Contracts`, `Storage`, `Queue`), each mapped to the foundation capability
+  that will own it. Narrow targets beat broad ones.
+- **Foundation capability ids:** `FD-REPO`, `FD-CI`, `FD-CON`, `FD-API`,
+  `FD-DB`, `FD-AUTH`, `FD-WEB`, `FD-INF`, `FD-SEC`, `FD-OBS`, plus one for any
+  domain content package. List which register rows foundations own outright
+  (platform infrastructure, auth plumbing) so no area restates them.
+
+Put the same lists in the shared brief, `scratch/requirements-brief.md`.
+
+## Agents
+
+One agent per area: a **foundations** file plus one per product area of the
+register. Brief each with the shared brief above, its register rows and
+appendix, the non-functional requirements, `decisions.md`, the rules and the
+table format below.
+
+Disposition rules:
+
+- **Carry:** today's behaviour, with exact values.
+- **Fix:** the intended behaviour, naming the defect it corrects.
+- **Redesign:** the new shape.
+- **New:** built to the non-functional requirements.
+- **Undecided, Optional:** written as if the answer were yes, self-contained so
+  the whole capability can be gated in phase 4.
+- **Drop:** no requirements; a short map of what replaces each job it did.
+
+**Granularity drives the estimate,** so every agent cuts the same way: one
+requirement is one behaviour that one test checks, at the level a reviewer
+would accept or reject. Values, labels, defaults and copy that belong to one
+behaviour go in that requirement (list them), not one row each; two
+behaviours that fail independently are two rows. Aim for most capabilities
+landing between 3 and 10 requirements. After the agents, compare each file's
+share of S rows and its requirements per capability; a file well off the
+others was cut differently, so re-brief it before moving on. Blind runs of the
+same system with an unstated cut produced 537 and 984 requirements.
+
+New forks found by parallel agents go in their file's findings as
+`D-new: <question>`; the controller numbers them into `decisions.md` once all
+agents finish. Register rows that foundations own keep their register ids as
+capability headings in `foundations.md` (`### IA-01 ...`), so references to
+them still resolve.
+
+A value no source gives (a URL lifetime, a retry count) is written with
+`placeholder` in Notes. A new library or pattern the requirement implies (a
+charting library, a service worker) is an engineering fork: a `D-new` in the
+file's findings and `see D-xx` in Notes, never `Decision:`. Work several areas need that nobody owns (a background
+job runner) becomes a new foundation capability; tell the controller rather
+than writing it three times.
+
+## Format
+
+One `###` heading per capability, then its table:
+
+```
+### RC-01 Session setup (Carry)
+
+| FR | Requirement | Actor | Layers | Size | Depends on | Source | Notes |
+|---|---|---|---|---|---|---|---|
+| RC-01.1 | The API shall return ... | System | api, db | M | Auth, Contracts, DB | A §1.1 | Decision: who may record |
+```
+
+- **FR:** `<capability>.<n>`, unique across all files.
+- **Requirement:** one observable "shall" statement a test could check.
+- **Layers:** comma-separated from `dependsOn.layers`.
+- **Size:** `S` under half a day, `M` about a day, `L` two to three days, for
+  an engineer working with agents.
+- **Depends on:** requirement ids, capability ids, a range
+  (`FD-DB.2 to FD-DB.9`), or an alias. `-` for none.
+- **Source:** appendix and section.
+- **Notes:** `Decision:` (with the colon) marks a client question, and only
+  that does; `Decision: see D-04` points at a bigger one. An engineering fork
+  is `see D-07` without the marker (see `SKILL.md`, Decisions).
+
+Parser rules: only tables whose header starts with `| FR |` are read, so other
+tables can sit in the same file. Cells are separated by a space, a pipe and a
+space (`| a | b |`, not `|a|b|`). A literal `|` inside a cell is written `\|`.
+Every row has exactly eight cells.
+
+## After the agents
+
+1. **Check.** Run the scheduler against the draft plan: one slice per
+   requirements file listing its capabilities, no `foundations`, empty
+   `dependsOn` lists, and aliases pointing at capability ids (phase 4 remaps
+   them to foundation packages). Every capability becomes one package and
+   cross references become links, so it checks ids, sizes, row shape, layers
+   and unresolved dependencies without any cycles. Fix every problem it names.
+2. **Merge overlaps to one owner.** Where two files describe the same work,
+   keep it in the owning file and trim the other to its difference. Totals
+   then count each behaviour once.
+3. **Write back.** Copy new findings and questions into the capability map
+   (section 10 and open questions), new forks into `decisions.md`, and apply
+   register corrections (status, disposition, layers, splits) directly,
+   re-running the map's counting script.

package/skills/scope-estimate/references/schedule.md

@@ -0,0 +1,138 @@
+# Slices, packages and the schedule
+
+## Slices
+
+A slice is a feature one engineer owns end to end: schema, route with its
+permission check, UI, tests and the infrastructure it needs. With generalist
+engineers nobody is "the frontend person"; slices rotate. A scheduled slice
+is 2 to 14 planning days, and its requirement tables are its spec card.
+
+`phase` groups slices for reading; the scheduler ignores it. A package may sit
+in a slice other than its capability's (a guard against copied files belongs
+with CI), and counts toward the slice it sits in, but never across the gated
+line: the scheduler refuses a scheduled package claiming gated work, or the
+reverse. Contracts first means operations slices start as
+soon as their foundations land, long before the product apps finish; say in
+the document when they actually start, from the schedule.
+
+- **0 Foundations:** monorepo and local dev stack, CI, contracts and API
+  skeleton, data model, sign-in, web shell, domain content package, dev
+  infrastructure and security baseline, logging.
+- **1 Platform core:** tenancy and permissions, user management, account
+  security, the core entities, consent or equivalent, storage, audit.
+- **2 Product apps:** the user-facing apps and background workers.
+- **3 Environments and operations:** promotion, monitoring, backup.
+
+**Gated slices** hold every Undecided and Optional capability, one slice per
+client decision, with `"gated": true`. They are counted and totalled, never
+scheduled, and the size rule does not apply. A scheduled package may not wait
+on a gated one; the scheduler refuses it.
+
+Each slice gets a one-sentence goal stating what works when it is done. For
+"depends on" per slice in the document, roll up package dependencies; two
+slices can each have a package waiting on the other without a cycle.
+
+## Work packages
+
+- **Foundations** are split by hand into small packages in `foundations`,
+  each a handful of related requirements (`F8f Auth configuration and VPC
+  endpoints`). Work the sources forgot (often a local dev stack) gets
+  `assumedDays` and is reported as an assumption. Scope that nobody has agreed
+  is not given an assumed size; list it under what the estimate leaves out.
+- **Products** need no listing: every requirement not claimed by a package
+  becomes one package per capability. List a product package in `products`
+  only to split a large capability (over about 5 planning days, or one that
+  ends the critical chain) or to give it a real wait.
+- **Contracts first.** A product package waits only on the foundation
+  packages it uses: `dependsOn.product` for all, plus `dependsOn.layers` by
+  the layers its requirements touch, plus any foundation its requirements
+  name. A reference to another product is an **integration link**, checked
+  when both sides land, never a blocker.
+- **Real product waits** are for data, not contracts: a pipeline stage that
+  needs the previous stage's output to build or test against. Give it
+  `after` in `products`, and say in the document why a mock or fixture
+  cannot stand in.
+- **What a dependency means:** needed to build and test locally, not needed
+  to deploy. `dependsOn.product` is what every product needs to run locally
+  (the local dev stack, the API and web skeletons); deploy infrastructure is
+  a dependency of the environment slices, not of every product.
+- **Layers:** every layer used in a requirement must be a key in
+  `dependsOn.layers`, even with an empty list.
+- **Aliases** from the phase 3 draft point at capability ids; remap each to
+  the foundation package that owns the work. Keys match regardless of case. Keep them narrow: if a
+  requirement inside package A uses an alias that also names package B, and B
+  depends on A, the two wait on each other. The scheduler refuses the cycle
+  and names the requirement behind each edge.
+- **Unresolved dependencies** are listed under "Dependencies that resolved to
+  nothing". Fix the requirement or add an alias; each is a missing edge.
+
+## Rates and team
+
+`rates` are days per requirement by size. A starting point from a past
+engagement:
+
+| Rate | S | M | L | Meaning |
+|---|---|---|---|---|
+| fast | 0.1 | 0.4 | 1.0 | agents do most of it, little rework |
+| plan | 0.25 | 0.75 | 2.0 | the planning case |
+| floor | 0.5 | 1.0 | 2.5 | barely faster than without agents |
+
+Lanes are engineers x worktrees, and each placed package in `schedule.json`
+names its engineer and worktree. N worktrees per engineer holds only while
+the engineer's own time on a package (spec, steering, review, checking in
+dev) stays at or under about 1/N of its planning time; say so next to the
+headline, and show the one-worktree column as the fallback.
+
+The schedule is list scheduling: the lane that frees first takes the package
+that can start now with the longest chain behind it. A credible order, not an
+optimum. It does not keep one engineer's worktrees off the same files, and it
+does not follow "finish your slice first", so real lanes will follow slices
+more closely than the printed order; say both.
+
+## Rules that go in the slices document
+
+- Integration is continuous: whoever merges the second side of a link runs
+  the flow end to end in dev that day.
+- Contracts change through one PR that updates both sides.
+- Pick up the oldest ready package in your slice before starting a new slice.
+- One engineer's worktrees never touch the same migration or contract at once;
+  pair packages from different slices or layers.
+- Review is a second engineer, and reviews scale with worktrees.
+- Parts agents cannot check (browser devices, sign-in on real devices, domain
+  sign-off) carry more people time than their size suggests.
+
+## Calibration
+
+Nobody knows the team's real rate with agents until it is measured. Plan a
+two-week calibration on the first foundation slices: record actual days per
+S, M and L, and the engineer's own hours per package. At the end, put the
+measured rates into `plan.json`, re-run, and commit to a date only then. Start
+anything that waits on people in week 1: client decisions, domain sign-off of
+the content package, account and landing-zone access.
+
+## Slices document outline
+
+1. Purpose, scope (build only unless agreed otherwise), sources.
+2. Summary: totals, gated totals, the engineers x worktrees table at fast,
+   planning and floor, the headline, the worktree condition.
+3. How the requirements were produced, checks done and not done.
+4. How slices work with generalist engineers.
+5. Slice catalogue by phase: FRs (S/M/L), decisions, depends on, plan days.
+6. Work packages: what "blocked by" means, real product waits and why, the
+   effect on the critical chain, the rules above, the package catalogue.
+7. Schedule: lane order for the headline team, things to start early,
+   calibration.
+8. Findings from the requirements work.
+9. What this does not cover: verification, test cycles, pen test, UAT,
+   gated slices (with their total), scope with no requirement yet, time away
+   from building (spec cards, decisions, reviews, meetings), leave and
+   ramp-up.
+
+## HTML page
+
+Engineers, worktrees and rate as selectors over the `schedules` array from
+`schedule.json`, embedded in the page at build time (a page opened from disk
+cannot fetch it). A Gantt per engineer and worktree whose scale ends at the
+total (no empty tail); slices always visible as articles listing their
+packages, with only the requirement tables collapsed; labels hidden on bars
+too narrow to hold them.

package/skills/scope-estimate/scripts/__tests__/schedule.test.ts

@@ -0,0 +1,366 @@
+import { expect, test } from 'bun:test'
+import { estimate, parseRequirements, type Plan } from '../schedule.ts'
+
+const HEADER = `| FR | Requirement | Actor | Layers | Size | Depends on | Source | Notes |
+|---|---|---|---|---|---|---|---|`
+
+const REQUIREMENTS = `# Area
+
+### FD-DB Data model (New)
+
+${HEADER}
+| FD-DB.1 | Migrations shall create the core tables. | System | db | M | - | C §1 | |
+| FD-DB.2 | Seed data shall be synthetic only. | System | db | S | FD-DB.1 | C §2 | Decision: seed shape |
+
+### PM-01 Participants (Carry)
+
+${HEADER}
+| PM-01.1 | The API shall create a participant. | Clinician | api, db | L | FD-DB.1, CO-01 | C §3 | |
+| PM-01.2 | The web app shall list participants. | Clinician | web | S | PM-01.1 | A §1 | |
+
+### CO-01 Consent (New)
+
+${HEADER}
+| CO-01.1 | The API shall send a consent request. | System | api | M | Auth | C §4 | |
+
+### AA-01 Acoustic analysis (Undecided)
+
+${HEADER}
+| AA-01.1 | The worker shall run acoustic analysis. | System | worker | S | - | D §1 | Decision: in pilot? |
+`
+
+// Whole-day rates so every expected value below can be worked out by hand.
+const plan = (overrides: Partial<Plan> = {}): Plan => ({
+  daysPerWeek: 5,
+  rates: {
+    fast: { S: 1, M: 2, L: 4 },
+    plan: { S: 1, M: 2, L: 4 },
+    floor: { S: 1, M: 2, L: 4 },
+  },
+  team: { engineers: [1, 2], worktrees: [1], headline: { engineers: 2, worktrees: 1 } },
+  slices: [
+    { id: 'F', name: 'Foundations', goal: 'Schema exists', phase: 0, capabilities: ['FD-DB'] },
+    { id: 'P', name: 'Participants', goal: 'Participants exist', phase: 1, capabilities: ['PM-01', 'CO-01'] },
+    { id: 'D', name: 'Acoustic', goal: 'Only if wanted', phase: 1, capabilities: ['AA-01'], gated: true },
+  ],
+  foundations: [
+    { id: 'F1', slice: 'F', name: 'Migrations', members: ['FD-DB.1'] },
+    { id: 'F2', slice: 'F', name: 'Seed data', members: ['FD-DB.2'] },
+  ],
+  dependsOn: { foundation: [], product: [], layers: { db: ['F1'], web: ['F2'], api: [], worker: [] } },
+  aliases: { auth: ['F1'] },
+  ...overrides,
+})
+
+const reqs = () => parseRequirements(REQUIREMENTS, 'area.md')
+
+test('parsed requirements carry their capability, size, layers and decision flag', () => {
+  const pm = reqs().find((r) => r.id === 'PM-01.1')
+  expect(pm).toEqual({
+    id: 'PM-01.1',
+    file: 'area.md',
+    capability: 'PM-01',
+    disposition: 'Carry',
+    size: 'L',
+    layers: ['api', 'db'],
+    depends: ['FD-DB.1', 'CO-01'],
+    decision: false,
+  })
+  expect(reqs().find((r) => r.id === 'FD-DB.2')?.decision).toBe(true)
+})
+
+test('only a Decision: marker flags a requirement, not prose that mentions a decision', () => {
+  const md = `### X-01 Thing (New)\n\n${HEADER}\n| X-01.1 | A. | System | api | S | - | s | Decision: as X-02.1 |\n| X-01.2 | B. | System | api | S | - | s | Built per Decision D-05 |\n`
+  expect(parseRequirements(md, 'x.md').map((r) => r.decision)).toEqual([true, false])
+})
+
+test('an escaped pipe stays inside its cell', () => {
+  const md = `### X-01 Thing (New)\n\n${HEADER}\n| X-01.1 | Shows a \\| b. | System | api | S | - | s | |\n`
+  expect(parseRequirements(md, 'x.md')).toHaveLength(1)
+})
+
+test('a requirement row with the wrong number of cells is rejected with its location', () => {
+  const broken = `### X-01 Thing (New)\n\n${HEADER}\n| X-01.1 | Too few cells | System | S |\n`
+  expect(() => parseRequirements(broken, 'x.md')).toThrow('x.md:5')
+})
+
+test('tables that are not requirement tables are ignored', () => {
+  const mixed = `### X-01 Thing (Drop)\n\n| Job today | Replaced by |\n|---|---|\n| Create users | IA-01.2 |\n\n${HEADER}\n| X-01.1 | A thing. | System | api | S | - | s | |\n`
+  expect(parseRequirements(mixed, 'x.md').map((r) => r.id)).toEqual(['X-01.1'])
+})
+
+test('a size other than S, M or L is rejected', () => {
+  const broken = `### X-01 Thing (New)\n\n${HEADER}\n| X-01.1 | A thing. | System | api | XL | - | s | |\n`
+  expect(() => parseRequirements(broken, 'x.md')).toThrow('XL')
+})
+
+test('one lane builds every scheduled package back to back', () => {
+  // F1 2 + F2 1 + PM-01 5 + CO-01 2 = 10 days = 2 weeks; AA-01 is gated and left out.
+  const report = estimate(reqs(), plan())
+  expect(report.schedules.find((s) => s.engineers === 1 && s.rate === 'plan')?.weeks).toBe(2)
+})
+
+test('two lanes finish when the longest dependency chain does', () => {
+  // F1 (0-2) > F2 (2-3) > PM-01 (3-8), with CO-01 (2-4) on the other lane: 8 days.
+  const report = estimate(reqs(), plan())
+  expect(report.schedules.find((s) => s.engineers === 2 && s.rate === 'plan')?.weeks).toBe(1.6)
+  expect(report.criticalChain).toEqual({ ids: ['F1', 'F2', 'PM-01'], weeks: 1.6 })
+})
+
+test('a product package is blocked by the foundations its layers use, not by other products', () => {
+  const report = estimate(reqs(), plan())
+  const pm = report.packages.find((p) => p.id === 'PM-01')
+  expect(pm?.deps).toEqual(['F1', 'F2'])
+  expect(pm?.integrationLinks).toEqual(['CO-01'])
+})
+
+test('a dependency named by alias resolves to the packages it stands for', () => {
+  const report = estimate(reqs(), plan())
+  expect(report.packages.find((p) => p.id === 'CO-01')?.deps).toEqual(['F1'])
+})
+
+test('worktrees multiply the lanes each engineer runs', () => {
+  const team = { engineers: [1], worktrees: [2], headline: { engineers: 1, worktrees: 2 } }
+  const report = estimate(reqs(), plan({ team }))
+  expect(report.schedules.find((s) => s.rate === 'plan')?.weeks).toBe(1.6)
+})
+
+test('a foundation package with an assumed size is scheduled at that size', () => {
+  const foundations = [
+    { id: 'F0', slice: 'F', name: 'Local dev stack', members: [], assumedDays: { fast: 3, plan: 3, floor: 3 } },
+    { id: 'F1', slice: 'F', name: 'Migrations', members: ['FD-DB.1'] },
+    { id: 'F2', slice: 'F', name: 'Seed data', members: ['FD-DB.2'] },
+  ]
+  const report = estimate(reqs(), plan({ foundations }))
+  expect(report.schedules.find((s) => s.engineers === 1 && s.rate === 'plan')?.weeks).toBe(2.6)
+})
+
+test('a dependency cycle between foundation packages is refused and named', () => {
+  const foundations = [
+    { id: 'F1', slice: 'F', name: 'Migrations', members: ['FD-DB.1'], after: ['F2'] },
+    { id: 'F2', slice: 'F', name: 'Seed data', members: ['FD-DB.2'] },
+  ]
+  expect(() => estimate(reqs(), plan({ foundations }))).toThrow('F1 waits on F2 waits on F1')
+})
+
+test('a dependency cycle names the requirement behind each edge', () => {
+  const foundations = [
+    { id: 'F1', slice: 'F', name: 'Migrations', members: ['FD-DB.1'], after: ['F2'] },
+    { id: 'F2', slice: 'F', name: 'Seed data', members: ['FD-DB.2'] },
+  ]
+  expect(() => estimate(reqs(), plan({ foundations }))).toThrow('F2 waits on F1: FD-DB.2 depends on FD-DB.1')
+})
+
+test('a capability that belongs to no slice is refused', () => {
+  const slices = plan().slices.filter((s) => s.id !== 'D')
+  expect(() => estimate(reqs(), plan({ slices }))).toThrow('AA-01')
+})
+
+test('a requirement claimed by two foundation packages is refused', () => {
+  const foundations = [
+    { id: 'F1', slice: 'F', name: 'Migrations', members: ['FD-DB.1', 'FD-DB.2'] },
+    { id: 'F2', slice: 'F', name: 'Seed data', members: ['FD-DB.2'] },
+  ]
+  expect(() => estimate(reqs(), plan({ foundations }))).toThrow('FD-DB.2')
+})
+
+test('a dependency that names nothing known is reported, not dropped silently', () => {
+  const extra = REQUIREMENTS.replace('| Auth |', '| Auth, Billing |')
+  const report = estimate(parseRequirements(extra, 'area.md'), plan())
+  expect(report.unresolved).toEqual({ Billing: 1 })
+})
+
+test('a scheduled package that waits on a gated one is refused and named', () => {
+  const slices = plan().slices.map((s) => (s.id === 'F' ? { ...s, gated: true } : s))
+  expect(() => estimate(reqs(), plan({ slices }))).toThrow('PM-01 waits on F1, which is gated')
+})
+
+test('two packages with the same id are refused', () => {
+  const foundations = [
+    { id: 'F1', slice: 'F', name: 'Migrations', members: ['FD-DB.1'] },
+    { id: 'F1', slice: 'F', name: 'Seed data', members: ['FD-DB.2'] },
+  ]
+  expect(() => estimate(reqs(), plan({ foundations }))).toThrow('package id F1 is used twice')
+})
+
+test('a range waits on every package that owns a requirement in it', () => {
+  const md = REQUIREMENTS.replace('| Auth |', '| FD-DB.1 to FD-DB.2 |')
+  expect(estimate(parseRequirements(md, 'area.md'), plan()).packages.find((p) => p.id === 'CO-01')?.deps).toEqual(['F1', 'F2'])
+})
+
+test('a range that names no known requirement is reported', () => {
+  const md = REQUIREMENTS.replace('| Auth |', '| ZZ-01.1 to ZZ-01.3 |')
+  expect(estimate(parseRequirements(md, 'area.md'), plan()).unresolved).toEqual({ 'ZZ-01.1 to ZZ-01.3': 1 })
+})
+
+test('a misspelled requirement id is reported rather than widened to its capability', () => {
+  const md = REQUIREMENTS.replace('| Auth |', '| FD-DB.9 |')
+  const report = estimate(parseRequirements(md, 'area.md'), plan())
+  expect(report.unresolved).toEqual({ 'FD-DB.9': 1 })
+  expect(report.packages.find((p) => p.id === 'CO-01')?.deps).toEqual([])
+})
+
+test('a bare capability id waits on every package holding that capability', () => {
+  const md = REQUIREMENTS.replace('| Auth |', '| FD-DB |')
+  expect(estimate(parseRequirements(md, 'area.md'), plan()).packages.find((p) => p.id === 'CO-01')?.deps).toEqual(['F1', 'F2'])
+})
+
+test('a layer the plan does not declare is refused', () => {
+  const dependsOn = { foundation: [], product: [], layers: { db: ['F1'], web: ['F2'] } }
+  expect(() => estimate(reqs(), plan({ dependsOn }))).toThrow('layer api')
+})
+
+test('alias keys match whatever their case', () => {
+  const report = estimate(reqs(), plan({ aliases: { Auth: ['F1'] } }))
+  expect(report.packages.find((p) => p.id === 'CO-01')?.deps).toEqual(['F1'])
+})
+
+test('a table padded by a formatter is still read', () => {
+  const md = `### X-01 Thing (New)\n\n| FR     | Requirement | Actor | Layers | Size | Depends on | Source | Notes |\n| ------ | --- | :--- | --- | --- | --- | --- | --- |\n| X-01.1 | A thing. | System | api | S | - | s | |\n`
+  expect(parseRequirements(md, 'x.md').map((r) => r.id)).toEqual(['X-01.1'])
+})
+
+test('a capability heading without a title still starts a new capability', () => {
+  const md = `### X-01 Thing (New)\n\n${HEADER}\n| X-01.1 | A. | System | api | S | - | s | |\n\n### Y-01\n\n${HEADER}\n| Y-01.1 | B. | System | api | S | - | s | |\n`
+  expect(parseRequirements(md, 'x.md').map((r) => r.capability)).toEqual(['X-01', 'Y-01'])
+})
+
+test('a plan with nothing left to schedule is refused', () => {
+  const slices = plan().slices.map((s) => ({ ...s, gated: true }))
+  expect(() => estimate(reqs(), plan({ slices }))).toThrow('nothing to schedule')
+})
+
+test('every team combination carries its own lane order', () => {
+  const report = estimate(reqs(), plan())
+  const two = report.schedules.find((s) => s.engineers === 2 && s.rate === 'plan')
+  expect(two?.order.map((o) => [o.id, o.engineer, o.startWeek, o.endWeek])).toEqual([
+    ['F1', 1, 0, 0.4],
+    ['F2', 2, 0.4, 0.6],
+    ['CO-01', 1, 0.4, 0.8],
+    ['PM-01', 2, 0.6, 1.6],
+  ])
+})
+
+test('slices report their requirement counts and planning days, gated ones marked', () => {
+  const report = estimate(reqs(), plan())
+  expect(report.slices).toEqual([
+    { id: 'F', frs: 2, sizes: { S: 1, M: 1, L: 0 }, decisions: 1, planDays: 3, gated: false },
+    { id: 'P', frs: 3, sizes: { S: 1, M: 1, L: 1 }, decisions: 0, planDays: 7, gated: false },
+    { id: 'D', frs: 1, sizes: { S: 1, M: 0, L: 0 }, decisions: 1, planDays: 1, gated: true },
+  ])
+})
+
+test('a headline team outside the team ranges is refused', () => {
+  const team = { engineers: [2], worktrees: [1], headline: { engineers: 2, worktrees: 3 } }
+  expect(() => estimate(reqs(), plan({ team }))).toThrow('headline 2 x 3')
+})
+
+test('a product package can wait on another product when the plan says so', () => {
+  const products = [{ id: 'PM-01', slice: 'P', name: 'Participants', members: ['PM-01'], after: ['CO-01'] }]
+  const report = estimate(reqs(), plan({ products }))
+  expect(report.packages.find((p) => p.id === 'PM-01')?.deps).toEqual(['CO-01', 'F1', 'F2'])
+  // F1 (0-2), CO-01 (2-4) and F2 (2-3) in parallel, then PM-01 (4-9): 9 days.
+  expect(report.schedules.find((s) => s.engineers === 2 && s.rate === 'plan')?.weeks).toBe(1.8)
+})
+
+test('a large product capability can be split into packages', () => {
+  const products = [
+    { id: 'PM-01a', slice: 'P', name: 'Create', members: ['PM-01.1'] },
+    { id: 'PM-01b', slice: 'P', name: 'List', members: ['PM-01.2'], after: ['PM-01a'] },
+  ]
+  const report = estimate(reqs(), plan({ products }))
+  expect(report.packages.filter((p) => p.slice === 'P').map((p) => [p.id, p.days.plan])).toEqual([
+    ['PM-01a', 4],
+    ['PM-01b', 1],
+    ['CO-01', 2],
+  ])
+})
+
+test('gated work is totalled so the cost of each yes is visible', () => {
+  expect(estimate(reqs(), plan()).gated).toEqual({ requirements: 1, planDays: 1 })
+})
+
+test('each placed package names its engineer and worktree', () => {
+  const team = { engineers: [1], worktrees: [2], headline: { engineers: 1, worktrees: 2 } }
+  const order = estimate(reqs(), plan({ team })).schedules.find((s) => s.rate === 'plan')?.order
+  expect(order?.map((o) => [o.id, o.engineer, o.worktree])).toEqual([
+    ['F1', 1, 1],
+    ['F2', 1, 2],
+    ['CO-01', 1, 1],
+    ['PM-01', 1, 2],
+  ])
+})
+
+test('a scheduled package that references gated work is refused, even as an integration link', () => {
+  const md = REQUIREMENTS.replace('| Auth |', '| Auth, AA-01 |')
+  expect(() => estimate(parseRequirements(md, 'area.md'), plan())).toThrow('CO-01 references AA-01, which is gated')
+})
+
+test('package totals are in the report, not only in the printed summary', () => {
+  // Scheduled packages: F1 2, F2 1, PM-01 5, CO-01 2 days; PM-01 links to CO-01.
+  expect(estimate(reqs(), plan()).totals).toEqual({ planDays: 10, medianPlanDays: 2, largestPlanDays: 5, integrationLinks: 1 })
+})
+
+test('a scheduled package may not claim requirements from a gated slice', () => {
+  const products = [{ id: 'AA-01x', slice: 'P', name: 'Acoustic', members: ['AA-01'] }]
+  expect(() => estimate(reqs(), plan({ products }))).toThrow('AA-01x is scheduled but claims AA-01.1, whose slice D is gated')
+})
+
+test('a package placed in another slice counts toward the slice it is placed in', () => {
+  const foundations = [
+    { id: 'F1', slice: 'F', name: 'Migrations', members: ['FD-DB.1'] },
+    { id: 'F2', slice: 'P', name: 'Seed data', members: ['FD-DB.2'] },
+  ]
+  const report = estimate(reqs(), plan({ foundations }))
+  expect(report.slices.map((x) => [x.id, x.frs, x.planDays])).toEqual([
+    ['F', 1, 2],
+    ['P', 4, 8],
+    ['D', 1, 1],
+  ])
+})
+
+test('a split that leaves part of a capability under the same id names the clash', () => {
+  const products = [{ id: 'PM-01', slice: 'P', name: 'Create', members: ['PM-01.1'] }]
+  expect(() => estimate(reqs(), plan({ products }))).toThrow('PM-01.2 is left unclaimed')
+})
+
+test('a package listed as waiting on itself is refused', () => {
+  const products = [{ id: 'PM-01', slice: 'P', name: 'Participants', members: ['PM-01'], after: ['PM-01'] }]
+  expect(() => estimate(reqs(), plan({ products }))).toThrow('PM-01 lists itself under after')
+})
+
+test('an escaped pipe is read back as a plain pipe', () => {
+  const md = `### X-01 Thing (New)\n\n${HEADER}\n| X-01.1 | A. | System | api | S | - | s | a \\| b |\n`
+  const md2 = md.replace('| - | s |', '| X-02.1 \\| x | s |')
+  expect(parseRequirements(md2, 'x.md')[0].depends).toEqual(['X-02.1 | x'])
+})
+
+test('work spreads across engineers before it doubles up on one engineer', () => {
+  const team = { engineers: [2], worktrees: [2], headline: { engineers: 2, worktrees: 2 } }
+  const order = estimate(reqs(), plan({ team })).schedules.find((s) => s.rate === 'plan')?.order
+  // F1 starts alone at day 0; the next lane to free is engineer 2's first worktree.
+  expect(order?.slice(0, 2).map((o) => [o.id, o.engineer, o.worktree])).toEqual([
+    ['F1', 1, 1],
+    ['F2', 2, 1],
+  ])
+})
+
+test('the median of an odd number of packages is the middle one', () => {
+  // With AA-01 ungated: 1, 1, 2, 2, 5 days.
+  const slices = plan().slices.map((s) => ({ ...s, gated: false }))
+  expect(estimate(reqs(), plan({ slices })).totals.medianPlanDays).toBe(2)
+})
+
+test('--help prints usage and the plan fields, and exits cleanly', async () => {
+  const proc = Bun.spawn(['bun', `${import.meta.dir}/../schedule.ts`, '--help'], { stdout: 'pipe', stderr: 'pipe' })
+  const out = await new Response(proc.stdout).text()
+  expect(await proc.exited).toBe(0)
+  expect(out).toContain('usage: bun schedule.ts <requirements-dir> <plan.json> [--json <out.json>]')
+  for (const field of ['daysPerWeek', 'rates', 'team', 'slices', 'foundations', 'products', 'dependsOn', 'aliases']) expect(out).toContain(field)
+})
+
+test('a missing argument prints usage to stderr and fails', async () => {
+  const proc = Bun.spawn(['bun', `${import.meta.dir}/../schedule.ts`], { stdout: 'pipe', stderr: 'pipe' })
+  expect(await proc.exited).toBe(2)
+  expect(await new Response(proc.stderr).text()).toContain('usage:')
+})