mandrel 1.81.0 → 1.83.0

package/.agents/skills/core/hydrate-context/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: hydrate-context
 description: >-
-  Hydrate a Task or Story ticket into a structured ContextEnvelope (or the
-  legacy `{ prompt }` stdout wrapper). Reads the ticket body, parses
-  Feature / Epic hierarchy, fetches the Tech Spec + PRD, and assembles
+  Hydrate a Story ticket into a structured ContextEnvelope (or the
+  legacy `{ prompt }` stdout wrapper). Reads the ticket body, resolves the
+  parent Epic, embeds the sectioned Epic body (acceptance-table section
+  stripped), and assembles
   named sections with provenance and section-aware elision. Successor to
   the retired mandrel MCP `context.hydrate` tool.
 allowed_tools:
@@ -26,8 +27,12 @@ allowed_tools:
 ## Role
 
 Context aggregator. Resolves a ticket's hierarchy (Story → Epic)
-and stitches the linked planning artifacts into a
-single prompt the executor consumes.
+and stitches the Epic body — the single planning document, carrying the
+folded Tech Spec sections — plus the Story body into a
+single prompt the executor consumes. The Epic body is embedded with its
+`## Acceptance Table` managed section stripped (close-time reconciliation
+detail the executor does not need); there is no separate Tech Spec fetch
+(Story #4324).
 
 ## When to use
 

package/.agents/skills/core/knowledge-transfer/SKILL.md

@@ -69,8 +69,9 @@ differs (a plan vs. a diff); the *method* is identical.
 
 Before starting, identify the comprehension subject and gather it:
 
-- **A plan** — the Epic body, the linked PRD / Tech Spec context tickets, the
-  decomposition (Features/Stories with inline `acceptance[]` / `verify[]`),
+- **A plan** — the Epic body (whose managed sections carry the folded Tech
+  Spec and Acceptance Table), the
+  decomposition (Stories with inline `acceptance[]` / `verify[]`),
   and the dispatch/wave roadmap.
 - **A change** — a PR, a branch, or a working-tree diff. Read the diff, the
   PR/issue description, and the surrounding code the change touches.

package/.agents/skills/core/scope-triage/SKILL.md

@@ -32,7 +32,8 @@ description:
   wrong in the `epic` direction is cheap — the Phase 8.3 consolidation pass and
   the sizing validator catch an over-planned Story later. Being wrong in the
   `story` direction is expensive — a story-sized scope pushed through the full
-  Epic ceremony pays a PRD + Tech Spec + Acceptance Spec + Story backlog +
+  Epic ceremony pays a sectioned-Epic-body (Tech Spec + Acceptance Table) +
+  Story backlog +
   `epic/<id>` integration-branch tax for a degenerate one-Story output.
 - Keep the rubric prose **artifact-agnostic**. The thing under judgment may be a
   sharpened one-pager, an existing Epic body, or a draft Story — the rubric

package/.agents/skills/skills.index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-06-16T16:35:27.286Z",
+  "generatedAt": "2026-07-04T23:12:38.376Z",
   "generator": "generate-skills-index.js@1",
   "skills": [
     {
@@ -127,7 +127,7 @@
       "tier": "core",
       "category": "core",
       "path": ".agents/skills/core/epic-plan-consolidate/SKILL.md",
-      "description": "Run a holistic, pre-persist consolidation pass over the draft Story ticket array an Epic's decompose phase produced. Use during Phase 8 of `/plan`, after `epic-plan-decompose-author` writes `temp/epic-<Epic_ID>/tickets.json` and before `epic-plan-decompose.js` validates and persists it. Reconciles the draft against the Tech Spec \"Delivery Slicing\" target via scope-preserving operations only.",
+      "description": "Run a holistic, pre-persist consolidation pass over the draft Story ticket array an Epic's decompose phase produced. Use during Phase 8 of `/plan`, after `epic-plan-decompose-author` writes `temp/epic-<Epic_ID>/tickets.json` and before `epic-plan-decompose.js` validates and persists it. Reconciles the draft against the Tech Spec \"Delivery Slicing\" ceiling via scope-preserving operations only.",
       "policyCapsuleBullets": 9,
       "allowedTools": ["Read", "Write", "Bash"],
       "vendor": null
@@ -147,7 +147,7 @@
       "tier": "core",
       "category": "core",
       "path": ".agents/skills/core/epic-plan-premortem/SKILL.md",
-      "description": "Run a fresh-context, code-reading pre-mortem critic over the draft Story ticket array an Epic's decompose phase produced. Use during Phase 8 of `/plan`, after `epic-plan-decompose-author` / `epic-plan-consolidate` write `temp/epic-<Epic_ID>/tickets.json` and before `epic-plan-decompose.js` validates and persists it. Reads the PRD / Tech Spec AND the actual cited code surfaces, then emits predicted-rework findings before any GitHub write.",
+      "description": "Run a fresh-context, code-reading pre-mortem critic over the draft Story ticket array an Epic's decompose phase produced. Use during Phase 8 of `/plan`, after `epic-plan-decompose-author` / `epic-plan-consolidate` write `temp/epic-<Epic_ID>/tickets.json` and before `epic-plan-decompose.js` validates and persists it. Reads the sectioned Epic body AND the cited code surfaces, then emits predicted-rework findings before any GitHub write.",
       "policyCapsuleBullets": 7,
       "allowedTools": ["Read", "Write", "Bash", "Grep"],
       "vendor": null
@@ -157,8 +157,8 @@
       "tier": "core",
       "category": "core",
       "path": ".agents/skills/core/epic-plan-spec-author/SKILL.md",
-      "description": "Author the PRD, Tech Spec, Acceptance Spec markdown, and risk-verdict JSON for an Epic from the planner authoring context emitted by `epic-plan-spec.js --emit-context`. Use during Phase 7 of `/plan` when the host LLM needs to write the four artifacts before `epic-plan-spec.js` persists them.",
-      "policyCapsuleBullets": 12,
+      "description": "Author the Tech Spec, Acceptance Table markdown, and risk-verdict JSON for an Epic from the planner authoring context emitted by `epic-plan-spec.js --emit-context`. Use during Phase 7 of `/plan` when the host LLM needs to write the three artifacts before `epic-plan-spec.js` folds them into the Epic body's managed sections.",
+      "policyCapsuleBullets": 13,
       "allowedTools": ["Read", "Write", "Bash"],
       "vendor": null
     },
@@ -187,7 +187,7 @@
       "tier": "core",
       "category": "core",
       "path": ".agents/skills/core/hydrate-context/SKILL.md",
-      "description": "Hydrate a Task or Story ticket into a structured ContextEnvelope (or the legacy `{ prompt }` stdout wrapper). Reads the ticket body, parses Feature / Epic hierarchy, fetches the Tech Spec + PRD, and assembles named sections with provenance and section-aware elision. Successor to the retired mandrel MCP `context.hydrate` tool.",
+      "description": "Hydrate a Story ticket into a structured ContextEnvelope (or the legacy `{ prompt }` stdout wrapper). Reads the ticket body, resolves the parent Epic, embeds the sectioned Epic body (acceptance-table section stripped), and assembles named sections with provenance and section-aware elision. Successor to the retired mandrel MCP `context.hydrate` tool.",
       "policyCapsuleBullets": 7,
       "allowedTools": ["Read", "Bash"],
       "vendor": null
@@ -567,8 +567,8 @@
       "tier": "stack",
       "category": "qa",
       "path": ".agents/skills/stack/qa/qa-explore-driving/SKILL.md",
-      "description": "Conventions for agent-driven exploratory QA driving — how the agent itself drives a surface during `/qa-explore` (agent-led), as opposed to the human-led `/qa-assist`. Use when the agent explores a running app via the browser MCP (navigation-first, the default) or walks a static surface (the documented interim until consumer persona-seeding lands), under a strictly read-only capture invariant. The exploration procedure lives in `.agents/workflows/qa-explore.md`; this skill is the driving-conventions reference it leans on.",
-      "policyCapsuleBullets": 8,
+      "description": "Conventions for agent-driven exploratory QA driving — how the agent itself drives a surface during `/qa-explore` (agent-led), as opposed to the human-led `/qa-assist`. Use when the agent explores a running app via the browser MCP (navigation-first, the default) — including authenticated deployed surfaces reached through the resolved environment's sign-in seam — or walks a static surface (the documented interim where no seam resolves), under a strictly read-only capture invariant. The exploration procedure lives in `.agents/workflows/qa-explore.md`; this skill is the driving-conventions reference it leans on.",
+      "policyCapsuleBullets": 9,
       "allowedTools": null,
       "vendor": null
     },

package/.agents/skills/stack/qa/qa-explore-driving/SKILL.md

@@ -4,9 +4,10 @@ description:
   Conventions for agent-driven exploratory QA driving — how the agent itself
   drives a surface during `/qa-explore` (agent-led), as opposed to the
   human-led `/qa-assist`. Use when the agent explores a running app via the
-  browser MCP (navigation-first, the default) or walks a static surface (the
-  documented interim until consumer persona-seeding lands), under a strictly
-  read-only capture invariant. The exploration procedure lives in
+  browser MCP (navigation-first, the default) — including authenticated
+  deployed surfaces reached through the resolved environment's sign-in seam —
+  or walks a static surface (the documented interim where no seam resolves),
+  under a strictly read-only capture invariant. The exploration procedure lives in
   `.agents/workflows/qa-explore.md`; this skill is the driving-conventions
   reference it leans on.
 ---
@@ -16,9 +17,10 @@ description:
 ## Policy Capsule
 
 - Drive the running app **by default** through the browser MCP, navigation-first: start at a root and reach each surface only via UI affordances — never URL-jump to a deep link.
-- Treat **static driving** (reading source, routes, and rendered markup without a live runtime) as the **documented interim** method, chosen at Plan time when a live runtime is not reachable — never the silent fallback.
+- Resolve the target **environment** at Plan time (via `resolveQaEnvironment`) and record its name in the ledger; each environment keys its own `baseUrl`, `signInSeam`, and `allowWrites`.
+- Treat **static driving** (reading source, routes, and rendered markup without a live runtime) as the **documented interim** method, chosen at Plan time **only where no seam resolves** for the target environment — never the silent fallback.
 - Hold the **read-only capture invariant** absolutely: the agent makes no source edits and no product mutations while driving; the only write is appending to the `temp/qa/<sessionId>` ledger.
-- Authenticated driving depends on **consumer persona-seeding infrastructure that this Epic does not deliver**; without it, drive only the unauthenticated surface or fall back to static, and record the gap — never enter real credentials or fabricate a session.
+- Authenticated driving follows the resolved environment's **`signInSeam`**: sign in through a dev `url` seam (persona name substituted into the template) or a `skill` seam (a stored `credentialRef` read by the named sign-in skill), with **mandatory redaction** of all captured evidence. Never type real credentials inline or fabricate a session; where an environment resolves no seam, drive the unauthenticated surface or fall back to static and record the gap.
 - Pick the driving method explicitly in the Plan phase (drive vs. static) and record it in the ledger; do not switch methods mid-surface without a new Plan note.
 - Every phase transition and every GitHub write is HITL-gated; the agent drives and captures, but never files or promotes findings autonomously.
 - Broken navigation, a missing affordance, or a guard redirect loop is a **finding**, not a workaround — record it and move on; do not route around it with a direct URL.
@@ -65,15 +67,14 @@ state rather than an artifact of a deep link.
 
 ## 2. Static Driving — the Documented Interim
 
-Static driving is the **explicitly documented interim** method for when a live
-runtime is not reachable — most commonly because authenticated driving needs
-consumer persona-seeding infrastructure that does not yet exist (§ 4). It walks
-the surface from source, route definitions, and rendered markup rather than a
-running browser.
+Static driving is the **explicitly documented interim** method for when **no
+seam resolves** for the target environment — the resolved environment carries
+no `signInSeam` the agent can drive through (§ 4). It walks the surface from
+source, route definitions, and rendered markup rather than a running browser.
 
 - **Choose it at Plan time, never silently.** Static is a deliberate Plan-phase
-  decision recorded in the ledger ("method: static, reason: no reachable
-  authenticated runtime"), not an unannounced fallback the agent slips into
+  decision recorded in the ledger ("environment: preview, method: static,
+  reason: no seam resolves"), not an unannounced fallback the agent slips into
   when the browser MCP hiccups.
 - **It is interim, not equivalent.** Static driving cannot exercise real
   authorization, routing guards, or runtime console/network signal. Treat its
@@ -81,10 +82,10 @@ running browser.
   same coverage a driven pass would.
 - **Same read-only invariant.** Static driving reads source and routes; it makes
   no edits. The read-only capture invariant (§ 3) applies identically.
-- **Promote to driving when the runtime lands.** Static is the bridge until the
-  consumer's persona-seeding infrastructure (§ 4) makes authenticated driving
-  possible. When that lands, re-run the surface driven; do not leave a surface
-  permanently static when it could be driven.
+- **Promote to driving when a seam lands.** Static is the bridge until the
+  target environment resolves a `signInSeam` (§ 4) that makes driven
+  authenticated exploration possible. When that lands, re-run the surface
+  driven; do not leave a surface permanently static when it could be driven.
 
 ## 3. The Read-Only Capture Invariant
 
@@ -109,29 +110,42 @@ and the Epic's security considerations — it is not a soft preference.
   (ticket creation, promotion) happen only behind an operator confirmation gate.
   The agent never files or promotes findings autonomously.
 
-## 4. Authenticated Driving Depends on Consumer Infra (Not Delivered Here)
-
-Driving an **authenticated** surface requires signing in as a seeded persona.
-That seeding — provisioning a test persona with the right org, role, and data
-so the agent can reach a logged-in surface navigation-first — is **consumer
-persona-seeding infrastructure that this Epic does not deliver**. It is an
-explicit non-goal of the `/qa-explore` rebuild.
-
-- **Unauthenticated surface only, by default.** Without persona-seeding infra in
-  the consumer project, drive only the surface reachable without sign-in, or
-  fall back to static driving (§ 2) for the authenticated surface. Record the
-  gap in the ledger so the partial coverage is visible.
-- **Never enter real credentials.** The agent MUST NOT type real usernames,
-  passwords, or tokens to reach an authenticated surface, and MUST NOT fabricate
-  or forge a session. This is a hard security boundary, not a convenience to
+## 4. Authenticated Driving Follows the Per-Environment Seam
+
+Driving an **authenticated** surface requires signing in. The resolved target
+environment (via `resolveQaEnvironment`, § Policy Capsule) carries the
+`signInSeam` the agent drives through — the same discriminated-union shape
+`qa-harness` resolves via its contract. When a seam resolves, authenticated
+deployed surfaces are **driven**, not statically deferred.
+
+- **Drive the authenticated surface through the seam.** When the target
+  environment carries a `signInSeam`, sign in via that seam and then reach the
+  authenticated surface navigation-first — including authenticated **deployed**
+  hosts. The two seam kinds:
+  - **`kind: 'url'` (dev impersonation).** Substitute the persona **name** into
+    the seam's URL template and navigate there. The persona name is the sole
+    input; no per-persona auth material is read.
+  - **`kind: 'skill'` (procedural / credential).** Invoke the named consumer
+    sign-in skill, which reads a per-persona **`credentialRef`** — an indirect
+    handle to a stored credential, never an inline secret. Read the skill's
+    `SKILL.md` and follow it.
+- **Never enter real credentials inline.** The agent MUST NOT type real
+  usernames, passwords, or tokens to reach an authenticated surface, and MUST
+  NOT fabricate or forge a session. Sign-in flows only through the seam, which
+  consumes a persona name or a `credentialRef` indirection — never a
+  hand-typed secret. This is a hard security boundary, not a convenience to
   work around.
-- **The dependency is the consumer's to satisfy.** When a consumer wants driven
-  authenticated exploration, the consumer supplies a dev sign-in seam and seeded
-  personas (the same shape `qa-harness` resolves via its contract). Until then,
-  authenticated coverage is static or deferred — say which in the ledger.
-- **Surface the gap, don't paper over it.** A surface that could not be driven
-  because authenticated seeding is absent is itself a coverage signal worth
-  recording, not a silent skip.
+- **Redaction is mandatory.** Every captured evidence string — console,
+  network, headers — passes through the shared redaction path (§ 3) before it
+  reaches disk or GitHub; bearer tokens, session cookies, `Authorization`
+  headers, and PII are masked. Authenticated driving raises the stakes on
+  redaction, it does not relax it.
+- **Static only where no seam resolves.** When the target environment resolves
+  **no** `signInSeam`, drive only the unauthenticated surface or fall back to
+  static driving (§ 2), and record the gap in the ledger so the partial
+  coverage is visible. A surface that could not be driven because the
+  environment carries no seam is itself a coverage signal worth recording, not
+  a silent skip.
 
 ## 5. Cross-References
 

package/.agents/templates/epic-from-idea.md

@@ -16,6 +16,10 @@
 
 {{scope}}
 
+## User Stories
+
+{{userStories}}
+
 ## Acceptance Criteria
 
 {{acceptanceCriteria}}

package/.agents/workflows/audit-to-stories.md

@@ -118,8 +118,8 @@ Ask:
 > How would you like these `<M>` Stories created?
 >
 > - **Single Epic via `/plan`** **[Recommended]** — opens one Epic,
->   then chains into `/plan --idea` so the standard PRD / Tech Spec
->   / WBS authoring handles decomposition. Grouped Stories become the
+>   then chains into `/plan --idea` so the standard spec-and-WBS
+>   authoring handles decomposition. Grouped Stories become the
 >   seed for Phase 7 decomposition.
 > - **Individual standalone Stories** — opens one GitHub Issue per
 >   group directly, no Epic wrapper.

package/.agents/workflows/helpers/code-review.md

@@ -79,13 +79,15 @@ review yourself, honor the `depth` semantics above directly.
 
 1. Resolve `[TICKET_ID]` from `ticketId` (Story or Epic depending on `scope`).
 2. Resolve `[BASE_REF]` from `baseRef` and `[HEAD_REF]` from `headRef`.
-3. Fetch the `[TICKET_ID]` ticket and identify linked context tickets:
+3. Fetch the `[TICKET_ID]` ticket and resolve the planning context:
    - **Story scope** — read the parent Epic from the Story body, then load
-     the Epic's `context::prd` (PRD) and `context::tech-spec` (Tech Spec).
-   - **Epic scope** — load the Epic's `context::prd` (PRD) and
-     `context::tech-spec` (Tech Spec) directly from the Epic body.
-4. Read both the PRD and Tech Spec fully to understand the intended scope,
-   architectural decisions, and acceptance criteria.
+     the Epic body (including its `## User Stories` section and its folded
+     Tech Spec sections).
+   - **Epic scope** — read the Epic body directly; its managed sections
+     carry the Tech Spec.
+4. Read the Epic body fully (including its Tech Spec sections) to
+   understand the intended
+   scope, architectural decisions, and acceptance criteria.
 
 ## Step 1 — Automated Audit (Pre-Review)
 
@@ -120,7 +122,7 @@ before finalizing findings.
 
 ### Pillar 1: Spec Adherence
 
-Does the implementation match the PRD requirements and Tech Spec architecture?
+Does the implementation match the Epic's requirements and Tech Spec architecture?
 
 - Compare each completed Story/Task against its stated acceptance criteria.
 - Flag any undocumented deviations, missing features, or scope creep.
@@ -251,7 +253,7 @@ anything not fixed in-place.
      structured comment for the operator to triage in Step 5.
 2. **Leave the finding on the structured comment for Step 5.** Required
    when the finding falls into any of the following classes:
-   - `spec-deviation` — the change diverges from the PRD/Tech Spec.
+   - `spec-deviation` — the change diverges from the Epic/Tech Spec.
    - `secrets` — credentials, tokens, or PII surfaced in the diff.
    - `test-deletion` — coverage was removed without an explicit
      decision in the spec.
@@ -359,7 +361,7 @@ to the next phase of the parent workflow.
   the scope is set by the caller, and reviewing against the wrong base
   produces either a hollow review (too small a diff) or noise (too large a
   diff that includes unrelated history).
-- **Always** read the PRD and Tech Spec before reviewing code. Findings without
+- **Always** read the Epic body and Tech Spec before reviewing code. Findings without
   spec context are noise.
 - **Never** implement fixes unless the operator explicitly requests it. The
   default mode is read-only audit.