dev-loops 0.5.0 → 0.6.0

package/scripts/release/extract-changelog-section.mjs

@@ -0,0 +1,111 @@
+import { readFile } from "node:fs/promises";
+
+import { isDirectCliRun } from "../_core-helpers.mjs";
+
+const USAGE = `Usage: extract-changelog-section.mjs --version <v> [--changelog <path>]
+
+Prints the CHANGELOG.md section for <version> (the block from "## <version>"
+up to the next "## " heading). Exits 1 if no such section exists or the section
+is empty, so a release is never created for an undocumented version. Exits 2 on
+usage/argument errors (missing --version, missing flag value, unreadable file).`;
+
+/**
+ * Extract the changelog block for a single version.
+ *
+ * Matches a heading line of the form "## <version>" optionally followed by
+ * " - <date>" (or any trailing text), and returns everything up to but not
+ * including the next "## " heading. Returns null when no matching section
+ * exists (fail closed — caller must not synthesize notes).
+ *
+ * @param {string} changelog - Full CHANGELOG.md contents.
+ * @param {string} version - Version without a leading "v" (e.g. "0.5.0").
+ * @returns {string|null} Trimmed section body (without the heading), or null.
+ */
+export function extractChangelogSection(changelog, version) {
+  const lines = changelog.split("\n");
+  // A heading is "## " followed by the exact version token, then either end of
+  // line or a non-version-character (space / "-"). This avoids "0.5.0" matching
+  // "0.5.0-rc1" or "0.5.01".
+  const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const headingRe = new RegExp(`^##\\s+v?${escaped}(?=\\s|$)`);
+
+  let start = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (headingRe.test(lines[i])) {
+      start = i;
+      break;
+    }
+  }
+
+  if (start === -1) {
+    return null;
+  }
+
+  const body = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^##\s/.test(lines[i])) {
+      break;
+    }
+    body.push(lines[i]);
+  }
+
+  return body.join("\n").trim();
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+
+  let version;
+  let changelogPath = "CHANGELOG.md";
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--version" || argv[i] === "--changelog") {
+      const flag = argv[i];
+      const value = argv[i + 1];
+      if (value === undefined) {
+        process.stderr.write(`error: ${flag} requires a value\n\n${USAGE}\n`);
+        return 2;
+      }
+      if (flag === "--version") {
+        version = value;
+      } else {
+        changelogPath = value;
+      }
+      i += 1;
+    }
+  }
+
+  if (!version) {
+    process.stderr.write(`error: --version is required\n\n${USAGE}\n`);
+    return 2;
+  }
+
+  const normalized = version.replace(/^v/, "");
+
+  let changelog;
+  try {
+    changelog = await readFile(changelogPath, "utf8");
+  } catch (error) {
+    process.stderr.write(`error: cannot read ${changelogPath}: ${error.message}\n`);
+    return 2;
+  }
+
+  const section = extractChangelogSection(changelog, normalized);
+  if (section === null || section === "") {
+    process.stderr.write(
+      `error: no section found for version ${normalized} in ${changelogPath}. ` +
+        `Refusing to create a release for an undocumented version.\n`,
+    );
+    return 1;
+  }
+
+  process.stdout.write(`${section}\n`);
+  return 0;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  const exitCode = await main();
+  process.exitCode = exitCode;
+}

package/skills/dev-loop/SKILL.md

@@ -35,7 +35,14 @@ For async-required routes (config `workflow.asyncStartMode`, default `required`)
 > Under the Claude Code harness the dev-loop runs as a single agent: run these steps directly — no read-only boundary and no separate async-subagent dispatch. See [Main Agent Contract](../docs/main-agent-contract.md).
 
 <!-- pi-only -->
