criteria-review 0.3.3 → 0.7.2

package/agents/README.md

@@ -95,6 +95,19 @@ a network download inside the check and lets a missing dependency read as a pass
 `node_modules/.bin/criteria-review`, falls back to `PATH`, and fails when neither exists. See
 `docs/standard/emit-contract.md`.
 
+### 5. A plan holds ids; the documents hold everything else
+
+`criteria-review plan` records which scenarios a task covers and nothing more - no titles, no
+statuses, no todo list of its own. Every other fact is read live, so nothing here can go stale
+and disagree with a document.
+
+There is therefore **no "mark it done"**. A scenario is done when its status moved and a
+journey cites it, which is a fact rather than a tick. `plan check` answers from the documents
+and exits non-zero while anything declared is still outstanding, which makes it usable as a
+delivery gate.
+
+`--plan` is a scope beside `--since`: what I chose, versus what the branch touched.
+
 ### And one standing rule
 
 **A session that edits an acceptance document regenerates before running tests.** Otherwise the
@@ -121,9 +134,68 @@ not.
 
 ## What is here
 
+**Work runs in two directions, and the skills split on that line.** Confusing them is the
+mistake worth avoiding: one starts from what somebody wanted, the other from what the software
+already does.
+
+```
+FORWARD - there is intent, the software does not exist yet
+
+  architect  ->  intake, tier 1 spec + tier 2 shortlist, brief, declaration
+                     |
+  plan       ->  the scenarios a task covers
+                     |
+       +-------------+-------------+
+       |                           |
+    test                        develop
+"write the test"            "write the code"
+       |                           |
+       +-------------+-------------+
+                     |
+  lookup     ->  a person confirms, corrects, rejects
+                     |
+  bundle     ->  the evidence
+
+
+REVERSE - the software exists, nothing was written down
+
+  backfill   ->  criteria + characterisation journeys, from OBSERVATION
+                 intent inferred, nothing confirmed
+                     |
+  lookup     ->  a person verifies it, and the disagreements are the findings
+```
+
+In the forward direction a test that disagrees with its criterion is a defect in the software.
+In the reverse direction the criterion came from the behaviour, so a disagreement means it was
+observed wrongly. Same artefacts, opposite meaning.
+
 | Skill | For |
 |---|---|
-| [`skills/claude-code/criteria-lookup`](skills/claude-code/criteria-lookup/SKILL.md) | Looking a scenario up and answering it in conversation, and walking the queue one at a time |
+| [`criteria-help`](skills/claude-code/criteria-help/SKILL.md) | **Start here.** Asks what you are doing and routes to the right skill, by situation rather than by name |
+| [`criteria-architect`](skills/claude-code/criteria-architect/SKILL.md) | **Forward.** Vet the request, design the tier 1 spec and tier 2 shortlist, write the brief, save the declaration where the team takes work from |
+| [`criteria-backfill`](skills/claude-code/criteria-backfill/SKILL.md) | **Reverse.** Reverse engineer a legacy area into criteria and characterisation journeys from observation, intent inferred and unconfirmed |
+| [`criteria-plan`](skills/claude-code/criteria-plan/SKILL.md) | Turning a task into a working list of scenario ids: ask, verify, prepare, then act |
+| [`criteria-lookup`](skills/claude-code/criteria-lookup/SKILL.md) | Looking a scenario up and answering it in conversation, and walking the queue one at a time |
+| [`criteria-test`](skills/claude-code/criteria-test/SKILL.md) | Building the journey for a criterion, learning the behaviour by driving the running app |
+| [`criteria-develop`](skills/claude-code/criteria-develop/SKILL.md) | Implementing code for criteria the build does not satisfy, red to green, without editing the criterion |
+| [`criteria-glossary`](skills/claude-code/criteria-glossary/SKILL.md) | Finding where the vocabulary really lives and writing the script that emits the terms manifest, so a rename never stales a document |
+| [`criteria-bundle`](skills/claude-code/criteria-bundle/SKILL.md) | Recording narrated videos for a plan or a branch, and packaging them with their documents |
+
+### What every one of them refuses
+
+Worth reading even if you port only one, because these are the rules that make the rest worth
+having:
+
+- **Never edit a criterion to make a test pass.** Easy, invisible, and the failure the whole
+  system exists to prevent. When the criterion is wrong, raise it and stop.
+- **Never promote a status.** `verified` claims a person watched it; `accepted` is a claim about
+  intent. Neither is an agent's to make, and least of all about its own work.
+- **Never invent intent.** Cite a source or write `INFERRED`. Code contains what a system does,
+  never why anyone wanted it.
+- **Know which direction you are in.** A characterisation journey from `backfill` pins what the
+  software does and proves nothing about whether it is right; a journey from `criteria-test`
+  proves a criterion somebody chose. Reporting the first as if it were the second is how a green
+  suite comes to defend behaviour nobody ever wanted.
 
 ## What deliberately is not here
 

package/agents/skills/claude-code/criteria-architect/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: criteria-architect
+description: Drive the forward direction: take a source of intent and design the acceptance spec and the technical brief a team can build from. Vets the request at intake, designs tier 1 scenarios and the tier 2 obligation shortlist, writes the brief, then asks where the declaration should be saved - a DevOps task, a GitHub issue, a document - so the scenario ids it names match what is committed. Use when the architect says "design this", "solution this", "new feature", "here is the intent", "prepare this task", or hands over a request that is not yet real work.
+---
+
+# Design a feature from intent
+
+The **forward direction**: intent, then criteria, then tests, then code. (The reverse - a legacy
+application with nothing written down - is `criteria-backfill`, which works from observation and
+infers intent. Do not mix them: one starts from what somebody wanted, the other from what the
+software does.)
+
+This skill drives the process the standard already defines. Read
+`npx criteria-review guide` and the roles document before working; what follows is how to run
+it, not a restatement of it.
+
+---
+
+## 1. Intake: is this real work yet?
+
+A request arriving from outside is **a want, not a specification**, and admitting it as though it
+were one is how unsourced intent enters the system.
+
+Take the source they give you - a conversation, a ticket, a document, a paragraph - and check it
+carries three things:
+
+- **A named actor and a real "so that".** Not "add a filter": who is blocked without it, and
+  what can they not currently do. A circular "so that" is a heading, not a story.
+- **Sourced intent, or an explicit question in its place.** Every claim about what was wanted
+  cites where it came from - a dated conversation with a named owner, a ticket, a recorded
+  commitment. Where nothing exists, carry **the question**, not a confident guess. Never reverse
+  engineer intent from what a competitor does or from what seems reasonable.
+- **The scope line.** One sentence naming what is in and, more usefully, what is deliberately
+  out. Most disputes at delivery are about the out.
+
+The output is not "approved". It is one of three, and say which:
+
+```
+ADMITTED  intent sourced, actor named, scope line written
+RETURNED  to the requester - naming the specific missing piece
+HELD      as a question against <who owns the answer>
+```
+
+**Do not design a returned or held request.** Designing around a missing intent is how a guess
+becomes a requirement with an architect's authority on it.
+
+## 2. Design the acceptance spec
+
+The tier 1 document plus the tier 2 shortlist, enumerated **before** anyone has an interest in
+the list being short.
+
+**Tier 1** - what the requester would recognise, in their language, one actor per scenario. Work
+outward from the happy path: the refusals, the permission boundaries, the states where the
+action makes no sense, the limits. Each is an ordinary scenario with its own id, not a bullet at
+the bottom.
+
+Status is **`proposed`**: written at planning, before the software exists. That is exactly what
+that status means, and it distinguishes these from anything derived off an implementation.
+
+**Tier 2** - the obligations this feature instantiates: partial writes, idempotency under retry,
+races, audit ordering, malformed input, boundaries, and authorisation enumerated including who
+must be refused. Taken from the catalogue rather than from imagination, because a catalogue can
+be checked against and diligence cannot.
+
+They attach to **the unit of work, never to a scenario or a journey.** An obligation is by
+definition something no user would describe, so it has no tier 1 parent and never will.
+
+Write them to a sibling file in the area folder, `acceptance/<area>/<area>-obligations.md`, kept
+separate from the acceptance document for one practical reason: tier 1 is shared with the
+requester and tier 2 never is, so "send them that file" is a safer operation than "send that file
+with the second half removed". Putting tier 2 in front of the requester buries the business
+intent they are being asked to approve.
+
+Present both for correction before writing anything. For tier 1, present the ids you propose and
+let them be renamed - ids are stable forever and never reused, so a bad prefix is expensive
+later.
+
+## 3. Write the technical brief
+
+Short on purpose. **If it is long, the architect is doing the team's job.**
+
+| Section | What goes in it |
+|---|---|
+| Intent, one paragraph | The agreed "so that", so the brief reads without the acceptance document open |
+| Obligations shortlist | The tier 2 ids, each a concrete list of tests rather than a feeling |
+| Contracts | API shape, events and messages, the data model - the boundary the team builds behind |
+| Decisions taken | Cross-cutting calls already made, each with a one-line why, so they are not relitigated |
+| Decisions left open | The local calls the team owns, named as theirs, so delegation is explicit |
+| Risks retired | Spikes done and what they proved; unknowns that would otherwise surface mid-sprint |
+| Out of scope | What this deliberately does not do, so a returned implementation is not marked short |
+
+**The hardest judgement in the role, and the one to get right here: specify the outcome
+completely, and do not specify the mechanism.** A gap in the outcome will not be correctly
+filled by someone who was not in the conversation. But the moment the brief pre-writes the code,
+designing costs what building costs and the reason for separating them is gone.
+
+The bar for the whole handoff is blunt: **a faithful, literal reading of the spec and the brief
+must produce the right software**, with no discrimination required on the far side. Anything
+ambiguous may not be queried - it may simply be guessed, built, and reported done.
+
+## 4. Ask where the declaration is saved
+
+Two destinations, and they are different things:
+
+- **The criteria go in the repository**, committed, where the review tool reads them:
+  `acceptance/<area>/<area>-acceptance.md`.
+- **The declaration goes in the work item** - the DevOps task, the GitHub issue, wherever the
+  team takes work from. It names the brief and **the scenario ids**, and those ids must match
+  what was committed exactly, because that is what `criteria-plan` reads back when someone picks
+  the task up.
+
+So ask:
+
+```
+Where should the task declaration go?
+1  a DevOps work item   - id, or create a new one
+2  a GitHub issue       - number, or create a new one
+3  a document in the repo
+4  print it - I will paste it myself
+```
+
+Then write it, and **verify the ids round-trip**: the ids in the work item must resolve against
+the committed documents.
+
+```bash
+npx criteria-review plan set <the ids> --task "<name>" --source "<the work item>"
+npx criteria-review plan            # every id resolves, nothing unresolved
+```
+
+If any id does not resolve, the declaration and the repository have already drifted, on day one.
+Fix it now rather than letting a developer find it.
+
+## 5. Hand off, and say what is owed
+
+```
+ADMITTED. 11 tier 1 scenarios (proposed), 5 tier 2 obligations.
+  criteria  -> acceptance/till-lock/till-lock-acceptance.md   committed
+  brief     -> issue #412
+  ids verified against the committed documents
+Owed before build: the requester confirms the tier 1 spec (minus tier 2).
+Next: `criteria-test` for the journeys, `criteria-develop` for the code.
+```
+
+**Share tier 1 with the requester and get it confirmed** before implementation. A document
+carries force in a disagreement only if it was agreed - that is what turns "what the developer
+assumed" into "what we agreed". Tier 2 stays inside the team.
+
+**Never promote a status.** These are `proposed` until a person moves them, and the person is
+the one who owns the intent, not the one who wrote it down.

