@jabworks/condux 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jabworks/condux",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "OpenCode plugin for the condux workflow toolkit — bundles the condux skills and injects the specialist agents (coder, explorer, planner, researcher) plus an opt-in plan-review listener.",
   "type": "module",
   "publishConfig": {

package/skills/discovery/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: discovery
-description: "Refine a rough idea into a signed-off design, presented in sections for sign-off before any planning or code begins. Feeds the tech spec, written via technical-spec at sign-off. Trigger for LARGE tasks, when scope is unclear, or when the user wants to brainstorm or explore a rough idea. Also when resuming an existing design or design doc — the existing-design check offers resume-or-fresh. A soft gate before /draft-plan: if discovery has not run, ask whether to skip it consciously."
+description: "Refine a rough idea into a signed-off design, presented in sections for sign-off before any planning or code begins. Opens with the requirements — the feature PRD — and feeds the tech spec, written via technical-spec at sign-off. Trigger for LARGE tasks, when scope is unclear, or when the user wants to brainstorm or explore a rough idea — or to pin requirements first: \"write a PRD\", \"product requirements\", \"what are we building and why\". Also when resuming an existing design or design doc — the existing-design check offers resume-or-fresh. A soft gate before /draft-plan: if discovery has not run, ask whether to skip it consciously."
 argument-hint: "<rough idea or feature description>"
 effort: high
 ---
@@ -31,6 +31,13 @@ exists, read its frontmatter `status` and offer accordingly:
 
 Accept either answer, same as any other soft gate in this skill.
 
+**Requirements on disk.** The same two-scope lookup finds
+`specs/<slug>/prd.md`. When it exists, read it before Step 1 and say so —
+"Requirements loaded from `<path>`" — then treat its sections as already
+answered: the goal round asks only for the ones that are empty (The
+Requirements Card, below). A spec with no `prd.md` is the normal case, not a
+gap — say nothing.
+
 ```
 ┌──────────────────────────────────────────────────────────────────┐
 │                        DISCOVERY                                │
@@ -42,6 +49,9 @@ Accept either answer, same as any other soft gate in this skill.
 │    - Is the request already well-defined (ticket, spec doc)?    │
 │      → Ask: "This looks well-defined. Skip discovery and       │
 │        go straight to planning?"                                │
+│      → If discovery goes ahead: a PRD, ticket or product doc    │
+│        they brought is requirements, not a design — it feeds    │
+│        §0 (below); it never stands in for the design            │
 │    - Is the scope genuinely unclear?                            │
 │      → Proceed to Step 2                                        │
 │                                                                  │
@@ -50,10 +60,15 @@ Accept either answer, same as any other soft gate in this skill.
 │  Focus on: goals, constraints, what "done" looks like,         │
 │  known unknowns, and what should explicitly NOT be built.      │
 │  No implementation detail yet — that's Step 4's job.           │
+│  The batch covers the six PRD sections — problem, users,        │
+│  goals and non-goals, success metrics, scope, open              │
+│  questions — skipping any a loaded PRD already answers.         │
 │                                                                  │
 │  Step 3: PROPOSE                                                │
 │  Announce the section list, then create the design file        │
 │  (status: in-progress) and open the live preview.              │
+│  First card is §0 · requirements — the goal round in            │
+│  prd.md's six headings (The Requirements Card, below).          │
 │  Present one section at a time in the card shape, get          │
 │  acknowledgment, append the agreed section to the file.        │
 │  §1 is approaches-and-tradeoffs; the rest follow the design.   │
@@ -82,6 +97,8 @@ Accept either answer, same as any other soft gate in this skill.
 │    ✓ No subsystems that should be separate tasks               │
 │    ✓ Every contract, mapping, or edge case named in the        │
 │      design has a home in a spec concern file                   │
+│    ✓ §0 invents nothing — an unanswered PRD section is an       │
+│      open question, never a filled-in guess                     │
 │    ✓ Unanswered detail questions surface as open questions,    │
 │      never silently dropped                                     │
 │                                                                  │
@@ -94,8 +111,9 @@ Accept either answer, same as any other soft gate in this skill.
 │  every agreed section is in it. Flip its frontmatter            │
 │  status: in-progress → signed-off. That flip is what           │
 │  /draft-plan's gate check reads.                                │
-│  Spec write-back is default-on: persist the concern files       │
-│  too (Spec Integration below) unless the user opts out.         │
+│  Spec write-back is default-on: persist the concern files —     │
+│  prd.md from §0, then the rest (Spec Integration below) —       │
+│  unless the user opts out.                                      │
 │  The preview is already running — reuse it (Design Review       │
 │  Loop); never launch a second server or open a second tab.      │
 └──────────────────────────────────────────────────────────────────┘
@@ -160,6 +178,8 @@ Accept either answer. Never block. Never lecture.
 ✗ Proceeding to planning without explicit sign-off
 ✗ Treating a well-defined ticket as needing full discovery
 ✗ Widening past the named target surface without saying so
+✗ Inventing users, metrics, or scope to complete §0
+✗ Writing prd.md before sign-off
 ✗ A section card that runs past one screen, or a paragraph past three lines
 ✗ Launching a second preview server, or opening a tab the user didn't ask for
 ```
@@ -211,6 +231,51 @@ the path as the label, and nothing degrades without a server. Never write a
 git-root-relative href (it cannot resolve against the served root), and
 never inline a copy of the diagram beside the artifact.
 
+## The Requirements Card (§0)
+
+The goal round has always collected requirements — goals, what done looks
+like, what not to build — and then compressed them into a three-line why-line,
+where they were lost. §0 keeps them. It is the first card of Step 3, presented
+once for acknowledgment before §1, and it is the feature's PRD in draft.
+
+**Shape.** §0 uses `prd.md`'s six headings verbatim — *Problem · Users · Goals
+and non-goals · Success metrics · Scope · Open questions* — each a table or a
+short list (technical-spec's `references/templates.md` has the template). Same
+one-screen rule as any card; overflow goes in the design file.
+
+**§0 sits outside the count.** The section list announced before §1 names the
+*design* sections — "4 sections: approach · …" — and cards stay `§n of N`
+against that N. Announce §0 separately, first: *"Requirements first (§0), then
+4 sections: …"*.
+
+**Three ways in, one card out:**
+
+| Arriving with | What §0 is built from |
+|---|---|
+| nothing | the goal round — one batch, six slots |
+| `specs/<slug>/prd.md` on disk | that file; ask only for empty sections |
+| a ticket, product doc, or pasted PRD | that document, mapped onto the six headings, gaps marked |
+
+**Rules underneath it:**
+
+| Rule | Why |
+|---|---|
+| An unanswered section is asked once, then written under *Open questions* — never filled in | a six-slot shape creates pressure to complete it; invented users and metrics read as facts forever after |
+| Content from the user's document that fits no heading goes under *Open questions*, in its original wording | losing what they wrote to fit the shape is worse than an untidy list |
+| A later design section that changes scope, goals, or users updates §0 visibly, and names the change | `prd.md` and `decisions.md` describe one feature; preflight's drift check reads both |
+| `prd.md` is written at Step 7, never at §0 | a PRD in `specs/` for a discovery nobody signed off is a durable file making unsigned claims |
+| The design's why-line is derived from §0's *Problem* | one fact, one home — never a second copy that can disagree |
+
+A request for *only* the requirements — "write a PRD for X", no design wanted
+yet — still runs Steps 1–3 as far as §0, then asks: carry on into the design,
+or sign off here and save the PRD alone? Saving it alone is the Step 7 spec
+write-back with `prd.md` as the only concern file — and **the design file
+keeps `status: in-progress`**. A PRD is not a design: no approach was agreed,
+so `/draft-plan`'s gate must still ask, and flipping the status here would let
+it plan against a file with requirements and no design in it. A later
+discovery on the same feature finds the file and the `prd.md`, and resumes
+from §0.
+
 ## The Design File and the Live Preview (Step 3 onward)
 
 **The file is created at §1, not at sign-off.** Write
@@ -275,8 +340,9 @@ A short design summary covering:
 - Key constraints and out-of-scope items
 - Open questions (if any remain after sign-off)
 
-Detail-round answers (Step 4) belong in the spec concern files, not the
-summary — the summary stays short; the spec carries the detail.
+Requirements live in §0 and become `prd.md`; detail-round answers (Step 4)
+belong in the other spec concern files, not the summary — the summary stays
+short; the spec carries the detail.
 
 Lives at: `.condux/designs/YYYY-MM-DD-<feature>.md`, created at §1 and
 appended to per section, in the shape of `references/design-template.md`
@@ -334,8 +400,9 @@ the launch here.
 Integrates with `technical-spec` to persist the design and render it live while
 discovery runs. At sign-off (Step 7), unless the user opts out: run
 `technical-spec`'s scaffold script to create the spec directory, write the
-design's decisions/contracts/mappings/edge-cases into its concern files
-(`decisions.md`, `api.md`, `fields.md`, `quirks.md`, `implementation.md`), then
+design's requirements/decisions/contracts/mappings/edge-cases into its concern
+files (`prd.md` from §0, then `decisions.md`, `api.md`, `fields.md`,
+`quirks.md`, `implementation.md`), then
 launch `plan-review`'s directory-mode preview against that spec path so it
 live-reloads as the conversation refines the design. Full commands, the
 existing-spec check, and how to action a submitted review decision:

package/skills/discovery/evals/trigger_eval.json

@@ -19,6 +19,10 @@
   { "query": "review the plan in the browser", "should_trigger": true, "expected_skill": "plan-review" },
   { "query": "save what we decided as a spec", "should_trigger": true, "expected_skill": "technical-spec" },
   { "query": "why does checkout 500 on submit", "should_trigger": true, "expected_skill": "root-cause-analysis" },
+  { "query": "write a PRD for the notifications feature", "should_trigger": true, "expected_skill": "discovery", "accept": ["workflow"] },
+  { "query": "what are we building and why — pin the product requirements before any design", "should_trigger": true, "expected_skill": "discovery", "accept": ["workflow"] },
+  { "query": "write a PRD for fixing the footer typo", "should_trigger": true, "expected_skill": "workflow", "disallowed": ["discovery"], "note": "A PRD ask on a trivial change goes to the router, which picks SMALL; discovery must not claim it (specs/prd-authoring quirk Q5)." },
+  { "query": "save this PRD", "should_trigger": true, "expected_skill": "technical-spec" },
   { "query": "help me write my resume", "should_trigger": false, "expected_skill": null },
   { "query": "design a logo for the app", "should_trigger": false, "expected_skill": null }
 ]

package/skills/discovery/references/design-template.md

@@ -23,6 +23,13 @@ feature: <slug>
 
 **Sections:** N — <names, in order>          [at creation]
 
+## §0 · requirements — AGREED <date>         [on acknowledgment; revised visibly]
+
+<prd.md's six headings, verbatim — Problem · Users · Goals and non-goals ·
+Success metrics · Scope · Open questions — each a table or short list.
+technical-spec's references/templates.md has the template. Step 7 copies
+this part into specs/<slug>/prd.md heading for heading.>
+
 ## §n · <name> — AGREED <date>               [appended per agreement]
 
 **Decided:** <the choice>, because <one line>.
@@ -49,8 +56,11 @@ feature: <slug>
 | Rule | Why |
 |---|---|
 | Every agreed § carries the four facts a `decisions.md` entry carries — title+date, choice, alternatives with one-line why-nots, consequence | Step 7's spec write-back becomes transcription, not authorship; the design doc and `decisions.md` cannot disagree on shape because they share one |
+| §0 carries `prd.md`'s six headings verbatim, outside the `§n of N` count; an unanswered section is an open question, never a guess | Step 7 copies §0 into `prd.md` — same shape, so nothing is re-authored; an invented metric reads as fact forever after |
+| The why-line is derived from §0's *Problem*, never a second statement of it | one fact, one home |
 | Sections are appended as agreed, never drafted ahead | The file records the conversation's actual state; a pre-drafted section reads as agreed when it isn't |
 | Constraints discovered mid-flow go straight into their table | The section exists from creation precisely so mid-flow findings have a home other than an invented heading |
+| A requirements-only discovery that stops at §0 writes `prd.md` and leaves `status: in-progress` | a PRD is not a design; `/draft-plan`'s gate must still ask |
 | `status` flips to `signed-off` only at Step 7, and nothing else edits the frontmatter | `/draft-plan` and the `planner` agent gate on this value |
 
 ## Lifecycle stamps, spelled out
@@ -58,6 +68,8 @@ feature: <slug>
 | Stamp | When written | Parts |
 |---|---|---|
 | `[at creation]` | Step 3 opens, before §1 is presented | frontmatter, title, why-line, section list |
+| `[on acknowledgment]` | the §0 card is acknowledged, before §1 is presented | §0 requirements — written then, not before, so the file never shows requirements as agreed that nobody has seen |
+| `[revised visibly]` | a later section changes scope, goals, or users | §0 — edited in place, the change named in that section's entry |
 | `[appended per agreement]` | each section, at the moment it is agreed | the § entries |
 | `[accumulates]` | any time | `Constraints & out of scope` rows |
 | `[finalized at sign-off]` | Step 7 | `Open questions`, the `status` flip |

package/skills/discovery/references/spec-integration.md

@@ -21,8 +21,8 @@ If yes, go straight to **Launch preview** below (skip scaffold + write — spec
 The Markdown design doc (Step 7) is always written. The spec write-back is
 **default-on** — announce it rather than ask:
 
-> "Saving this as a tech spec too (decisions + the concern files from the
-> detail round) and opening the live preview — say no to skip."
+> "Saving this as a tech spec too (the PRD from §0, decisions, and the concern
+> files from the detail round) and opening the live preview — say no to skip."
 
 Unless the user opts out (the spec directory then becomes the target for the
 Design Review Loop above, in directory mode):
@@ -45,7 +45,12 @@ Design Review Loop above, in directory mode):
    repo structure, automatically.
 
 3. **Write initial spec files** from the design into `$SPEC_PATH/`.
-   `decisions.md` always (chosen approach + rationale). Then every concern
+   `prd.md` first — the design file's `§0 · requirements` part, copied
+   heading for heading; if a `prd.md` was already on disk, update it in
+   place and add a changelog line to `index.md` rather than overwriting
+   silently. `decisions.md` always (chosen approach + rationale) — except on
+   the requirements-only exit (SKILL.md → The Requirements Card), where no
+   approach was agreed and `prd.md` is the only file written. Then every concern
    the detail round produced answers for gets its file: `api.md`,
    `fields.md`, `quirks.md`, `implementation.md`. A detail-round answer
    that never lands in a spec file is a bug in the flow, not a judgment call.

package/skills/preflight/SKILL.md

@@ -68,6 +68,7 @@ missing or scaffold-only file makes no claim, skip it:
 
 | Concern file | Check the implementation against |
 |---|---|
+| `prd.md` | requirements — work that lands in the **Scope** table's *Out* column, or inside a row of the **Non-goal** table, is drift: both are explicit exclusions. Work the *In* column merely does not mention is not. Goals are compared only when the task claims to complete the feature; a task that serves a subset of them is not drift |
 | `api.md` | contracts touched — shapes, error forms, external calls |
 | `fields.md` | source-to-UI mappings and transformations |
 | `quirks.md` | edge cases and failure modes the spec says are handled |