-**CLI invocation (`<dev-loops-package-root>`):** dev-loop CLI commands below are invoked as `node <dev-loops-package-root>/cli/index.mjs <verb...>` using the package-local CLI rather than `npx`, so they resolve unambiguously from the installed package without a global install. Resolve `<dev-loops-package-root>` from this skill's own installed path: this skill is installed at `<package-root>/.pi/skills/dev-loop/SKILL.md`, so the package root is `../../..` from this skill's directory. (The `dev-loop` agent resolves it analogously from its own installed path.)
+**CLI invocation (`<dev-loops-package-root>`):** dev-loop CLI commands below are invoked as `node <dev-loops-package-root>/cli/index.mjs <verb...>` using the package-local CLI rather than `npx`, so they resolve unambiguously from the installed package without a global install. Resolve `<dev-loops-package-root>` via the first of these **bounded** candidates whose `cli/index.mjs` exists — never assume a single fixed layout (under a Pi user-level install the package lives at `~/.pi/agent/npm/node_modules/dev-loops/`, so the old `../../..` package-relative guess from `skills/dev-loop/SKILL.md` overshoots the package root):
+
+1. **Node module resolution** (best-effort first try): `node -e "try{const p=require('node:path');console.log(p.resolve(p.dirname(require.resolve('dev-loops/cli/index.mjs')),'..'))}catch{process.exit(1)}"` — resolves the package root when `dev-loops` is reachable from Node's module search path (notably under `~/.pi/agent/npm`); this is cwd-dependent and commonly misses from a target-repo cwd, so the probe is wrapped in try/catch (no stack trace, exits non-zero on miss) — treat a non-zero exit as "probe missed, try the next candidate", not a hard failure.
+2. **Pi user-agent npm root** (reliable for user-level installs): `~/.pi/agent/npm/node_modules/dev-loops`.
+3. **Package-relative (legacy):** `../../..` from this skill's own directory (the original package-local install layout).
+4. **Global npm root:** `$(npm root -g)/dev-loops`.
+
+NEVER fall back to `find /` or any unbounded filesystem walk to locate the CLI — it stalls and trips the needs-attention timeout. If every bounded candidate fails, stop and ask the orchestrator/operator for the dev-loops package root rather than searching. (The `dev-loop` agent resolves it analogously.)
 <!-- /pi-only -->
 
 Resolve authoritative state via the startup resolver (`node <dev-loops-package-root>/cli/index.mjs loop startup --issue <n>` for issues, `node <dev-loops-package-root>/cli/index.mjs loop startup --pr <n>` for PRs), then immediately build the handoff envelope via `node <dev-loops-package-root>/cli/index.mjs loop build-envelope --input <resolver-output.json>`. The envelope determines `requiredReads`, `nextAction`, `stopRules`, and `acceptance` — load only those files, execute only that bounded task. It is the first handoff artifact consumed before loading any route pack. See [Workflow Handoff Contract](../docs/workflow-handoff-contract.md) for the derivation contract.
@@ -125,7 +132,12 @@ When you need a fact from a dev-loops JSON-emitting script, climb this ladder an
 1. **Prefer the dev-loops subcommand / concise mode.** Use `loop info` or a script's `--concise`/`--summary` mode (e.g. `run-watch-cycle.mjs --concise`, `probe-copilot-review.mjs --concise`) for a human-readable digest. The concise modes surface loop state, Copilot round count, unresolved/actionable thread counts, round-cap-clean eligibility, CI status, next action, and the current round's new Copilot comment bodies.
 2. **`--silent` / `-s` for a yes/no check.** Reads ZERO output: `… --jq '<predicate>' --silent; echo $?` exits `0` for true / `1` for false. Without `--jq`, `--silent` maps the script's success (`ok:true`) to exit `0`, failure to `1`. Example: `probe-copilot-review.mjs --repo o/r --pr N --jq '.status=="idle"' -s`.
 3. **`--jq <filter>` to extract a single field.** The `--jq`-wired scripts (`probe-copilot-review.mjs`, `capture-review-threads.mjs`, `upsert-checkpoint-verdict.mjs`, the `scripts/projects/*` queue scripts) accept a gh-style `--jq` filter (jq subset: field access, `.[]`/`.[N]`, `|`, `select(...)`, `==`/`!=`/`<`/`<=`/`>`/`>=`, `length`, `keys`). It prints only the filtered value. An invalid filter fails closed (stderr + exit `2`), distinct from a clean predicate-false (silent exit `1`).