package/agents/skills/claude-code/criteria-backfill/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: criteria-backfill
+description: Reverse engineer a legacy application into specs and tests that QA and the solution architect can verify. Asks which area to investigate, learns the behaviour by reading and running it, then recommends a filename, ids, roles, user stories and a numbered scenario list for correction before anything is written. Builds criteria and characterisation journeys from OBSERVATION; intent is inferred and marked as such until a human confirms it. Use when the architect says "backfill", "reverse engineer X", "we have no scenarios for this area", "document what this does", or a plan turns up work with no criteria behind it.
+---
+
+# Reverse engineer an existing application
+
+This is the **reverse direction** of the two the process has. Forward is intent to criteria to
+tests to code, and the solution architect drives it. Reverse is this: a legacy application
+exists, nobody wrote down what it promises, and the job is to produce specs and tests from
+**observation** to the point where QA and the architect can verify them.
+
+The output is a document of scenarios, and journeys that pin the behaviour, which a person can
+confirm, correct or reject.
+
+Four steps. **Nothing is written until step 3 has been corrected.**
+
+---
+
+## 0. What is being produced, and what it is worth
+
+> Code contains what a system **does**. It never contains why anyone wanted it.
+
+So the behaviour here is observed and the **intent is inferred**, every time, and it is marked
+`INFERRED` rather than asserted. An agent asked to document intent while reading only the
+implementation will produce it fluently, plausibly and fabricated; the marking is what stops
+that from becoming a requirement nobody chose.
+
+**Yes, this produces tests as well as criteria** - characterisation journeys that pin what the
+software does today. Be clear about what they are worth, because it is not the same as a forward
+test:
+
+- They **cannot disagree with the software.** They were written from it. A green one proves
+  nothing about whether the behaviour is right.
+- What they buy is that the behaviour is now **pinned**: a change to it becomes visible instead
+  of silent, on a codebase where nothing was watching.
+- And they make the criteria **verifiable**: QA and the architect get something concrete to
+  watch running, rather than a paragraph to agree with in the abstract.
+
+The disagreement comes later, and from a person - reading a derived criterion and saying *that is
+not what it should do*. That is the whole point of the reverse direction, and it is why the one
+rule that must not bend is the next one.
+
+**Nothing produced here is confirmed.** Every scenario is `derived`, every intent is `INFERRED`
+unless genuinely cited, and nothing is ever `accepted` or `verified`. A characterisation test
+whose criterion has been mistaken for a requirement is worse than no test, because it now defends
+the current behaviour against anyone trying to change it.
+
+## 1. Ask what to investigate
+
+Never pick the area yourself. Ask, and offer help choosing:
+
+```
+Which area should I work through?
+1  name it              - "the till", "shift hand-over", "refunds"
+2  show me candidates   - I will list areas with code and no criteria
+3  from a plan          - items that resolved to nothing when the task was planned
+```
+
+An **area is a thing a user would name.** "Locking the till" is an area. "SessionController" is
+not. If the answer is a module rather than a behaviour, say so and ask again.
+
+Then ask what may be read as intent: a design note, a decision log, an issue, a specification,
+a conversation they remember. **Ask explicitly, because this is the only chance to get real
+intent**, and once the document is written the inferred version starts looking like a fact.
+
+## 2. Investigate, in this order
+
+**Documentation first, code second.** Reversing it means the code frames what you then go
+looking for, and every document you read afterwards is read as confirmation.
+
+1. **Read the sources they named**, and any decision record or phase document covering the
+   area. Note exact citations - `file.md:214`, an issue number, a dated decision. A citation is
+   a path, a line, an id or a URL. Prose that merely discusses intent is **not** a citation.
+2. **Read the implementation** to learn what the software does: the actor's entry point, the
+   guards, the states, what is refused and what is silently allowed.
+3. **Run it if you can.** Citing `file:line` proves a line was read; running the flow proves the
+   system does it. Anything you only read is a weaker claim, and the difference belongs in the
+   provenance line.
+4. **Collect the anomalies as you go.** States nothing can write, guards no caller reaches,
+   buttons with no behaviour behind them, comments contradicting the code. **This is the highest
+   value output of the whole exercise**, higher than the document - derived blindly, a status
+   with four guards and no writer reads as "the system supports this"; derived carefully it is
+   a defect report.
+
+## 3. Recommend, and wait for corrections
+
+Present all of it before writing anything:
+
+**Where it goes**
+
+```
+acceptance/till-lock/till-lock-acceptance.md          new
+acceptance/shift-lifecycle/shift-lifecycle-acceptance.md   exists - 6 scenarios would be added
+```
+
+One folder per area, named for the area rather than the module. Say plainly when an area
+already has a document, because adding to one is different from starting one.
+
+**The id scheme**, checked against every registered project for collisions:
+
+```
+LOCK-SET-001..004   locking
+LOCK-OPEN-001..004  reopening
+LOCK-FAIL-001..003  lockout
+```
+
+Ids are stable forever and never reused, so a bad prefix is expensive later. Offer the grouping
+and let them rename it.
+
+**The roles**, including any that must be refused.
+
+**The user stories**, in prose, with the "so that" doing real work - "as a user I want a lock
+button so that I can lock the screen" is circular and says nothing a test could disagree with.
+
+**The scenarios**, numbered, each one line, each marked with where its intent came from:
+
+```
+  1  LOCK-SET-001  sourced   design-notes/till-lock.md:44   Locking de-authorises the terminal
+  2  LOCK-SET-002  sourced   design-notes/till-lock.md:51   The shift and drawer stay open
+  3  LOCK-OPEN-002 INFERRED  -                              A different cashier is recorded
+  ...
+```
+
+Then ask for corrections, and ask specifically about the `INFERRED` ones: **each is a question,
+not a statement.** "I could not find why this behaves this way - is it deliberate, and is this
+what it should do?" One sentence from them turns an unfalsifiable criterion into one that can
+catch a defect.
+
+Also present the anomalies, separately and plainly. They are not scenarios and should not be
+smuggled in as if they were.
+
+## 4. Write the criteria, then the journeys that pin them
+
+Only after correction. Follow `criteria-review guide` and the standard's authoring rules; the
+ones most often broken here:
+
+- **One actor, in their language.** No route paths, no component names, no HTTP status codes.
+- **`Then` clauses are assertions**, close to 1:1 with what a test would assert.
+- **Negative outcomes are stated**, not implied. "And the drawer does not open" is a clause.
+- **Edge cases get their own scenario and their own id.** A wrong PIN, a lockout countdown, an
+  expired voucher - each is an ordinary use case. A bullet list at the bottom headed "edge
+  cases" is a list of things nobody automated.
+- **Tier 1 only.** Partial writes, retries, races, malformed input and boundaries are real and
+  belong to the engineering obligations, not here. No operator will ever describe them, and
+  putting them here buries the business intent this layer exists to make reviewable.
+- **Every scenario is `derived`**, or `proposed` if the software does not exist yet. Never
+  `verified`, never `accepted` - those are claims only a person can make.
+- **Every block carries a provenance comment**, a citation or `INFERRED`.
+
+Where you believe the behaviour is wrong, **write the scenario as the wanted behaviour and say
+so in the comment**, and do not write a journey pinning the behaviour you think is a defect.
+
+Then the journeys, following `criteria-test`'s rules for binding, selectors and seeding - with
+one difference that matters. There, a journey that disagrees with its criterion is a finding to
+raise. Here the criterion came from the behaviour, so a disagreement means you observed it
+wrongly: go back and look again rather than adjusting either artefact to match the other.
+
+**A scenario you cannot exercise is a finding, not a gap.** A path no caller can reach, a state
+nothing writes, an affordance with nothing behind it - record it in the anomaly list and leave
+the scenario without a journey. Writing a journey that fakes its way into an unreachable state
+would produce a green test for something that cannot happen.
+
+## 5. Hand it on
+
+Say what was produced and what is owed:
+
+```
+14 scenarios written to acceptance/till-lock/till-lock-acceptance.md
+  2 sourced, 12 INFERRED - the 12 are questions, not statements
+11 characterisation journeys written and green - they PIN today's behaviour and
+   prove nothing about whether it is right
+3 scenarios could not be exercised (listed) - and that is a finding, not a gap
+4 anomalies found (listed above), none of them scenarios
+Next: `criteria-lookup` to walk the inferred ones with the recordings beside them
+```
+
+Say plainly that the green journeys are not evidence of correctness. A reader who takes "11
+green" as reassurance has drawn the opposite conclusion from the truth: they show the software
+does what it does, on a codebase where nobody had written down what it should do.
+
+Never promote a status, never mark anything accepted, and do not fix the anomalies here. This
+skill produces a document, a set of pinning tests and a list of questions. Answering them is the
+architect's, and acting on them is another skill's.