package/skills/subagent-execution/references/task-brief.sh

@@ -21,11 +21,14 @@ mkdir -p "$SCRATCH_DIR"
 SLUG=$(basename "$PLAN_FILE" .md)
 BRIEF_FILE="$SCRATCH_DIR/${SLUG}-task-${TASK_N}-brief.md"
 
+# A card is a `## Task N:` heading (draft-plan's plan-template.md) or the older
+# `### Task N:`. The card ends at the next card of either shape, or at any
+# other `## ` section — a trailing "## Verification" is not part of the brief.
 awk -v n="$TASK_N" '
   BEGIN { found = 0 }
-  /^### Task [0-9]+:/ {
+  /^##+ Task [0-9]+:/ || /^## / {
     if (found) exit
-    if ($0 ~ ("^### Task " n ":")) { found = 1 }
+    if ($0 ~ ("^##+ Task " n ":")) { found = 1 }
   }
   found { print }
 ' "$PLAN_FILE" > "$BRIEF_FILE"

package/skills/technical-spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: technical-spec
-description: "Persists feature decisions, API contracts, implementation details, and quirks into a structured, queryable spec tree — one folder per feature, one file per concern. Invoke-only — discovery runs it at design sign-off and preflight's drift check reads its output; the user runs it via /technical-spec when they say \"save spec\", \"document this\", \"write up what we decided\", \"record the decision rationale\", or \"spec this out\" — recording decisions for the future is spec work even when phrased as remembering. Not for turning a rough idea into a design first — that's discovery."
+description: "Persists feature requirements, decisions, API contracts, implementation details, and quirks into a structured, queryable spec tree — one folder per feature, one file per concern. Invoke-only — discovery runs it at design sign-off and preflight's drift check reads its output; the user runs it via /technical-spec when they say \"save spec\", \"document this\", \"write up what we decided\", \"record the decision rationale\", \"spec this out\", \"save this PRD\", or \"write up the requirements\" — recording decisions for the future is spec work even when phrased as remembering. Not for turning a rough idea into a design first — that's discovery."
 disable-model-invocation: true
 ---
 