-4. **`gh … --jq` on a raw `gh` call** when no dev-loops script covers it.
+4. **Use a dev-loops wrapper for `gh` reads — never an agent-level raw `gh`.** With `workflow.requireRetrospectiveInternalTooling: true`, a raw `gh` call is a recorded retro violation (fail-closed). If no script covers the read you need, treat it as a tooling gap: file/build a thin wrapper (reuse `scripts/lib/jq-output.mjs`, like the three below), don't shell out. The reads that already have wrappers:
+   - CI run-log tail (a failing PR's job log) → `scripts/github/fetch-ci-logs.mjs --repo <o/r> --pr <n> [--failed-only] [--tail <n>]`, **never raw `gh run view --log`/`--log-failed`**. (`probe-ci-status.mjs` names the failed checks; this returns the LOG.)
+   - Issue list/filter → `scripts/github/list-issues.mjs --repo <o/r> [--state <open|closed|all>] [--label <l>] [--limit <n>]`, **never raw `gh issue list`**. (The queue tool lists the project board; this is for arbitrary issue queries.)
+   - Issue comment → `scripts/github/comment-issue.mjs --repo <o/r> --issue <n> (--body <text> | --body-file <path>)`, **never raw `gh issue comment`**. Returns `{ ok, commentUrl }`.
+
+   All three accept the same `--jq`/`--silent` output flags as the other JSON-emitting scripts.
 5. **NEVER `| python3` or `node -e`** to parse tool JSON. If a field you need is missing from a script's output, add it to the script (or its concise mode), not an inline parser.
 
 ## Guard rules

package/skills/docs/release-runbook.md

@@ -0,0 +1,45 @@
+# Release runbook
+
+Releasing is fully automated from a tag. **Pushing a `v<version>` tag is the only
+manual step.** Everything after the tag is hands-off.
+
+## Procedure
+
+1. On `main` (merged, green), bump the version and add the matching
+   `## <version> - <date>` section to `CHANGELOG.md` (the empty `## Unreleased`
+   heading stays above the latest version).
+2. Tag the release commit and push the tag:
+
+   ```bash
+   git tag v<version>
+   git push origin v<version>
+   ```
+
+That is the whole manual flow. Do **not** create the GitHub Release by hand —
+the workflow does it (and is idempotent if you already created one).
+
+## What happens automatically
+
+- **`.github/workflows/release.yml`** fires on the `v*` tag push. It verifies the
+  tagged commit is on `origin/main`, extracts the `## <version>` block from
+  `CHANGELOG.md` via `scripts/release/extract-changelog-section.mjs`, and creates
+  the GitHub Release (`--latest`, notes = that CHANGELOG section). It is
+  **idempotent** (no-op if a Release for the tag already exists) and **fails
+  closed** if the version has no CHANGELOG section — an undocumented version never
+  gets an empty release.
+- **`.github/workflows/npm-publish.yml`** fires on `release: published` (created by
+  the step above) and publishes the packages to npm.
+
+## Failure modes
+
+- Tag not on `main`: the release workflow fails the on-main guard — re-tag the
+  correct commit.
+- Missing CHANGELOG section: the extraction step exits non-zero and no Release is
+  created. The workflow checks out the tagged commit, so editing `CHANGELOG.md`
+  alone is not enough — commit the `## <version>` section, then move the tag to
+  the new commit and re-push:
+
+  ```bash
+  git tag -f v<version>
+  git push --force origin v<version>
+  ```

package/skills/docs/ui-e2e-scoping-step.md

@@ -0,0 +1,102 @@
+# UI e2e scoping step
+
+Canonical owner for **when the shared UI/mobile e2e loop is required**. Inclusion
+is **path-triggered and deterministic** — it does not depend on a human annotating
+the PR or a phase doc.
+
+## Trigger: a rendered-artifact change requires UI e2e coverage
+
+A PR that **adds or modifies a rendered HTML artifact** MUST run the shared UI e2e
+assertions (mobile + desktop) AND register that artifact in the e2e suite. A
+"rendered artifact" is anything that renders to a served page or component:
+
+- a presentation deck — `docs/presentations/*.html` (registered in `DECK_REGISTRY`)
+- an article page — `docs/articles/*.html` (registered in `ARTICLE_REGISTRY`; the
+  intro article is the published landing page)
+- the inspect-run viewer's served page/component — `scripts/loop/inspect-run-viewer.mjs`
+
+The trigger is the PR's **changed-file set** matched against these explicit globs.
+It is conservative on purpose (issue #976 scope): only artifacts that render to a
+page/component, matched by exact directory + single-segment `*.html` globs (no
+recursion) and the viewer source path.
+
+Registration is keyed on the **full repo-relative path**, not the basename, so
+`docs/articles/X.html` and `docs/presentations/X.html` (which share basenames,
+e.g. `introducing-dev-loops.html`) are **distinct** artifacts and can never alias
+onto each other — editing the article never counts as deck coverage and vice versa.
+
+### Examples — required
+
+- `docs/presentations/introducing-dev-loops.html` edited → UI e2e **required**
+  (deck-smoke CI job runs the deck fit specs).
+- `docs/articles/introducing-dev-loops.html` (the landing page) edited → UI e2e
+  **required** (article-smoke CI job runs the article fit specs); it is its own
+  registration, NOT covered by the same-named deck.
+- A new `docs/articles/new-page.html` added → UI e2e **required**, and because the
+  new page is not yet in `ARTICLE_REGISTRY` the gate **fails closed** until it is
+  registered (add an entry + a thin spec calling `defineArticleSuite`).
+- `scripts/loop/inspect-run-viewer.mjs` edited → UI e2e **required** (the viewer is
+  registered in `VIEWER_REGISTRY`).
+
+### Examples — not required
+
+- `packages/core/src/loop/copilot-loop-state.mjs`, `README.md`, `*.test.mjs`,
+  `docs/articles/foo.md` (not `.html`), or a nested `docs/articles/sub/x.html`
+  (the glob is single-segment) → UI e2e **not required**; the gate passes through.
+
+## Register the artifact in the suite
+
+"Registered" means the artifact appears in the shared registries:
+
+- decks → `DECK_REGISTRY` in `test/playwright/harness/deck-fit-harness.mjs`
+  (served from `docs/presentations/<deck>`) with a thin spec calling `defineDeckSuite`.
+- articles → `ARTICLE_REGISTRY` in `test/playwright/harness/deck-fit-harness.mjs`
+  (served from `docs/articles/<file>`) with a thin spec calling `defineArticleSuite`
+  (shared fit/CSP/no-horizontal-scroll assertions, minus the deck's per-section
+  named captures).
+- the viewer → `VIEWER_REGISTRY` in
+  `test/playwright/harness/inspect-run-viewer-harness.mjs`.
+
+The deterministic membership list the gate checks against lives in
+`packages/core/src/loop/ui-e2e-scoping.mjs` (`REGISTERED_ARTIFACT_PATHS`, keyed by
+full repo-relative path; `VIEWER_ARTIFACT_ID`). A sync test keeps
+`REGISTERED_ARTIFACT_PATHS` from drifting from `DECK_REGISTRY` + `ARTICLE_REGISTRY`;
+the single-valued `VIEWER_ARTIFACT_ID` is not import-checked against `VIEWER_REGISTRY`
+(that harness pulls `@playwright/test` into core), so keep the two in sync by hand.
+
+## Fail-closed semantics
+
+The check is wired as a gate precondition in `evaluatePrGateCoordination`
+(`packages/core/src/loop/pr-gate-coordination.mjs`), at a seam distinct from the
+mergeability (#980) and retrospective (#982) preconditions. It fails closed:
+
+- **Unregistered rendered artifact touched** → gate blocks with
+  `nextAction: run_ui_e2e_suite`, reason naming the artifact and that it needs
+  registration in the suite.
+- **Registered, but UI e2e suite did not pass for this head** (`uiE2ePassed` is
+  `false`/unknown) → gate blocks with the same action, reason that the suite must
+  run and pass first.
+- **Non-UI change** → `required: false`, gate passes through untouched.
+
+The detect layer reads the changed-file set from `gh pr view --json files` and
+derives `uiE2ePassed` from the `statusCheckRollup` UI e2e check(s)
+(`UI_E2E_CHECK_NAMES`): present UI e2e checks must all be `SUCCESS`; if none is
+present the value is unknown and the gate fails closed.
+
+Each rendered-artifact family has a stable, satisfiable CI job in
+`.github/workflows/ci.yml`, path/diff-conditioned in the `changes` job and named
+to match `UI_E2E_CHECK_NAMES` so the gate can read a real signal:
+
+- `viewer-smoke` → inspect-run viewer spec (triggered by the viewer source set).
+- `deck-smoke` → both presentation deck fit specs (triggered by
+  `docs/presentations/**` and the deck specs/harness/configs).
+- `article-smoke` → both article fit specs (triggered by `docs/articles/**` and the
+  article specs/harness/configs).
+
+So a deck- or article-only PR has a CI check that can actually satisfy the gate;
+without these jobs such a PR would fail closed with no satisfiable signal.
+
+## Non-goals
+
+Not always-on screenshot testing; not mandatory multi-browser. The criterion is
+only the conservative path-glob + registry-membership + passing-coverage check.

package/skills/local-implementation/SKILL.md

@@ -512,7 +512,7 @@ After the phase plan passes review:
 3. Run local validation:
    - `npm run verify`
    - when a narrower local check is more honest for the touched slice, say so explicitly and run the narrowest justified subset instead of pretending the full verify path was unnecessary
-   - for user-facing HTML/UI/component slices when the user opts in, add a bounded deterministic browser smoke harness (prefer fixture-backed Playwright WebKit plus screenshot capture); use `npm run test:playwright:viewer` when that viewer/browser surface is part of the slice, and wire it into CI once it becomes required validation for that slice
+   - for a *rendered* HTML artifact (a deck `docs/presentations/*.html`, an article `docs/articles/*.html`, or the inspect-run viewer source) UI e2e coverage is **required and auto-scoped** — not opt-in. Touching one obliges you to register it in the shared harness and have a passing UI e2e suite, or the gate fails closed (see [UI e2e scoping step](../docs/ui-e2e-scoping-step.md)); run the matching shared suite locally, e.g. `npm run test:playwright:intro-deck` / `:intro-article` / `:viewer`. For a bespoke local UI surface that is not a registered rendered artifact, the WebKit smoke seam (fixture-backed Playwright WebKit plus screenshot capture) remains available without being mandatory
    - **Commit immediately after validation passes.** Once `npm run verify` (or the narrowest justified validation subset) is green, stage and commit the current slice of work with an atomic commit message. For tracker-backed sessions, also push the commit. In non-interactive subagent sessions, commit authorization is implicit — the subagent was dispatched to implement and must commit before exiting. In interactive sessions, wait for coordination agent authorization. Do not defer commits — uncommitted changes when the session terminates are a workflow defect.
 4. Review the implementation against the merged phase plan.
 5. Run the default pre-approval gate as a full review / fix loop on the branch before calling it review-complete, approval-ready, merge-ready, or ready for final handoff: