@danmoisan/drm-copilot-mcp 1.0.10 → 1.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danmoisan/drm-copilot-mcp",
-  "version": "1.0.10",
+  "version": "1.0.13",
   "description": "Stdio MCP server exposing drm-copilot repo-automation tools.",
   "license": "MIT",
   "type": "commonjs",

package/resources/claude-customizations/.claude/agents/epic-orchestrator.md

@@ -63,7 +63,7 @@ On every invocation:
    `git branch`, and `gh pr view --json state,mergedAt,headRefOid` per the `epic-orchestrate`
    skill's resume procedure, not from in-memory notifications alone).
 5. If no checkpoint exists or the objective is new, begin from manifest parsing
-   (`docs/features/epics/<epic-slug>/epic-plan.md`).
+   (`docs/features/epics/<epic-slug>/epic.md`).
 
 ## Delegation Model
 
@@ -112,8 +112,9 @@ route's required names from `config/orchestration-routing.json`.
 Maintain `docs/features/epics/<epic-slug>/epic-status.md` as a human-readable projection of the
 epic checkpoint's `features[]` array, regenerated (not hand-edited) at epic kickoff, at every
 `merge_status` transition, at every wave transition, and at final integration-PR completion, per
-the `epic-orchestrate` skill's documentation-maintenance procedure. `epic-plan.md` itself (the
-manifest) is treated as static, human-authored input and is not rewritten by you.
+the `epic-orchestrate` skill's documentation-maintenance procedure. `epic.md` itself (the merged
+manifest + narrative source of truth) is treated as static, human-authored input and is not
+rewritten by you; `epic-status.md` is a generated projection only and is never hand-authored.
 
 ## Completion Requirements
 

package/resources/claude-customizations/.claude/hooks/persist-session-id.ps1

@@ -0,0 +1,153 @@
+<#
+.SYNOPSIS
+    SessionStart hook that persists the current Claude Code session id.
+
+.DESCRIPTION
+    Invoked by the Claude Code SessionStart hook event (registered in
+    .claude/settings.json). Reads the hook payload JSON from standard input,
+    falling back to the CLAUDE_HOOK_INPUT environment variable (the existing
+    SubagentStop-hook precedent), and extracts the 'session_id' field.
+
+    Persistence channel:
+      - When CLAUDE_ENV_FILE is set, appends the line
+        'CLAUDE_SESSION_ID=<id>' to that file. Variables persisted there are
+        exported to subsequent Bash tool commands in the session, which is how
+        this hook provisions the otherwise-unset CLAUDE_SESSION_ID variable.
+      - When CLAUDE_ENV_FILE is unset, writes the id to
+        .claude/state/current-session-id instead.
+
+    On malformed or empty input (missing/blank payload, unparseable JSON, or an
+    absent/blank session_id) the hook performs no write. It always exits 0 so a
+    SessionStart hook never blocks session start.
+
+.NOTES
+    Compatible with PowerShell 7+. Does not use Invoke-Expression.
+#>
+[CmdletBinding()]
+param()
+
+function Get-PersistSessionIdDecision {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $RawPayload,
+
+        [string] $EnvFilePath,
+
+        [Parameter(Mandatory)]
+        [string] $StateFilePath
+    )
+
+    $none = [ordered]@{ action = 'none'; sessionId = ''; path = '' }
+
+    if ([string]::IsNullOrWhiteSpace($RawPayload)) {
+        return $none
+    }
+
+    try {
+        $payload = $RawPayload | ConvertFrom-Json -ErrorAction Stop
+    } catch {
+        Write-Verbose "persist-session-id: ignoring unparseable payload: $($_.Exception.Message)"
+        return $none
+    }
+
+    $sessionId = $null
+    if ($null -ne $payload -and $payload.PSObject.Properties.Name -contains 'session_id') {
+        $sessionId = [string]$payload.session_id
+    }
+
+    if ([string]::IsNullOrWhiteSpace($sessionId)) {
+        return $none
+    }
+
+    if (-not [string]::IsNullOrWhiteSpace($EnvFilePath)) {
+        return [ordered]@{ action = 'env-file'; sessionId = $sessionId; path = $EnvFilePath }
+    }
+
+    return [ordered]@{ action = 'state-file'; sessionId = $sessionId; path = $StateFilePath }
+}
+
+function Invoke-PersistSessionIdHook {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $RawPayload,
+
+        [string] $EnvFilePath,
+
+        [Parameter(Mandatory)]
+        [string] $StateFilePath,
+
+        [scriptblock] $AppendLine = {
+            param([string] $Path, [string] $Line)
+            Add-Content -Path $Path -Value $Line -Encoding utf8
+        },
+
+        [scriptblock] $WriteStateFile = {
+            param([string] $Path, [string] $Content)
+            Set-Content -Path $Path -Value $Content -Encoding utf8 -NoNewline
+        },
+
+        [scriptblock] $EnsureDirectory = {
+            param([string] $Path)
+            if (-not (Test-Path -Path $Path)) {
+                New-Item -ItemType Directory -Path $Path -Force | Out-Null
+            }
+        }
+    )
+
+    $decision = Get-PersistSessionIdDecision -RawPayload $RawPayload -EnvFilePath $EnvFilePath -StateFilePath $StateFilePath
+
+    switch ($decision.action) {
+        'env-file' {
+            & $AppendLine $decision.path ("CLAUDE_SESSION_ID={0}" -f $decision.sessionId)
+        }
+        'state-file' {
+            $stateDir = Split-Path -Path $decision.path -Parent
+            if ($stateDir) {
+                & $EnsureDirectory $stateDir
+            }
+            & $WriteStateFile $decision.path $decision.sessionId
+        }
+        default {
+            # 'none': malformed or empty input; perform no write.
+        }
+    }
+
+    return $decision
+}
+
+function Read-HookPayload {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [scriptblock] $ReadStandardInput = { [Console]::In.ReadToEnd() },
+
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $FallbackPayload = $env:CLAUDE_HOOK_INPUT
+    )
+
+    $raw = ''
+    try {
+        $raw = & $ReadStandardInput
+    } catch {
+        $raw = ''
+    }
+
+    if ([string]::IsNullOrWhiteSpace($raw)) {
+        return $FallbackPayload
+    }
+
+    return $raw
+}
+
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+$rawPayload = Read-HookPayload
+$stateFilePath = Join-Path -Path (Get-Location).Path -ChildPath '.claude/state/current-session-id'
+Invoke-PersistSessionIdHook -RawPayload $rawPayload -EnvFilePath $env:CLAUDE_ENV_FILE -StateFilePath $stateFilePath | Out-Null
+
+exit 0

package/resources/claude-customizations/.claude/settings.json

@@ -22,6 +22,7 @@
       "mcp__drm-copilot__new_active_feature_folder",
       "mcp__drm-copilot__validate_orchestration_artifacts",
       "mcp__drm-copilot__resolve_atomic_plan_prompt",
+      "mcp__drm-copilot__render_subagent_tree",
       "Agent(atomic-planner)",
       "Agent(atomic-executor)",
       "Agent(feature-review)",
@@ -55,6 +56,8 @@
       "Skill(invoke-powershell-engineer *)",
       "Skill(translate-copilot-to-claude *)",
       "Skill(execute-hard-lock *)",
+      "Skill(identify-session-id *)",
+      "Skill(show-my-agent-tree *)",
       "Edit(/.claude/skills/execute-hard-lock/**)",
       "Edit(/.claude/skills/feature-review-workflow/**)",
       "Edit(/.claude/skills/csharp-qa-gate/**)"
@@ -71,6 +74,16 @@
     ]
   },
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File .claude/hooks/persist-session-id.ps1"
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Bash",

package/resources/claude-customizations/.claude/skills/epic-orchestrate/SKILL.md

@@ -22,10 +22,12 @@ Before proceeding, `epic-orchestrator` must:
 
 ## Epic Dependency Manifest
 
-The epic manifest is Markdown with YAML frontmatter, at
-`docs/features/epics/<epic-slug>/epic-plan.md`. The frontmatter carries the fields that must be
-parsed deterministically; the Markdown body below the frontmatter carries free-text epic
-narrative (goal, scope, non-goals) that is not machine-parsed.
+The epic manifest is the YAML frontmatter of the single epic home
+`docs/features/epics/<epic-slug>/epic.md`. `epic.md` is the merged source of truth: its
+frontmatter carries the fields that must be parsed deterministically, and the Markdown body
+below the frontmatter carries the single free-text epic narrative (goal, scope, non-goals,
+shared design, decomposition) that is not machine-parsed. `epic.md` is also the source from
+which the epic GitHub issue body is generated.
 
 Frontmatter schema:
 
@@ -34,19 +36,37 @@ Frontmatter schema:
 epic: <epic-slug>
 integration_branch: epic/<epic-slug>-integration
 created_at: <iso8601>
+# Optional additive SAFe-style intent block. Omit the whole block when unused; when
+# present, epic_type and business_outcome_hypothesis are required and
+# leading_indicators / nfrs are optional lists of strings.
+intent:
+  epic_type: <business | enabler>
+  business_outcome_hypothesis: <measurable outcome the epic is expected to move>
+  leading_indicators: [<early validation signal>, ...]
+  nfrs: [<non-functional requirement>, ...]
 features:
-  - feature_folder: <feature-folder-basename>
-    issue_num: <int>
-    depends_on: [<feature-folder-basename>, ...]
+  - issue_num: <int>
+    feature_folder: <resolvable-hint-basename>
+    depends_on: [<upstream-issue_num>, ...]
 ---
 ```
 
-- `feature_folder` is the canonical identifier: the exact active-feature-folder basename,
-  matching the vocabulary already used by the per-feature checkpoint's `feature-folder` field.
-- `depends_on` is an array of `feature_folder` values that must each already exist as another
-  entry in `features[]`. A `depends_on` entry that does not resolve to a defined `feature_folder`,
-  or a duplicate `feature_folder` value, is a malformed manifest and is rejected before epic
-  kickoff as a synthetic Blocking finding — `epic-orchestrator` does not guess.
+- `issue_num` is the primary key: the stable GitHub issue number for the child feature. The
+  DAG is keyed by `issue_num`, so it does not drift when a child is promoted from `active/` to
+  `completed/`.
+- `feature_folder` is a resolvable hint, not a stable identifier. It may resolve to a concrete
+  path under `docs/features/active/<basename>` or `docs/features/completed/<basename>`; a
+  lifecycle prefix is stripped to the basename during resolution.
+- `depends_on` is an array of `issue_num` values (legacy manifests may still use
+  `feature_folder` basenames). Each entry must resolve — via the union index of the
+  `issue_num` set plus the `feature_folder` set — to another entry in `features[]`. A
+  `depends_on` entry that does not resolve, or a duplicate `feature_folder` value, is a
+  malformed manifest and is rejected before epic kickoff as a synthetic Blocking finding —
+  `epic-orchestrator` does not guess.
+- The optional `intent` block is additive and presence-gated: when present it is validated
+  (`epic_type` in {business, enabler}, non-empty `business_outcome_hypothesis`, string-list
+  `leading_indicators` / `nfrs`); when absent, validation is byte-identical to a manifest
+  without it.
 
 ## Wave Assignment
 
@@ -137,10 +157,14 @@ When `epic-orchestrator` kicks off a feature with a non-empty `depends_on`, the
 includes one literal citation line per dependency, appended after the epic-mode kickoff line
 above:
 
-> `Upstream context for <feature_folder>: depends on <dep_feature_folder> (spec: docs/features/active/<dep_feature_folder>/spec.md — or docs/features/completed/<dep_feature_folder>/spec.md if already promoted to completed; plan: docs/features/active/<dep_feature_folder>/plan.<ts>.md; merged as PR #<dep_pr_number>, commit <dep_merge_commit_sha>, into <integration_branch>).`
+> `Upstream context for <issue_num>: depends on <dep_issue_num> (spec: <dep_resolved_folder>/spec.md; plan: <dep_resolved_folder>/plan.<ts>.md; merged as PR #<dep_pr_number>, commit <dep_merge_commit_sha>, into <integration_branch>).`
 
-`epic-orchestrator` resolves the concrete `<dep_...>` values from its own checkpoint's
-`features[]` records for each dependency before emitting the line, so the dependent feature's own
+`epic-orchestrator` resolves each dependency by its stable `issue_num` against its own
+checkpoint's `features[]` records, and resolves `<dep_resolved_folder>` to the dependency's
+concrete `feature_folder` path — under `docs/features/active/` or `docs/features/completed/`
+depending on the dependency's current lifecycle state at emit time — before emitting the line.
+Because the DAG is keyed by `issue_num`, no active→completed path-drift workaround is needed: the
+concrete path is resolved from the checkpoint's current state, so the dependent feature's own
 `orchestrator`/`atomic-planner` is told exactly which upstream artifacts are relevant rather than
 being expected to rediscover prior design decisions from the diff alone.
 
@@ -207,12 +231,13 @@ child worktree) issues `git worktree remove <worktree_path>`, gated by
 
 ## Documentation Maintenance Boundaries
 