@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 ## Overview
 
-Persists feature decisions, API contracts, implementation details, and quirks into a structured, queryable spec tree. One folder per feature, one file per concern — future sessions load only what they need. Specs are living contracts: `/preflight`'s Drift Check compares the implementation against them at end-of-task.
+Persists feature requirements, decisions, API contracts, implementation details, and quirks into a structured, queryable spec tree. One folder per feature, one file per concern — future sessions load only what they need. Specs are living contracts: `/preflight`'s Drift Check compares the implementation against them at end-of-task.
 
 ## Spec Folder Layout
 
@@ -23,7 +23,8 @@ to place the spec.
   {feature-slug}/           # cross-cutting, or scaffolded from the repo root
   apps/web/
     {feature-slug}/         # scaffolded while working in apps/web
-      index.md              # purpose, TOC, last updated, commit hash, changelog  ← scaffold creates this
+      index.md              # purpose, TOC, last updated, PR stamp, changelog  ← scaffold creates this
+      prd.md                # Requirements: problem, users, goals/non-goals, metrics, scope
       decisions.md          # Design decisions with context + rationale
       api.md                # Endpoints, types, external APIs consumed
       fields.md             # Field mappings: BE/3rd-party → UI, or forwarding chains
@@ -56,9 +57,11 @@ exists and has since the design's first section — discovery creates it at §1
 and appends to it as each section is agreed. So the input here is a finished
 file on disk, not a summary reconstructed from the conversation: read
 `.condux/designs/YYYY-MM-DD-<feature>.md` and map its sections into the
