@danmoisan/drm-copilot-mcp 1.1.25 → 1.1.27

package/resources/claude-customizations/.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_preserve_merge_lib.sh

@@ -0,0 +1,234 @@
+#!/usr/bin/env bash
+# cleanup_worktrees_preserve_merge_lib.sh: sourceable staging-decision function group for
+# the preserve pass of the cleanup-worktrees tool. For each preserve record whose target
+# already exists as a regular file on the consolidation branch, it decides whether the
+# source may be copied, whether a three-way union merge may be staged instead, or whether
+# the record must be refused with ACTION|preserve-stage|<target-path>|REFUSED-WOULD-REGRESS.
+#
+# Sourcing contract: this library defines functions only and runs no work at source time.
+# It MUST be sourced before cleanup_worktrees_preserve_lib.sh, whose preserve_plan_one calls
+# preserve_merge_check_duplicate and preserve_merge_decide. Its own git calls go through
+# cleanup_wt_git, defined in cleanup_worktrees_enumerate_lib.sh.
+#
+# Phase-1 write exception. The preserve planning phase writes no index, ref, or working-tree
+# file. The one write it performs is the creation of unreferenced blob objects in the object
+# store: `git hash-object -w` hashes the two merge inputs and `git merge-file --object-id`
+# records the merged result. Nothing refers to those blobs unless the writing phase stages
+# the merged result, and an unreferenced blob is removed by the normal object pruning.
+#
+# Line-comparison rule. Every guard compares lines. Content is split with the
+# `while IFS= read -r line || [[ -n $line ]]` idiom, so an unterminated final line counts as
+# a line, and one trailing carriage return is stripped from each line before comparison, so
+# a CRLF working-tree file and its LF-normalized blob compare equal.
+#
+# No git call in this library passes -f or --force, and no process substitution is passed
+# to git as a file argument: native git on Windows cannot open an MSYS /dev/fd path.
+
+preserve_merge_split_lines() {
+	# Split one content string into the global array PRESERVE_MERGE_LINES under the
+	# line-comparison rule stated in the header. An empty string yields no line at all.
+	#
+	# Args: $1 = the content.
+	PRESERVE_MERGE_LINES=()
+	# The carriage return is held in a variable: ANSI-C quoting nested inside a
+	# double-quoted expansion is not interpreted consistently across bash versions.
+	local line cr=$'\r'
+	while IFS= read -r line || [[ -n $line ]]; do
+		PRESERVE_MERGE_LINES+=("${line%"$cr"}")
+	done < <(printf '%s' "${1-}")
+}
+
+preserve_merge_is_subsequence() {
+	# Return 0 when every line of the needle appears in the haystack in the same order, not
+	# necessarily adjacent, and 1 otherwise. An empty needle is a subsequence of anything.
+	#
+	# Args: $1 = needle content, $2 = haystack content.
+	local -a needle=() hay=()
+	preserve_merge_split_lines "${1-}"
+	needle=("${PRESERVE_MERGE_LINES[@]}")
+	preserve_merge_split_lines "${2-}"
+	hay=("${PRESERVE_MERGE_LINES[@]}")
+	local n=${#needle[@]} i=0 line
+	if ((n == 0)); then
+		return 0
+	fi
+	for line in "${hay[@]}"; do
+		if [[ $line == "${needle[$i]}" ]]; then
+			i=$((i + 1))
+			if ((i == n)); then
+				return 0
+			fi
+		fi
+	done
+	return 1
+}
+
+preserve_merge_extra_within() {
+	# Guard G3. Return 0 when multiset(merged) minus multiset(main) is contained in
+	# multiset(worktree) minus multiset(base), and 1 otherwise. A merged line that main does
+	# not carry is admitted only as one of the worktree's own additions, so a base line that
+	# main deleted and the merge re-emitted is refused. Counts are kept per line, so a line
+	# the worktree added once may appear at most once beyond main's own copies.
+	#
+	# Keys carry a fixed prefix because bash refuses an empty associative-array subscript,
+	# and a blank line is an ordinary line.
+	#
+	# Args: $1 = merged content, $2 = main content, $3 = worktree content, $4 = base content.
+	local -A extra=() added=()
+	local line key
+	preserve_merge_split_lines "${1-}"
+	for line in "${PRESERVE_MERGE_LINES[@]}"; do
+		key="k$line"
+		extra["$key"]=$((${extra["$key"]:-0} + 1))
+	done
+	preserve_merge_split_lines "${2-}"
+	for line in "${PRESERVE_MERGE_LINES[@]}"; do
+		key="k$line"
+		extra["$key"]=$((${extra["$key"]:-0} - 1))
+	done
+	preserve_merge_split_lines "${3-}"
+	for line in "${PRESERVE_MERGE_LINES[@]}"; do
+		key="k$line"
+		added["$key"]=$((${added["$key"]:-0} + 1))
+	done
+	preserve_merge_split_lines "${4-}"
+	for line in "${PRESERVE_MERGE_LINES[@]}"; do
+		key="k$line"
+		added["$key"]=$((${added["$key"]:-0} - 1))
+	done
+	for key in "${!extra[@]}"; do
+		if ((${extra["$key"]} > ${added["$key"]:-0} && ${extra["$key"]} > 0)); then
+			return 1
+		fi
+	done
+	return 0
+}
+
+preserve_merge_refuse() {
+	# Refuse one record: emit ACTION|preserve-stage|<target-path>|REFUSED-WOULD-REGRESS on
+	# stdout, a `cleanup-worktrees: refused` diagnostic naming the reason on stderr, set
+	# PRESERVE_EXIT to 1, and return 1. A refusal is not a hard stop: the remaining records
+	# are still planned and the pass exits 1.
+	#
+	# Args: $1 = target_path, $2 = the reason, which begins with the failed guard's token.
+	printf 'ACTION|preserve-stage|%s|REFUSED-WOULD-REGRESS\n' "${1-}"
+	printf 'cleanup-worktrees: refused %s: %s\n' "${1-}" "${2-}" >&2
+	# Read by preserve_plan and run_preserve across a source boundary shellcheck does not
+	# follow, so SC2034 reports it unused here; the suppression is line-scoped.
+	# shellcheck disable=SC2034
+	PRESERVE_EXIT=1
+	return 1
+}
+
+preserve_merge_check_duplicate() {
+	# Refuse a record whose target_path an earlier record of the same pass already named. A
+	# target counts as seen as soon as a record reaches this check, whatever that record's
+	# later outcome, so the first record keeps the target and every later one is refused.
+	# The seen set is the newline-delimited global PRESERVE_SEEN_TARGETS, which preserve_plan
+	# resets at the start of every pass.
+	#
+	# Args: $1 = target_path. Returns 0 when the target is new, 1 when it was refused.
+	local tgt=${1-}
+	local seen=${PRESERVE_SEEN_TARGETS:-$'\n'}
+	if [[ $seen == *$'\n'"$tgt"$'\n'* ]]; then
+		preserve_merge_refuse "$tgt" "duplicate-target: an earlier record in this pass names the same target_path"
+		return 1
+	fi
+	PRESERVE_SEEN_TARGETS="$seen$tgt"$'\n'
+	return 0
+}
+
+preserve_merge_resolve_base() {
+	# Echo the blob id of the source file at the merge base of the worktree HEAD and the
+	# consolidation HEAD, or return 1 when no base is available. The base is unavailable
+	# when source_path differs from target_path (no git call is made in that case), when
+	# the worktree HEAD does not resolve, when the two HEADs have no merge base, or when the
+	# file is absent at the merge base. An empty answer from git counts as unavailable.
+	#
+	# Args: $1 = worktree path, $2 = source_path, $3 = target_path, $4 = consolidation path.
+	local wt=${1-} src=${2-} tgt=${3-} cwt=${4-} head="" mb="" oid=""
+	if [[ $src != "$tgt" ]]; then
+		return 1
+	fi
+	head=$(cleanup_wt_git -C "$wt" rev-parse --verify --quiet HEAD) || return 1
+	[[ -n $head ]] || return 1
+	mb=$(cleanup_wt_git -C "$cwt" merge-base "$head" HEAD) || return 1
+	[[ -n $mb ]] || return 1
+	oid=$(cleanup_wt_git -C "$cwt" rev-parse --verify --quiet "$mb:$src") || return 1
+	[[ -n $oid ]] || return 1
+	printf '%s\n' "$oid"
+}
+
+preserve_merge_guard_b() {
+	# Guard (b), the fallback when no merge base is available: admit a whole-file copy only
+	# when main's version is a line-subsequence of the source, so no main line is lost.
+	#
+	# Args: $1 = target_path, $2 = main content, $3 = source content.
+	if preserve_merge_is_subsequence "${2-}" "${3-}"; then
+		PRESERVE_STAGE_MODE="copy"
+		return 0
+	fi
+	preserve_merge_refuse "${1-}" "guard-b: the target holds lines the source lacks"
+	return 1
+}
+
+# PRESERVE_STAGE_MODE and PRESERVE_STAGE_OID are read by preserve_plan_one across a source
+# boundary shellcheck does not follow, so SC2034 reports them unused; the suppression is
+# scoped to this one function.
+# shellcheck disable=SC2034
+preserve_merge_decide() {
+	# Decide how one record is staged. Sets PRESERVE_STAGE_MODE to `copy` or `merge` and
+	# PRESERVE_STAGE_OID to the merged blob id (empty for `copy`), or refuses the record.
+	#
+	#   - target not a regular file: `copy`, with no git call at all;
+	#   - `untracked` record, or `modified` record with no merge base: guard (b);
+	#   - `modified` record with a merge base: G1 (the worktree change is insertion-only),
+	#     then a `git merge-file --union --object-id` merge, then G2 (every main line
+	#     survives) and G3 (no line beyond the worktree's own additions); `merge` on success.
+	#
+	# The source and target are read with plain file I/O. The base and merged contents are
+	# read from the object store with `cat-file blob`.
+	#
+	# Args: $1 = change_class, $2 = worktree path, $3 = source_path, $4 = target_path,
+	# $5 = consolidation path. Returns 0 when the record may be staged, 1 when it was refused.
+	local cls=${1-} wt=${2-} src=${3-} tgt=${4-} cwt=${5-}
+	PRESERVE_STAGE_MODE="copy"
+	PRESERVE_STAGE_OID=""
+	if [[ ! -f "$cwt/$tgt" ]]; then
+		return 0
+	fi
+	local main_c wt_c base_oid base_c main_oid wt_oid merged_oid merged_c mrc=0
+	main_c=$(<"$cwt/$tgt")
+	wt_c=$(<"$wt/$src")
+	if [[ $cls == "untracked" ]] || ! base_oid=$(preserve_merge_resolve_base "$wt" "$src" "$tgt" "$cwt"); then
+		preserve_merge_guard_b "$tgt" "$main_c" "$wt_c"
+		return
+	fi
+	base_c=$(cleanup_wt_git -C "$cwt" cat-file blob "$base_oid") ||
+		{ preserve_merge_refuse "$tgt" "G1: the base blob could not be read" || return 1; }
+	if ! preserve_merge_is_subsequence "$base_c" "$wt_c"; then
+		preserve_merge_refuse "$tgt" "G1: the worktree removed or changed a base line"
+		return 1
+	fi
+	main_oid=$(cleanup_wt_git -C "$cwt" hash-object -w --path="$tgt" -- "$tgt") || main_oid=""
+	wt_oid=$(cleanup_wt_git -C "$wt" hash-object -w --path="$tgt" -- "$src") || wt_oid=""
+	merged_oid=$(cleanup_wt_git -C "$cwt" merge-file --union --object-id "$main_oid" "$base_oid" "$wt_oid") || mrc=$?
+	if ((mrc != 0)) || [[ -z $main_oid || -z $wt_oid || -z $merged_oid ]]; then
+		preserve_merge_refuse "$tgt" "merge-file rc=$mrc: no merged blob was produced"
+		return 1
+	fi
+	merged_c=$(cleanup_wt_git -C "$cwt" cat-file blob "$merged_oid") ||
+		{ preserve_merge_refuse "$tgt" "G2: the merged blob could not be read" || return 1; }
+	if ! preserve_merge_is_subsequence "$main_c" "$merged_c"; then
+		preserve_merge_refuse "$tgt" "G2: the merged result lost a main line"
+		return 1
+	fi
+	if ! preserve_merge_extra_within "$merged_c" "$main_c" "$wt_c" "$base_c"; then
+		preserve_merge_refuse "$tgt" "G3: the merged result carries a line the worktree did not add"
+		return 1
+	fi
+	PRESERVE_STAGE_MODE="merge"
+	PRESERVE_STAGE_OID=$merged_oid
+	printf 'cleanup-worktrees: merged %s\n' "$tgt" >&2
+	return 0
+}

package/resources/claude-customizations/.claude/skills/csharp-qa-gate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: csharp-qa-gate
-description: Final QA gate for C# changes. Executes the full CSharpier -> .NET Analyzers -> Nullable Analysis -> xUnit toolchain (with architecture tests), compares against a captured baseline, enforces zero-regression deltas, and produces the required reporting block before the agent declares the change complete.
+description: Final QA gate for C# changes. Executes the full CSharpier -> .NET Analyzers -> Nullable Analysis -> MSTest toolchain (with architecture tests), compares static tool results against the static baseline, reads test and coverage results from the single gate run, and produces the required reporting block before the agent declares the change complete.
 ---
 
 # C# QA Gate
@@ -12,14 +12,14 @@ Canonical procedure for the Phase D final quality gate that every C# change must
 Use this skill when:
 
 - `csharp-typed-engineer` is about to declare a change complete.
-- An executor has finished applying a planned batch and must verify zero regressions against the baseline captured in Phase A.
+- An executor has finished applying a planned batch and must verify the static tools against the static baseline recorded in Phase A, and the tests in the single gate run.
 - A reviewer needs to confirm the toolchain was actually run and produced a clean pass.
 
 ## Required Inputs
 
 Before invoking this gate, the agent must have:
 
-- a baseline record produced in Phase A, containing analyzer findings, compiler/nullable diagnostics, xUnit pass/fail status, and per-file coverage status for the in-scope files,
+- a static baseline record produced in Phase A, containing analyzer findings and compiler/nullable diagnostics for the in-scope files,
 - the exact list of touched production and test files,
 - a clean working tree (all planned edits committed to the working copy).
 
@@ -48,36 +48,35 @@ Analyzer settings (`AnalysisLevel`, `AnalysisMode`, `TreatWarningsAsErrors`, `Nu
 
 If the environment prevents running any tool, stop and report the change as **unverified**. Do not declare completion.
 
-## Delta Requirements (Zero-Regression Hard Gate)
+## Gate Requirements (Hard Gate)
 
-Compare the final results to the Phase A baseline. All of the following must hold:
+Compare the final static tool results to the static baseline recorded in Phase A, and read test and coverage results from the single gate run. All of the following must hold:
 
 - **Analyzer delta**: 0 new findings across the repository.
 - **Compiler / nullable delta**: 0 new diagnostics across the repository.
-- **xUnit delta**: 0 new failing tests.
-- **Architecture-test delta**: 0 new failing facts in the `*.ArchitectureTests` project.
-- **Per-file coverage delta**: coverage for every touched file is greater than or equal to the baseline for that file.
-- **Overall coverage delta** (when the repo enforces it): overall coverage is greater than or equal to the baseline.
+- **MSTest gate**: zero failures in the single gate run.
+- **Architecture tests**: zero failures in the `*.ArchitectureTests` project.
+- **Per-file coverage**: every changed file meets the coverage thresholds, read from the single gate run, and new behavior is tested.
 - **New modules, classes, or methods**: coverage >= 90% for each new unit introduced in the batch.
 
-If any delta check fails, the agent must revert or fix immediately and rerun the full toolchain. Do not proceed to reporting until all deltas are clean.
+If any check fails, the agent must revert or fix immediately and rerun the full toolchain. Do not proceed to reporting until all checks are clean.
 
 ## Required Reporting Block
 
 Every completion response must include the following sections:
 
 1. **Scope** — exact file list touched in this change.
-2. **Baseline** — analyzer, compiler/nullable, xUnit, and coverage status recorded in Phase A.
+2. **Baseline** — analyzer and compiler/nullable findings recorded in Phase A.
 3. **Plan** — design and test-strategy summary, referencing the approved plan.
 4. **Diffs** — patch-style or full-file replacements for scoped files only.
-5. **QA Gate Results** — analyzer, compiler/nullable, xUnit, architecture-test, and coverage deltas. If any step could not be run, mark the corresponding line **unverified** and state why.
+5. **QA Gate Results** — analyzer and compiler/nullable deltas, failures in the single gate run and the architecture tests, and per-file coverage against the thresholds. If any step could not be run, mark the corresponding line **unverified** and state why.
 
 ## Evidence Storage
 
 Persist toolchain output according to `evidence-and-timestamp-conventions`:
 
-- store baseline outputs under `<FEATURE>/evidence/baseline/<timestamp>/`,
-- store post-change outputs under `<FEATURE>/evidence/qa-gates/<timestamp>/`,
+- store static baseline outputs under `<FEATURE>/evidence/baseline/<timestamp>/`,
+- store final gate outputs under `<FEATURE>/evidence/qa-gates/<timestamp>/`,
 - use ISO-8601 UTC timestamps in folder names.
 
 This location is canonical per evidence-and-timestamp-conventions and is not overridable.
@@ -89,4 +88,4 @@ The evidence paths must be referenced in the agent's completion message to satis
 
 - Do not disable, skip, or narrow any step of the toolchain to reach a clean result.
 - Do not add analyzer suppressions, `#pragma warning disable`, `#nullable disable`, or test `[Ignore]` attributes to suppress new findings introduced by the change.
-- Do not report success based on partial or targeted runs alone. Targeted runs are allowed mid-batch, but the final gate requires a full-solution pass.
+- Do not report success based on partial or targeted runs. A focused run of one test file to debug a specific failure is debugging only; it is never a gate or evidence, and the final gate is the single gate run.

package/resources/claude-customizations/.claude/skills/epic-progress-report/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: epic-progress-report
+description: 'Post recurring epic progress reports from the coordinator session: a four-line TL;DR every 10 minutes and an hourly full status update with a push notification. Use when an epic is running and the owner wants scheduled progress, velocity, and time-remaining reports, or when the reports must be started, reset after a pause, moved to a new cadence, stopped, or recreated after a restart.'
+argument-hint: "[epic-folder]"
+allowed-tools:
+  - Read
+  - Glob
+  - "Bash(pwsh -NoProfile -File .claude/skills/epic-progress-report/scripts/Get-EpicProgressReport.ps1 *)"
+  - "Bash(cswap list*)"
+  - CronCreate
+  - CronList
+  - CronDelete
+  - PushNotification
+---
+
+# Epic Progress Report
+
+This skill runs the epic progress report script and schedules two recurring reports in the
+coordinator's main session: a four-line TL;DR and an hourly full status update. The script is
+`.claude/skills/epic-progress-report/scripts/Get-EpicProgressReport.ps1`. It reads the epic
+kickoff, the feature plans, the epic checkpoint, the pull-request state, and the weekly quota,
+prints the report, and keeps its samples and baseline in a state file.
+
+## When to Use This Skill
+
+- An epic is running and the owner wants scheduled progress reports.
+- The reports must be started for an epic, or recreated after the session restarted.
+- Work resumed after a pause or an outage and the velocity baseline must be reset.
+- The TL;DR cadence changes (for example from 5 to 10 minutes).
+- The epic is finished and the reports must be stopped.
+
+## Prerequisites
+
+- PowerShell 7 and `git`. `gh` and `cswap` are optional: without `gh` the pull-request state
+  is empty, and without `cswap` (or without parseable output) the weekly quota prints `n/a`.
+- The epic kickoff at `docs/features/epics/<epic-folder>/epic-kickoff.md` on
+  `origin/epic/<epic-folder>-integration`, with a feature-summary table (header first cell
+  `issue_num` or `Issue`) and an `Epic issue: #<n>` line. Pass `-EpicIssue` when the line
+  is missing.
+- The epic checkpoint `artifacts/orchestration/epic-orchestrator-state.json` under the
+  repository root (optional; without it every feature is classified from its plan and PR).
+- Run from the repository root in the coordinator's main session. An agent-isolated worktree
+  refuses command text containing `pwsh`, and the scheduled jobs and notifications belong to
+  the main session.
+
+## Inputs
+
+| Parameter | Default | Meaning |
+|---|---|---|
+| `-EpicFolder` | (mandatory) | Epic folder name under `docs/features/epics/`; also the epic name in the status heading. |
+| `-StartUtc` | stored start | Start of the measurement. Resolution: the passed value, else now with `-ResetBaseline`, else the stored start. With none of these the script stops before any git call with an error naming `-StartUtc` and `-ResetBaseline`. |
+| `-BaselineDone` | stored value, else 0 | Tasks already complete at the start. With `-ResetBaseline` and no passed value, the current done count. |
+| `-BaselineWeeklyPct` | stored value, else 0 | Weekly quota percentage at the start. `-ResetBaseline` does not change it. |
+| `-EpicIssue` | the kickoff's `Epic issue: #<n>` line | Epic issue number printed in the report. |
+| `-IntegrationBranch` | `origin/epic/<epic-folder>-integration` | Branch that holds the kickoff and the plans. |
+| `-KickoffPath` | `docs/features/epics/<epic-folder>/epic-kickoff.md` | Kickoff path on the integration branch. |
+| `-RepositoryRoot` | current location | Repository root in which git runs. |
+| `-CheckpointPath` | `artifacts/orchestration/epic-orchestrator-state.json` | Epic checkpoint under the repository root. |
+| `-StatePath` | `.claude/state/epic-progress-<epic-folder>.json` | State file under the repository root; the directory is created when missing. |
+| `-WaveOverheadHours` | 1.25 | Review and CI hours added per open wave. |
+| `-SampleCap` | 14 | Maximum number of samples kept. |
+| `-Mode` | `Full` | `TLDR` prints the four TL;DR lines; `Full` prints them followed by the full report. |
+| `-ResetBaseline` | off | Discards the stored samples and restarts the baseline now (see the reset section). |
+| `-PairSamples` | off | One-shot: pairs the stored samples for a cadence change (see the cadence section). Cannot be combined with `-ResetBaseline`. |
+
+A passed `-StartUtc`, `-BaselineDone`, or `-BaselineWeeklyPct` overrides the stored value and
+is persisted with the next state write.
+
+## Report Formats
+
+The wording, order, and punctuation below are the script's output and do not change. Values in
+angle brackets are placeholders; the examples use the fictional epic folder `example-epic` and
+epic issue `42`.
+
+TL;DR (both modes print these four lines first):
+
+```text
+**TL;DR:** Epic #<issue> is at <done> of <total> tasks (<pct>%). <done-sentence> <running-sentence>
+**Elapsed:** <H h MM min>, with about <hours> hours left on the wave-parallel estimate. **Weekly** quota is at <weekly>.
+**Avg Velocity:** <avg> tasks / hr. **Recent Velocity:** <recent> tasks / hr since last check-in. (SD of recent velocity: <sd>, from <n> intervals)
+**Estimated time remaining:** <range>
+```
+
+Variants:
+
+- done-sentence: `None of the <N> features is done yet.` or `<K> of <N> features are done.`
+- running-sentence: `No feature is running.`, `#<i> is running (<d> of <t>).`, or
+  `#<a> (<d> of <t>), #<b> (<d> of <t>) are running.`
+- range: `<HH:MM> hrs (range needs 3 or more check-in intervals)`, `<HH:MM> hrs to <HH:MM> hrs`,
+  or `<HH:MM> hrs to no upper bound (average velocity minus 2.05 SD is at or below 0.5 tasks / hr)`.
+- `<pct>`, `<avg>`, `<recent>`, and `<sd>` are rounded to one decimal and `<hours>` to zero
+  decimals, with invariant culture and default (to-even) rounding; an integral value prints
+  without a decimal (`1`, not `1.0`). `<weekly>` is `<value>%` or `n/a`.
+- Any non-finite value prints `n/a`; no report prints `NaN` or `Infinity`.
+
+Example (fictional):
+
+```text
+**TL;DR:** Epic #42 is at 3 of 10 tasks (30%). 1 of 3 features are done. #12345 is running (1 of 5).
+**Elapsed:** 3 h 00 min, with about 10 hours left on the wave-parallel estimate. **Weekly** quota is at 42.5%.
+**Avg Velocity:** 1 tasks / hr. **Recent Velocity:** 1 tasks / hr since last check-in. (SD of recent velocity: 0, from 3 intervals)
+**Estimated time remaining:** 09:22 hrs to 09:39 hrs
+```
+
+Full mode prints the TL;DR lines, then these lines:
+
+```text
+
+## Epic #<issue> <epic-folder>: status at <HH:mm> UTC, <MMM d>
+
+**Elapsed:** <H h MM min> since <HH:mm> UTC. **Progress:** <done> of <total> tasks complete, **<pct>%**.
+
+| State | Features |
+|---|---|
+| Completed | <completed> |
+| Running | #<i> (wave <w>, <band>): <d> of <t> tasks (<share>%).<phase><pr> |
+| Pending, wave <w> | #<i> (<t>), #<j> (<t>) |
+
+| Wave | Children | Tasks | Done |
+|---|---|---|---|
+| <w> | <count> | <tasks> | <done> |
+| **Total** | **<features>** | **<total>** | **<done>** |
+
+**Velocity:** <avg> tasks per hour (one child's pace). **Remaining:** <remaining> tasks.
+- Straight line, no parallelism: about <H h MM min> (upper bound).
+- Wave-parallel (longest chain <tasks> tasks plus about <overhead> h per open wave for review and CI): about **<H h MM min>**.
+**Weekly quota (active account):** <weekly> used, <delta> points since the epic started. This pool also covers the other runs in this session, so it is not the epic's cost alone.
+```
+
+Full report contents:
+
+- `<completed>` is `None yet` or the completed issues as `#<i>` joined with `, `.
+- One `Running` row per running feature. `<phase>` is ` Now at: <phase>.` when a current
+  phase exists, else empty; `<pr>` is ` PR <state>.` when a pull request exists, else empty;
+  `<share>` is the feature percentage rounded to zero decimals.
+- One `Pending, wave <w>` row per wave that holds pending features, in ascending wave order.
+- One Wave-table row per wave in ascending order, then the bold Total row.
+- `<overhead>` is `-WaveOverheadHours` unrounded. `<delta>` is the weekly percentage minus
+  the weekly baseline, with a leading `+` when it is finite and not negative, else `n/a`.
+- Times use invariant culture and UTC.
+
+## Calculation Rules
+
+- Task counts: plan checkboxes `- [ ] [P#-T#]` and `- [x] [P#-T#]` of each feature, read from
+  the feature's worktree when its branch has one, otherwise from the plan on the integration
+  branch. The feature list, waves, bands, and plan paths come from the kickoff's
+  feature-summary table.
+- Feature state: Completed when the checkpoint's `merge_status` is `merged` or
+  `worktree_removed`, or the feature PR is merged; Running when any task is done, the
+  checkpoint status is past `not_started`, or a PR exists; otherwise Pending.
+- Elapsed: from the start instant to now, clamped at 0; printed as `H h MM min` from rounded
+  total minutes.
+- Average velocity: (done now - baseline done) / elapsed hours; 0 when elapsed is not above 0.
+- Straight-line estimate: remaining tasks / average velocity; `n/a` when the average is not
+  above 0.
+- Wave-parallel estimate: the sum, over every wave with a non-completed feature, of the largest
+  remaining task count among that wave's non-completed features, divided by the average
+  velocity, plus `-WaveOverheadHours` (default 1.25 hours) per open wave; `n/a` when the
+  average is not above 0.
+- Samples: a check-in sample (Unix epoch seconds, done count) is added when there is no
+  previous sample or the previous one is at least 90 seconds old; the newest `-SampleCap`
+  (default 14) samples are kept. Epoch seconds are used because `ConvertFrom-Json` converts ISO
+  date strings into local-time values.
+- Interval velocity: max(0, change in done) / change in hours, for consecutive samples at
+  least 2 minutes apart; closer pairs are skipped.
+- Recent velocity: the latest interval's value; `n/a` without intervals.
+- SD: the sample standard deviation (n-1 denominator) of the interval velocities; `n/a` below
+  3 intervals. The report prints the interval count.
+- Range: below 3 intervals, the wave-parallel estimate followed by
+  `(range needs 3 or more check-in intervals)`. With 3 or more intervals the range is the
+  average velocity plus and minus 2.05 SD: fast end = critical-path tasks /
+  (average + 2.05 x SD) + overhead; slow velocity = average - 2.05 x SD; when the slow
+  velocity is above 0.5 tasks per hour the slow end = critical-path tasks / slow velocity +
+  overhead, otherwise the slow end prints the no-upper-bound text. Hours print as `HH:MM`.
+- Weekly quota: the seven-day percentage of the active account in `cswap list --json`;
+  `n/a` when `cswap` is missing or prints nothing parseable.
+- `n/a`: every printed number passes through a formatter that returns `n/a` for NaN or
+  infinity.
+
+## Starting the Reports
+
+1. Run the script once from the repository root to set the baseline. Either pass the start
+   and the tasks already done at that start:
+
+   ```text
+   pwsh -NoProfile -File .claude/skills/epic-progress-report/scripts/Get-EpicProgressReport.ps1 -EpicFolder example-epic -StartUtc 2026-01-05T09:00:00Z -BaselineDone 40 -Mode TLDR
+   ```
+
+   or start the measurement now:
+
+   ```text
+   pwsh -NoProfile -File .claude/skills/epic-progress-report/scripts/Get-EpicProgressReport.ps1 -EpicFolder example-epic -ResetBaseline
+   ```
+
+   The start and baseline are stored in the state file, so later runs need no `-StartUtc`.
+2. Create the two recurring jobs with `CronCreate`, using the prompts below with
+   `<epic-folder>` replaced by the epic folder name.
+3. Confirm both jobs with `CronList`.
+
+## Scheduling Prompts
+
+TL;DR job: cron `*/10 * * * *`, recurring.
+
+```text
+Run `pwsh -NoProfile -File .claude/skills/epic-progress-report/scripts/Get-EpicProgressReport.ps1 -EpicFolder <epic-folder> -Mode TLDR` from the repository root and post its output verbatim as the TL;DR epic update (no push notification). Do not add commentary unless a run is blocked or a child has finished and needs relaying.
+```
+
+Hourly job: cron `7 * * * *`, recurring.
+
+```text
+Run `pwsh -NoProfile -File .claude/skills/epic-progress-report/scripts/Get-EpicProgressReport.ps1 -EpicFolder <epic-folder>` (full mode) from the repository root and post its output as the hourly epic update, then send a PushNotification with the TL;DR line (under 200 characters). Check `cswap list` for the weekly pool; stop and commit at 93%.
+```
+
+Notes on the prompts:
+
+- Push-notification text: the first TL;DR output line with every `**` removed. When that text
+  is 200 characters or longer, drop the running-features sentence; the remaining text (prefix,
+  task counts, percentage, and done-sentence) is well under 200 characters.
+- The prompts omit `-StartUtc`, `-BaselineDone`, `-ResetBaseline`, and `-PairSamples`. The
+  baseline is read from the state file, so a later reset is never overridden by a stale
+  scheduled argument, and pairing is never repeated by a recurring job.
+- Cron times are local time, not UTC.
+- Jitter: a 10-minute job fires up to 5 minutes late and an hourly job up to 30 minutes late,
+  by a constant delay per job.
+
+## Resetting the Baseline After a Pause
+
+Whenever work resumes after a pause or an outage, run the script once with `-ResetBaseline`:
+
+```text
+pwsh -NoProfile -File .claude/skills/epic-progress-report/scripts/Get-EpicProgressReport.ps1 -EpicFolder example-epic -ResetBaseline
+```
+
+- The stored samples are discarded, the start becomes now, and the baseline done count becomes
+  the current done count. Pass `-StartUtc` and `-BaselineDone` with `-ResetBaseline` when the
+  resume instant is in the past.
+- The weekly-quota baseline is kept, so the Full report's points since the epic started stay
+  accurate.
+- The scheduled prompts are not changed.
+- The first reports after a reset show `0 h 00 min` elapsed and `n/a` estimates, and the
+  estimates are unreliable for about two hours.
+- Reason: earlier measures include the paused time. A 9-hour outage once distorted the averages
+  until the baseline was reset.
+
+## Changing the Cadence
+
+To move the TL;DR job to a new interval (for example from 5 to 10 minutes):
+
+1. Run the script once with `-PairSamples`. It keeps the newest sample and every second older
+   sample, so the stored intervals match the doubled cadence. 14 samples become 7.
+2. Delete the TL;DR job with `CronDelete` and create it again with `CronCreate` at the new
+   interval.
+
+`-PairSamples` is a one-shot command: each run halves the samples again. Never put it in a
+scheduled prompt.
+
+Worked example from recorded samples: thirteen 5-minute intervals gave mean 26.2 and SD 31.4
+tasks per hour; after pairing, six 10-minute intervals give mean 27.3 and SD 23.2. The
+conversation that defined the reports quoted 31.5 for the 5-minute SD; the recorded samples
+give 31.4 (unrounded 31.4495).
+
+## Stopping the Reports
+
+1. Run `CronList` and note the IDs of the TL;DR and hourly jobs.
+2. Run `CronDelete` for each report job ID.
+3. Keep the state file for a later restart of the reports, or delete it.
+
+## After a Restart
+
+- `CronCreate` jobs are session-only: they fire only while the session runs and is idle, and a
+  missed run fires once when the session becomes idle again.
+- `claude --resume` or `claude --continue` restores jobs that have not expired.
+- Recurring jobs expire 7 days after creation; recreate both before the 7-day expiry.
+- Run `CronList` and recreate only the missing jobs with the prompts above.
+- If work paused during the restart, reset the baseline first.
+- The state file survives under `.claude/state/` wherever the checkout persists, so the
+  baseline and samples are kept.
+
+## State File
+
+- Location: `.claude/state/epic-progress-<epic-folder>.json` under the repository root.
+  `-StatePath` overrides it.
+- The state is never committed: `.claude/state/` is gitignored in this repository and the
+  push-down adds it to a destination's `.gitignore`.
+- The state is per checkout: a different worktree or `-RepositoryRoot` starts a separate
+  history. Run from the same root, or pass `-StatePath`.
+- `git clean -fdX` deletes it.
+- A state file under the system temporary directory, written by an earlier version, is not
+  migrated: pass its path once with `-StatePath`, or reset the baseline.
+- The legacy format (a JSON array of samples) is still read. The current document is:
+
+  ```json
+  {
+    "version": 1,
+    "startUnixSeconds": 1767603600,
+    "baselineDone": 0,
+    "baselineWeeklyPct": 0,
+    "samples": [ { "ts": 1767614400, "done": 3 } ]
+  }
+  ```
+
+- Blank text, unparseable text, or a version other than 1 is read as empty state; a missing
+  field is absent.
+- The state is written when a sample is added, or when `-ResetBaseline` or `-PairSamples` is
+  given. A run within 90 seconds of the last sample with neither switch writes nothing.
+
+## Known Behaviors and Measured Rates
+
+- Plan checkboxes tick at batch boundaries, so 5-minute interval velocity is bursty: 0 to
+  about 150 tasks per hour, with an SD of about 30 to 45 around a mean near 26.
+- Aggregate throughput with three or four features in parallel is about 25 to 30 tasks per
+  hour. Per-feature pace is about 9 to 13 tasks per hour; a lone feature, including its review
+  and PR tail, about 4.
+- The wave-parallel estimate is unreliable for about two hours after a baseline: it swung
+  between 35 and 110 hours in the first hour, and once estimated 26 to 30 hours for about 10
+  active hours.
+- Task totals drift when planners revise plans, so read the percentage against the live total.
+- Flat stretches of 20 to 60 minutes are normal during review, PR, CI, and merge.
+- The tail from plan complete to merge is 0.8 to 4 hours per feature, and each remediation
+  cycle adds 45 to 90 minutes.
+- Weekly quota burn is 3 to 7 points per hour (4.3 to 7.6 tasks per point).
+- The hourly Full run also records a sample when it runs more than 90 seconds after the
+  previous one. This adds a shorter interval about once an hour and raises the SD.
+- A negative average (done below the baseline after a plan revision) makes the straight-line
+  and wave-parallel estimates `n/a`, while the range can print negative or very large values.
+- Integral velocities print without a decimal (`1`, not `1.0`).
+
+## Notes
+
+- Delivery: the push-down serves the installed extension payload, so this skill reaches a
+  destination repository only after the extension is rebuilt and reinstalled.
+- Quota: the 93% stop in the hourly prompt is coordinator policy. The commit-before-the-wall
+  procedure is governed by `.claude/skills/quota-throttling/SKILL.md`.
+- The script is read-only toward git and GitHub: it runs only `git fetch`, `git show`,
+  `git worktree list`, `gh pr list`, and `cswap list --json`, and the only file it writes is
+  the state file.
+- In this repository, `scripts/dev-tools/Get-EpicProgressReport.ps1` forwards every argument
+  to the canonical script; the skill always invokes the canonical script.