-`epic-plan.md` (the manifest) and `epic-status.md` (a separate, epic-orchestrator-maintained
-status document) are kept distinct. `epic-plan.md`'s frontmatter is the human-authored, largely
-static input; automatic epic decomposition is out of scope, so this file is not repeatedly
-rewritten. `epic-orchestrator` instead maintains
-`docs/features/epics/<epic-slug>/epic-status.md`, regenerated (not hand-edited) from the epic
-checkpoint at each of the following boundaries, not only at final completion:
+`epic.md` (the merged manifest + narrative source of truth) and `epic-status.md` (a separate,
+epic-orchestrator-maintained status document) are kept distinct. `epic.md`'s frontmatter is the
+human-authored, largely static input; automatic epic decomposition is out of scope, so this
+file is not repeatedly rewritten. `epic-status.md` is a generated projection only: it is
+regenerated (never hand-authored) from the epic checkpoint and is never the source of the DAG.
+`epic-orchestrator` maintains `docs/features/epics/<epic-slug>/epic-status.md`, regenerated from
+the epic checkpoint at each of the following boundaries, not only at final completion:
 
 - Epic kickoff — initial status table seeded from the manifest (one row per feature: wave,
   status `not_started`).
@@ -229,12 +254,14 @@ checkpoint JSON remains the durable, machine-authoritative source.
 ## Epic-Level Checkpoint
 
 `artifacts/orchestration/epic-orchestrator-state.json` carries `objective`, `route_id: "epic"`,
-`epic_feature_folder`, `epic_manifest_path`, `epic_status_doc_path`, `integration_branch`,
+`epic_feature_folder`, `epic_manifest_path` (which points at
+`docs/features/epics/<epic-slug>/epic.md`), `epic_status_doc_path`, `integration_branch`,
 `completed_steps`, `next_step`, `last_updated`, `current_wave`, `waves[]`, `features[]`,
 `epic_merge_pr`, and the three receipt arrays (`delegation_receipts[]`, `skill_receipts[]`,
 `mcp_call_receipts[]`) — the full schema is defined in `spec.md` §6 of this feature. The
 `merge_status` enum is: `not_started`, `worktree_created`, `pr_open`, `ci_green`,
-`merge_conflict`, `blocked_conflict_loop_limit`, `merged`, `worktree_removed`.
+`merge_conflict`, `blocked_conflict_loop_limit`, `merged`, `worktree_removed`. The optional
+`intent` object (projection of the `epic.md` intent block) is validated presence-gated.
 
 Every field needed to re-derive state durably on resume (`worktree_path`, `branch_name`,
 `pr_number`, `merge_status`) is re-derivable from `git worktree list --porcelain`, `git branch`,

package/resources/claude-customizations/.claude/skills/identify-session-id/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: identify-session-id
+description: Resolve the current Claude Code session id (the root transcript filename stem) without human input, using an ordered fallback chain, and report which source supplied it. Use before any workflow that needs the running session's id (for example show-my-agent-tree).
+allowed-tools:
+  - Read
+  - Bash
+---
+
+# Identify Session Id
+
+Resolve the current session's id — the root transcript filename stem under
+`~/.claude/projects/<encoded-workspace>/` — without asking the human. Try the
+sources in order and stop at the first that yields a non-empty id. Always
+report which source was used.
+
+## Resolution Order
+
+1. **Environment variable (primary).** Read `CLAUDE_SESSION_ID` from the
+   environment with a single command, e.g.:
+   - Bash: `printf '%s' "$CLAUDE_SESSION_ID"`
+   - pwsh: `pwsh -NoProfile -Command 'Write-Output $env:CLAUDE_SESSION_ID'`
+
+   This variable is provisioned by the SessionStart hook
+   `.claude/hooks/persist-session-id.ps1` through the `CLAUDE_ENV_FILE`
+   channel. If it is non-empty, use it and report source `env:CLAUDE_SESSION_ID`.
+
+2. **State file (secondary).** Read `.claude/state/current-session-id`
+   (written by the same hook when `CLAUDE_ENV_FILE` is unset). If it exists and
+   is non-empty, use its trimmed contents and report source
+   `.claude/state/current-session-id`.
+
+3. **Newest transcript (tertiary heuristic).** List the root `*.jsonl` files
+   directly under `~/.claude/projects/<encodeWorkspacePath(cwd)>/` (the encoding
+   replaces every path separator and `:` with `-`), pick the one with the
+   newest modification time, and use its filename stem (without `.jsonl`).
+   Report source `newest-mtime transcript` and note that this heuristic can
+   pick the wrong sibling only when multiple concurrent sessions share one
+   workspace path.
+
+## Output
+
+Report the resolved session id and the source that supplied it, for example:
+`session_id = <id> (source: env:CLAUDE_SESSION_ID)`. If every source is empty,
+state that the session id could not be resolved and which sources were checked.