-concern files. Discovery's own preview server is already running against that
-file, so the live-preview offer below applies to the *spec directory* only —
-never start a second server for the design.
+concern files. Its `§0 · requirements` part uses `prd.md`'s six headings
+verbatim, so that mapping is a copy, heading for heading. Discovery's own
+preview server is already running against that file, so the live-preview
+offer below applies to the *spec directory* only — never start a second
+server for the design.
 
 ## Required Notifications
 
@@ -86,10 +89,16 @@ bash path/to/skill/references/scaffold.sh "WanConfig"
 ```
 
 The script outputs one line:
-- `created:/abs/path/to/specs/wan-config commit:abc1234 date:2026-06-24` — new spec, `index.md` written
-- `exists:/abs/path/to/specs/wan-config commit:abc1234 date:2026-06-24` — spec already exists
+- `created:/abs/path/to/specs/wan-config date:2026-06-24 commit:PR #pending` — new spec, `index.md` written
+- `exists:/abs/path/to/specs/wan-config date:2026-06-24 commit:PR #pending` — spec already exists
 
-Parse `commit`, `date`, and the **absolute spec path** from the output — use the absolute path when writing content files and launching the preview server.
+Parse `date` and the **absolute spec path** from the output — use the absolute path when writing content files and launching the preview server.
+
+The `**Commit:**` stamp names the PR that carries the change (`PR #153`), never
+a commit hash: a hash written on a feature branch is orphaned by the
+squash-merge that lands it, so it resolves only in clones that had the branch.
+The scaffold writes `PR #pending`; replace it with the number once the PR is
+open, and use the same form in changelog lines.
 
 ## After Scaffold: Writing Content Files
 
@@ -105,6 +114,16 @@ the spec all read, so write each row as a claim someone could check.
 trailing `//` per field, JSDoc only when a line won't do. `fields.md` says
 what *happens to it* — mapping and transformation only. One fact never lives
 in both places: a fact with two homes goes missing from the one being read.