package/agents/skills/claude-code/criteria-bundle/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: criteria-bundle
+description: Record narrated videos for the scenarios in the current plan or added on this branch, and assemble them with their acceptance documents into a delivery package. Runs the journeys at human-viewable pacing at 1080p, names each clip for the scenario it proves, and reports every scenario that has no recording rather than shipping a package that looks complete. Use when the architect says "record these", "bundle the videos", "make the handoff package", or a task is finished and needs its evidence.
+---
+
+# Record and bundle the evidence
+
+A test count is a claim about the software. A video is the software. This produces the second
+kind, for the scenarios a task actually covered.
+
+The full procedure, its failure modes and the reference plumbing are in the standard's
+**Recording a journey** (`npx criteria-review guide` lists it, and the reading tab renders it).
+This skill is how to run it and what to refuse.
+
+---
+
+## The rule that governs the whole thing
+
+**Tests run at full speed. Videos published for people run at a speed a person can follow.**
+
+Same journeys, same assertions, same code path, run twice, with an environment seam nobody sets
+by default as the only difference. Two ways to get it wrong, and they are opposite:
+
+- Pacing the gating suite for watchability gets the affordance deleted by whoever is waiting on
+  the build, and the demonstration goes with it.
+- Publishing a clip at test speed produces footage of a cursor flickering around an unfamiliar
+  interface: cheaper to make and worth nothing, because the viewer cannot tell what happened.
+
+If a set of clips runs in under a minute, it was filmed at test speed. If the everyday suite got
+slower this week, something demonstration-only became unconditional.
+
+## 1. Decide the scope, and say what it is
+
+```bash
+npx criteria-review queue --plan      # what this task covers
+npx criteria-review queue --since main   # what this branch added
+```
+
+Ask which, rather than assuming. A package labelled as a task's evidence that quietly contains
+the whole suite is misleading in the direction that matters.
+
+Then name the ones with no journey. **They cannot be recorded, and that is the finding** - a
+scenario with no journey is not evidence missing from the package, it is coverage missing from
+the work. Report it before recording rather than after.
+
+## 2. Record
+
+From a clean database, single worker, only the journeys in scope:
+
+```bash
+E2E_VIDEO=1 E2E_SLOWMO=900 E2E_CARD_MS=4500 E2E_STEP_PAUSE=2000 \
+  npx playwright test --workers=1 <the journeys in scope>
+```
+
+Environment variable names are the project's own - read its watch-mode module rather than
+assuming these. What must be true, whatever they are called: **1080p at a 1:1 capture size**,
+per-test timeout raised for the recording run only, and every demonstration affordance inert
+when the seam is unset.
+
+**The recording run is a real pass, not a filming session.** Same assertions. If it goes red,
+you have found something, and filming stops until it is understood - a green suite and a red
+recording of the same journeys means the wider viewport broke something.
+
+## 3. Copy the files out immediately
+
+The runner wipes its output directory at the start of every run, so the next headless run
+destroys them. This is the single most common way a recording session is lost, and it is
+unrecoverable except by recording again.
+
+Then rename each to lead with its scenario id, which is what maps a clip to a criterion.
+
+## 4. Check each clip before it goes anywhere
+
+Open them. A recording session that produced files is not a recording session that produced
+evidence, and every one of these failures leaves the run green:
+
+- **Blank, and unusually small** - the journey opened its own browser context, which inherited
+  no recording options. A thirty-second clip of about 55KB is this.
+- **Soft, roughly 800x450** - the runner scaled the viewport into its default 800x800 box.
+- **Two indistinguishable files from one test** - two contexts, both named by internal id.
+- **No title card**, or captions that do not match the document's wording.
+
+## 5. Assemble
+
+Documents first, clips in the order the acceptance document introduces their scenarios:
+
+```
+<target>/<area>-<recording date>/
+  00-<Area>-Acceptance.pdf
+  01-<SCENARIO-ID>-<slug>.webm
+  ...
+  README.md
+```
+
+- **The numbering comes from the document**, not from a list you keep, so adding a scenario and
+  re-running is enough.
+- **A gap in the numbers is meaningful** - a scenario written down with no recording. The README
+  names those, and names any clip that matched no scenario rather than dropping it.
+- **Replace the target folder, do not merge.** A stale clip from a retired scenario is worse
+  than no folder, because nothing about it says it is out of date.
+- **Label it with the date of the recording, not today's.** The package is evidence from a
+  moment.
+
+**Write the manifest**, which is what ties the package to the work rather than leaving it a
+folder of clips:
+
+```bash
+npx criteria-review manifest --out <target>/manifest.json
+```
+
+It records the task and its source - the issue, the work item, the URL the plan was built from -
+alongside every scenario, its status, and the clip that proves it. **Scenarios with no recording
+are listed rather than omitted**, so a package cannot read as complete when it is not, and a
+fuzzy-matched clip is marked as matched rather than named, because that is a guess that this
+video shows this scenario.
+
+A video not tied to a named scenario is only a recording. A package not tied to a work item has
+the same problem one level up: six months later nobody can say which delivery it belonged to.
+
+**Known gap, and say it rather than hiding it:** the tool writes the manifest but does not
+assemble the folder - the copying, renaming and document conversion is still a project script or
+hand work. The standard's own rule is that a package assembled by hand gets skipped exactly when
+the delivery is under pressure. If you are doing it by hand, say so in the report and recommend
+scripting it.
+
+## 6. Report
+
+```
+6 scenarios in scope for "Till hardening" (issue #412)
+  5 recorded, checked, packaged to <path>
+  1 has no journey - LOCK-OPEN-002 - not recorded, and not covered
+  manifest.json written: 6 scenarios, 1 with no recording
+  folder assembled by hand (no package command); recommend scripting it
+```
+
+Never promote a status because a recording exists. A video is what lets a person promote one
+themselves in `criteria-lookup`, watching it - which is what `verified` has always meant.