package/resources/claude-customizations/.claude/skills/show-my-agent-tree/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: show-my-agent-tree
+description: Render the current session's subagent call tree and print it in the assistant reply. Use when the user asks to "show my agent tree" or otherwise wants to see the subagent hierarchy of the running session.
+allowed-tools:
+  - Read
+  - Bash
+  - mcp__drm-copilot__render_subagent_tree
+---
+
+# Show My Agent Tree
+
+Render the subagent call tree for the current session and print it directly in
+the assistant reply. This works identically in normal turns and in `/btw`
+side-conversations and needs no VS Code host API.
+
+## Flow
+
+1. **Resolve the session id.** Follow the `identify-session-id` skill to obtain
+   the current session id and note which source supplied it.
+
+2. **Call the MCP tool.** Invoke `mcp__drm-copilot__render_subagent_tree` with:
+   - `session_id`: the id resolved in step 1.
+   - `workspace_root`: an explicit absolute path to the current workspace root
+     (do not rely on the tool's default; pass it explicitly).
+
+   On success the tool returns `ok: true`, a `summary` naming the session id
+   and resolved transcript path, and a `rendered_tree` string.
+
+3. **Print the tree.** Output the `rendered_tree` value in the assistant reply
+   inside a fenced code block, so the hierarchy is legible. Include the
+   `summary` line above it for context.
+
+## Error Handling
+
+- If the tool returns `ok: false`, report the `summary` verbatim. An unknown
+  session id names the searched directories; a malformed session id names the
+  validation rule (`^[0-9A-Za-z-]{8,64}$`).
+- If `identify-session-id` cannot resolve an id, report that and do not call
+  the tool.

package/resources/claude-customizations/pack-manifests/core.json

@@ -28,6 +28,7 @@
     ".claude/hooks/enforce-pr-author-skill.ps1",
     ".claude/hooks/enforce-prd-feature-before-planner.ps1",
     ".claude/hooks/enforce-promotion-mcp-only.ps1",
+    ".claude/hooks/persist-session-id.ps1",
     ".claude/hooks/validate-bash.ps1",
     ".claude/hooks/validate-executor-output.ps1",
     ".claude/hooks/validate-feature-review-coverage.ps1",
@@ -55,6 +56,7 @@
     ".claude/skills/fill-feature-docs/SKILL.md",
     ".claude/skills/human-exception-runbook/example.runbook.md",
     ".claude/skills/human-exception-runbook/SKILL.md",
+    ".claude/skills/identify-session-id/SKILL.md",
     ".claude/skills/make-skill-template/SKILL.md",
     ".claude/skills/orchestrate/SKILL.md",
     ".claude/skills/policy-audit-template-usage/SKILL.md",
@@ -67,6 +69,7 @@
     ".claude/skills/review-epic/SKILL.md",
     ".claude/skills/review-feature/SKILL.md",
     ".claude/skills/review-staged/SKILL.md",
+    ".claude/skills/show-my-agent-tree/SKILL.md",
     ".claude/skills/skill-canonical-location-audit/SKILL.md",
     ".claude/skills/translate-copilot-to-claude/SKILL.md",
     ".claude/skills/update-status/SKILL.md",

package/resources/feature-templates/epic/epic-status.md

@@ -0,0 +1,20 @@
+<!--
+  GENERATED FILE — DO NOT HAND-AUTHOR.
+
+  epic-status.md is a generated projection of the epic checkpoint
+  (artifacts/orchestration/epic-orchestrator-state.json). It is regenerated by
+  the epic-orchestrator agent at each lifecycle boundary (epic kickoff, every
+  feature merge_status change, each wave transition, and final integration
+  merge). It is never the source of the dependency DAG and must never be edited
+  by hand — the manifest in epic.md and the epic checkpoint JSON are the
+  authoritative sources.
+-->
+
+# <epic-name> - Epic Status (generated)
+
+This document is regenerated from the epic checkpoint and must not be
+hand-authored. Any manual edit will be overwritten on the next regeneration.
+
+| feature_folder | issue_num | wave_number | merge_status | pr_url | merge_commit_sha |
+| --- | --- | --- | --- | --- | --- |
+| _(populated on epic kickoff from the manifest, then updated in place)_ | | | | | |

package/resources/feature-templates/epic/epic.md

@@ -0,0 +1,79 @@
+---
+# Epic manifest (source of truth).
+#
+# This YAML frontmatter is the machine-readable manifest for the epic: the
+# dependency DAG (parsed deterministically by the epic-orchestrator agent) and an
+# optional SAFe-style intent block. The Markdown body below the frontmatter is the
+# single human-authored narrative and is not machine-parsed.
+#
+# The DAG is keyed by stable `issue_num`. `feature_folder` is a resolvable hint
+# that may point into docs/features/active/<folder> OR docs/features/completed/<folder>;
+# it is not a stable identifier and changes when a child is promoted.
+epic: <epic-slug>
+integration_branch: epic/<epic-slug>-integration
+created_at: <iso8601>
+
+# Optional additive SAFe-style intent block. Omit the whole `intent` block when
+# not used; when present, `epic_type` and `business_outcome_hypothesis` are
+# required, and `leading_indicators` / `nfrs` are optional lists of strings.
+intent:
+  epic_type: <business | enabler>
+  business_outcome_hypothesis: <the measurable outcome this epic is expected to move>
+  leading_indicators:
+    - <early signal that the hypothesis is being validated>
+  nfrs:
+    - <non-functional requirement the epic must satisfy>
+
+# Manifest DAG. Primary key is `issue_num`. `depends_on` lists the `issue_num`
+# values of upstream siblings (each must be another entry in `features[]`).
+features:
+  - issue_num: <int>
+    feature_folder: <resolvable-hint-basename>
+    depends_on: []
+  - issue_num: <int>
+    feature_folder: <resolvable-hint-basename>
+    depends_on: [<upstream-issue_num>]
+---
+
+# <epic-name> - Epic
+
+- Issue: #<tracking-issue>
+- Owner: <name>
+- Last Updated: YYYY-MM-DD
+
+## Goal
+
+State the epic objective and the measurable outcomes. Keep it user/impact
+oriented, not implementation detail. This is the source from which the epic
+GitHub issue body is generated.
+
+## Scope
+
+Enumerate what is in scope for this epic. Reference the child features by their
+`issue_num` so the narrative and the manifest DAG stay aligned.
+
+## Non-Goals
+
+List what is explicitly out of scope so child features and reviewers do not
+scope-creep into adjacent work.
+
+## Shared Design
+
+Capture the cross-cutting design decisions every child feature must honor:
+
+- Shared behaviors/algorithms that must stay aligned across children.
+- Determinism/performance/compatibility guarantees.
+- Data/artifact locations, formats, or tooling expectations.
+- Quality gates (tests/lint/type-checks) required across all children.
+
+## Decomposition
+
+Describe the child features and their ordering. Each child keeps its own git
+branch/worktree and its own independent active/ -> completed/ lifecycle; this
+section is the human-readable projection of the `features[]` DAG above.
+
+- <Child feature A> (Issue #<id>) - wave 0
+- <Child feature B> (Issue #<id>) - depends on #<id>
+
+`epic-status.md` in this same directory is a generated projection of the epic
+checkpoint; it is never the source of the DAG and is never hand-authored.

package/resources/powershell/PoshQC/settings/pester.runsettings.psd1

@@ -44,6 +44,10 @@
             '.claude/hooks/enforce-pr-author-skill.ps1'
             '.claude/hooks/validate-orchestrator-output.ps1'
             '.claude/hooks/enforce-pr-author-skill.epic-base-branch.ps1'
+            # Issue #334 added this SessionStart hook that persists the current session id;
+            # measured here so the new production hook is not excluded from coverage. The
+            # test suite dot-sources the file (guarded body) so line attribution is valid.
+            '.claude/hooks/persist-session-id.ps1'
         )
         ExcludedPath          = @(
             '.claude/hooks/validate-feature-review-coverage.ps1' # Feature-review wrapper around repository evidence; not deterministic in normal unit-test execution.