+The same split holds one level up: `prd.md` says *why the feature exists and
+for whom*; `decisions.md` says *how it was chosen*. A decision never restates
+the problem, and the PRD never records an alternative.
+
+**`prd.md` is the requirements file, and the one file written before the
+design.** `discovery` authors it from its requirements card and writes it
+here at sign-off; run standalone ("save this PRD", "write up the
+requirements") you write it directly from what the user gives you. Six fixed
+sections — see the template. A section nobody has answered becomes an open
+question; never invent users or metrics to complete the table.
 
 **Quirk headings are `## Q<n> — Title`.** The `Q<n>` anchors are a citation
 contract (`durable-citations.test.mjs` resolves them), so numbers are unique,
@@ -131,7 +150,7 @@ path that resolves nowhere.
 When scaffold output is `exists:`:
 1. Read `index.md` to see current state and which files exist
 2. Update only files with new or changed content
-3. Bump `Last updated` and `Commit` in `index.md` using values from scaffold output
+3. Bump `Last updated` in `index.md` from scaffold output; set `Commit` to the PR carrying this change (`PR #pending` until it is open)
 4. Append to the `## Changelog` in `index.md`
 
 ## Live HTML Preview & Review (Optional)
@@ -188,7 +207,8 @@ feedback file, if a decision is submitted).
 | Mistake | Fix |
 |---------|-----|
 | Skipping the notification/confirmation | Always announce before writing, wait for approval |
-| Not using scaffold output for date/commit | Parse them from the script — don't run git separately |
+| Not using scaffold output for the date | Parse it from the script — don't run git separately |
+| Stamping a commit hash | The stamp is `PR #N` — a branch hash is orphaned by squash-merge; `PR #pending` until the PR is open |
 | Rewriting all files on update | Read `index.md` first, only touch files with new content |
 | Vague decisions | Each decision needs context + rationale + consequences |
 | Creating empty placeholder files | Only create a file when it has real content |

package/skills/technical-spec/evals/trigger_eval.json

@@ -17,6 +17,9 @@
   { "query": "browse the specs tree", "should_trigger": true, "expected_skill": "spec-browser" },
   { "query": "where is the spec for the auth feature", "should_trigger": true, "expected_skill": "spec-browser" },
   { "query": "design the feature first before documenting", "should_trigger": true, "expected_skill": "discovery" },
+  { "query": "save this PRD", "should_trigger": true, "expected_skill": "technical-spec" },
+  { "query": "write up the requirements from this ticket into the spec", "should_trigger": true, "expected_skill": "technical-spec", "disallowed": ["draft-plan"] },
+  { "query": "write a PRD for the notifications feature", "should_trigger": true, "expected_skill": "discovery", "accept": ["workflow"] },
   { "query": "generate openapi yaml from the routes", "should_trigger": false, "expected_skill": null },
   { "query": "write jsdoc comments for this module", "should_trigger": false, "expected_skill": null, "accept": ["workflow"], "note": "Writing comments is a code change — an implementation request workflow claims. null stays primary: it is also fine to just do it." },
   { "query": "host our swagger docs somewhere", "should_trigger": false, "expected_skill": null }

package/skills/technical-spec/references/scaffold.sh

@@ -38,7 +38,12 @@ if [[ -z "$SLUG" || ! "$SLUG" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then
 fi
 
 DATE=$(date +%Y-%m-%d)
-COMMIT=$(git rev-parse --short HEAD 2>/dev/null || echo "no-git")
+# The stamp names the PR that carries the spec, not a commit. A hash taken
+# here is HEAD on a feature branch, and a squash-merge orphans it the moment
+# the PR lands — it resolves only in clones that had the branch. The PR number
+# is not known until the PR is open, so the scaffold writes a placeholder for
+# the author to replace; a spec still stamped `PR #pending` is unfinished.
+COMMIT="PR #pending"
 REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
 [[ -z "$REPO_ROOT" ]] && REPO_ROOT="${PWD}"
 
@@ -76,7 +81,7 @@ case "$SPEC_DIR" in
 esac
 
 if [[ -d "$SPEC_DIR" ]]; then
-  echo "exists:$SPEC_DIR commit:$COMMIT date:$DATE"
+  echo "exists:$SPEC_DIR date:$DATE commit:$COMMIT"
   exit 0
 fi
 
@@ -110,4 +115,4 @@ cat > "$SPEC_DIR/index.md" <<EOF
 - $DATE ($COMMIT): Initial spec
 EOF
 
-echo "created:$SPEC_DIR commit:$COMMIT date:$DATE"
+echo "created:$SPEC_DIR date:$DATE commit:$COMMIT"

package/skills/technical-spec/references/templates.md

@@ -20,7 +20,7 @@ follow. Write each table row as a claim someone could check, not a label.
 > shows for the spec — without it the spec is listed with no description.
 
 **Last updated:** {YYYY-MM-DD}
-**Commit:** {short-hash}
+**Commit:** PR #{N}
 **Status:** draft | review | stable
 
 ## Contents
@@ -31,9 +31,14 @@ follow. Write each table row as a claim someone could check, not a label.
 | [Quirks](quirks.md) | what will bite you, and whether it is mitigated |
 
 ## Changelog
-- {YYYY-MM-DD} ({short-hash}): Initial spec
+- {YYYY-MM-DD} (PR #{N}): Initial spec
 ```
 
+The stamp names the PR that carries the change, never a commit hash: a hash
+written on a feature branch is orphaned by the squash-merge that lands it.
+The scaffold writes `PR #pending`; replace it once the PR is open, and use the
+same form in changelog lines.
+
 The Contents table answers *which file do I open* — one row per concern file
 that actually exists, each `Answers` cell saying what a reader comes to it
 for. Files that don't exist get no row.
@@ -47,6 +52,74 @@ rule existed and two were already dead when they were found.
 
 ---
 
+## prd.md
+
+```markdown
+# PRD — {Feature Name}
+
+| Section | In one line |
+|---|---|
+| Problem | {the problem, stated as a claim} |
+| Users | {who it is for} |
+| Goals | {what changes when this succeeds} |
+| Scope | {where the boundary sits} |
+
+## Problem
+
+{one paragraph, three lines at most — what is wrong today, for whom, and why
+it is worth fixing now}
+
+## Users
+
+| Who | Today | What changes |
+|---|---|---|
+| {role or persona} | {what they do now} | {what they can do after} |
+
+## Goals and non-goals
+
+| Goal | Measured by |
+|---|---|
+| {outcome, not a feature} | {the metric row that proves it} |
+
+| Non-goal | Why excluded |
+|---|---|
+| {what this deliberately does not do} | {one line} |
+
+## Success metrics
+
+| Metric | Target | How measured |
+|---|---|---|
+| {what is counted} | {the number or state} | {where the reading comes from} |
+
+## Scope
+
+| In | Out |
+|---|---|
+| {a surface, flow, or platform this covers} | {the adjacent thing it does not} |
+
+## Open questions
+
+- {a question nobody has answered yet — or "none"}
+```
+
+The PRD is the one concern file written *before* the design: it says why the
+feature exists and for whom, and `decisions.md` says how it was chosen. The
+section set is fixed — these six headings, in this order — because
+`discovery` writes them from its requirements card and `preflight`'s drift
+check reads **Scope** and the **Non-goal** table as claims: work that lands
+in the Out column, or inside a non-goal, is drift. Write the Out column as
+things someone might plausibly build — an exclusion nobody would attempt
+checks nothing.
+
+**An empty section is an open question, not a blank to fill.** When nobody
+has stated the users or a metric, the section says so under *Open questions*
+in plain words. A PRD whose metrics were invented to complete the table is
+worse than one that admits it has none. Content from a document the user
+brought that fits none of the six sections also lands under *Open questions*,
+in its original wording.
+
+---
+
 ## decisions.md
 
 ```markdown

package/skills/workflow/SKILL.md

@@ -78,7 +78,8 @@ Every tier ends with `preflight` then `finalize` — no exceptions.
    Match the task subject to a spec dir (fuzzy kebab-case: "checkout flow" →
    `specs/checkout-flow`). If found, read `index.md`, then load by task type —
    bug/debug → `quirks.md`, `api.md`, `fields.md`; refactor → `implementation.md`,
-   `decisions.md`; new feature → `decisions.md`, `api.md`, `fields.md`. Carry this
+   `decisions.md`; new feature → `prd.md`, `decisions.md`, `api.md`, `fields.md`
+   (any of these the spec does not have is skipped silently). Carry this
    context through; don't re-read mid-task. No spec → proceed without comment.
 3. **Confirm with the user.** State the inferred tier + a one-sentence reason. If a
    spec was loaded, mention it and offer the companion: "Found spec for