Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

fix: unblock fork PRs, triage GitHub, document the refactor path (#556)

Cobus Greyling47bcbd4adcdd
diff --git a/.github/workflows/daily-triage.yml b/.github/workflows/daily-triage.yml
index 787e8c7..9180966 100644
--- a/.github/workflows/daily-triage.yml
+++ b/.github/workflows/daily-triage.yml
@@ -60,36 +60,22 @@ jobs:
env:
GH_TOKEN: ${{ github.token }}
- - name: Update STATE.md
+ - name: Inspect GitHub and write STATE.md
+ id: github
+ env:
+ GH_TOKEN: ${{ github.token }}
run: |
- DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
- SCORE="${{ steps.audit.outputs.score }}"
- LEVEL="${{ steps.audit.outputs.level }}"
- FAILING="${{ steps.workflows.outputs.failing }}"
- cat > STATE.md <<EOF
- # Loop State — loop-engineering reference
-
- Last run: ${DATE} (automated daily-triage workflow)
-
- ## High Priority (loop is acting or waiting on human)
-
- - Maintain loop readiness score ≥ 58 (current: **${SCORE}**, level **${LEVEL}**).
- - Keep npm packages current after tool changes (tag \`loop-audit-v*\`, \`loop-init-v*\`, \`loop-cost-v*\` — see docs/RELEASE.md).
- $([ "$FAILING" -gt 0 ] && echo "- **${FAILING}** dogfood workflow(s) failing — investigate CI.")
-
- ## Watch List
-
- - Expand contributor failure stories (dependency sweeper, multi-loop).
- - Collect a production story for Post-Merge Cleanup.
- - Validate \`loop-init\` scaffolds on fresh projects across all patterns.
-
- ## Recent Noise (ignored this run)
-
- —
-
- ---
- Run log: Updated by \`.github/workflows/daily-triage.yml\`. See \`LOOP.md\` for cadence and gates.
- EOF
+ mkdir -p /tmp/triage
+ node scripts/github-triage.mjs \
+ --score "${{ steps.audit.outputs.score }}" \
+ --level "${{ steps.audit.outputs.level }}" \
+ --failing-workflows "${{ steps.workflows.outputs.failing }}" \
+ --out-md STATE.md \
+ --out-json /tmp/triage/summary.json
+ HIGH=$(node -e "console.log(JSON.parse(require('fs').readFileSync('/tmp/triage/summary.json','utf8')).high)")
+ ITEMS=$(node -e "console.log(JSON.parse(require('fs').readFileSync('/tmp/triage/summary.json','utf8')).items_found)")
+ echo "high=$HIGH" >> "$GITHUB_OUTPUT"
+ echo "items=$ITEMS" >> "$GITHUB_OUTPUT"
- name: Append loop-run-log.md
id: runlog
@@ -103,6 +89,8 @@ jobs:
")
FAILING="${{ steps.workflows.outputs.failing }}"
SCORE="${{ steps.audit.outputs.score }}"
+ ITEMS="${{ steps.github.outputs.items }}"
+ HIGH="${{ steps.github.outputs.high }}"
if [ "$FAILING" -gt 0 ]; then
OUTCOME="escalated"
else
@@ -113,9 +101,9 @@ jobs:
run_id: '${END}',
pattern: 'daily-triage',
duration_s: Number('${DURATION}'),
- items_found: Number('${FAILING}') + 1,
+ items_found: Number('${ITEMS}' || 0) + Number('${FAILING}'),
actions_taken: 1,
- escalations: Number('${FAILING}'),
+ escalations: Number('${FAILING}') + Number('${HIGH}' || 0),
tokens_estimate: 52000,
readiness_score: Number('${SCORE}'),
outcome: '${OUTCOME}',
diff --git a/.github/workflows/fork-pr-gate.yml b/.github/workflows/fork-pr-gate.yml
new file mode 100644
index 0000000..a21d852
--- /dev/null
+++ b/.github/workflows/fork-pr-gate.yml
@@ -0,0 +1,118 @@
+name: Fork PR gate
+
+# Runs in the *base* repo, so first-time-contributor fork PRs still get a
+# required-check outcome without anyone clicking "Approve and run workflows".
+# NEVER checkout or execute PR-head code here — list files via the API only.
+on:
+ pull_request_target:
+ types: [opened, synchronize, reopened]
+ workflow_dispatch:
+ inputs:
+ pr_number:
+ description: Open PR number to re-evaluate (content-only stub vs comment)
+ required: true
+ type: string
+
+permissions:
+ contents: read
+ statuses: write
+ pull-requests: write
+
+jobs:
+ gate:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/github-script@v9
+ with:
+ script: |
+ const owner = context.repo.owner;
+ const repo = context.repo.repo;
+ const marker = '— loop-engineering fork-pr-gate';
+
+ const prNumber = context.eventName === 'workflow_dispatch'
+ ? Number(process.env.PR_NUMBER)
+ : context.payload.pull_request.number;
+
+ if (!Number.isFinite(prNumber) || prNumber < 1) {
+ core.setFailed('Missing PR number');
+ return;
+ }
+
+ const { data: pr } = await github.rest.pulls.get({
+ owner, repo, pull_number: prNumber,
+ });
+
+ const files = await github.paginate(github.rest.pulls.listFiles, {
+ owner, repo, pull_number: prNumber, per_page: 100,
+ });
+ const paths = files.map((f) => f.filename);
+
+ const isContentPath = (p) => {
+ if (
+ p.startsWith('docs/') ||
+ p.startsWith('examples/') ||
+ p.startsWith('stories/') ||
+ p.startsWith('skills/') ||
+ p.startsWith('assets/')
+ ) {
+ return true;
+ }
+ // Root markdown / license only — not CODEOWNERS, gate.yaml, patterns, tools.
+ if (!p.includes('/')) {
+ return (
+ p.endsWith('.md') ||
+ p === 'LICENSE' ||
+ p === 'CODE_OF_CONDUCT.md'
+ );
+ }
+ return false;
+ };
+
+ const allContent = paths.length > 0 && paths.every(isContentPath);
+ const sha = pr.head.sha;
+ const targetUrl = `${context.serverUrl}/${owner}/${repo}/actions/runs/${context.runId}`;
+
+ core.info(`PR #${prNumber} sha=${sha} files=${paths.length} content-only=${allContent}`);
+ core.info(paths.join('\n'));
+
+ if (allContent) {
+ for (const check of ['validate', 'audit']) {
+ await github.rest.repos.createCommitStatus({
+ owner,
+ repo,
+ sha,
+ state: 'success',
+ context: check,
+ description: 'Content-only PR — required checks via fork-pr-gate (base repo)',
+ target_url: targetUrl,
+ });
+ }
+ core.info('Posted success statuses for validate + audit');
+ return;
+ }
+
+ // Code / patterns / tools / CI: do not fake required checks.
+ // Leave a one-shot comment so the maintainer knows to approve workflows.
+ const comments = await github.paginate(github.rest.issues.listComments, {
+ owner, repo, issue_number: prNumber, per_page: 100,
+ });
+ if (comments.some((c) => c.body?.includes(marker))) {
+ core.info('Fork-pr-gate comment already present; skipping.');
+ return;
+ }
+ await github.rest.issues.createComment({
+ owner,
+ repo,
+ issue_number: prNumber,
+ body: [
+ 'This PR changes paths that must run the real `validate` and `audit` workflows (tools, patterns, scripts, or CI).',
+ '',
+ 'Fork PRs from first-time contributors start with those workflows **waiting for approval**. A maintainer needs to open the Checks tab and click **Approve and run workflows**. Until that happens, branch protection will show the PR as blocked even after a review.',
+ '',
+ 'Content-only PRs (`docs/`, `examples/`, `stories/`, `skills/`, root markdown) skip this step — required checks are posted from this workflow instead.',
+ '',
+ marker,
+ ].join('\n'),
+ });
+ env:
+ PR_NUMBER: ${{ inputs.pr_number }}
diff --git a/.github/workflows/welcome-contributors.yml b/.github/workflows/welcome-contributors.yml
index c0de25d..c07ac47 100644
--- a/.github/workflows/welcome-contributors.yml
+++ b/.github/workflows/welcome-contributors.yml
@@ -10,6 +10,7 @@ on:
- 'docs/adopters.md'
- 'examples/**'
- 'docs/**'
+ - 'skills/**'
permissions:
contents: read
@@ -53,6 +54,8 @@ jobs:
const isAdopter = paths.some((p) => p === 'docs/adopters.md');
const isExample = paths.some((p) => p.startsWith('examples/')) ||
pr.title.toLowerCase().includes('example');
+ const isSkill = paths.some((p) => p.startsWith('skills/')) ||
+ pr.title.toLowerCase().includes('skill');
const isDocs = paths.some((p) => p.startsWith('docs/')) ||
pr.title.toLowerCase().includes('docs:');
@@ -60,6 +63,7 @@ jobs:
if (isStory) kind = 'a production story';
else if (isAdopter) kind = 'an adopter listing';
else if (isExample) kind = 'a tool example';
+ else if (isSkill) kind = 'a skill improvement';
else if (isDocs) kind = 'a docs improvement';
const body = [
diff --git a/CODEOWNERS b/CODEOWNERS
index cc08e74..71dfadf 100644
--- a/CODEOWNERS
+++ b/CODEOWNERS
@@ -7,8 +7,11 @@
/.github/ @cobusgreyling
/starters/ @cobusgreyling
-# Docs / examples / stories — co-triaged by community area owner
-# (AIMindCrafter: multi-PR docs/examples track; write access for CODEOWNERS reviews)
-/docs/ @cobusgreyling @AIMindCrafter
-/examples/ @cobusgreyling @AIMindCrafter
-/stories/ @cobusgreyling @AIMindCrafter
+# Docs / examples / stories / skills — maintainer owns merge.
+# Area owners (see docs/area-owners.md) triage and review by assignment;
+# they are not listed here because CODEOWNERS auto-requests block fork PRs
+# even when the branch ruleset does not require a code-owner review.
+/docs/ @cobusgreyling
+/examples/ @cobusgreyling
+/stories/ @cobusgreyling
+/skills/ @cobusgreyling
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4b489c3..f542512 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -72,7 +72,7 @@ npm run check:loop-init
## Area owners
-See [docs/area-owners.md](./docs/area-owners.md). Docs/examples/stories PRs are co-reviewed by [@AIMindCrafter](https://github.com/AIMindCrafter) (CODEOWNERS).
+See [docs/area-owners.md](./docs/area-owners.md). Docs/examples/stories/skills PRs are triaged by [@AIMindCrafter](https://github.com/AIMindCrafter) **by assignment** (not CODEOWNERS — auto-requests were blocking fork PRs). Content-only fork PRs get required `validate`/`audit` statuses from `.github/workflows/fork-pr-gate.yml`.
## Pull Request Checklist
diff --git a/LOOP.md b/LOOP.md
index 91f6be1..9a00e10 100644
--- a/LOOP.md
+++ b/LOOP.md
@@ -9,9 +9,9 @@ The goal of this repo is to be the canonical, copyable, high-signal collection o
### Daily Triage (L1 — automated + report)
- Cadence: 1d weekdays (`/.github/workflows/daily-triage.yml`)
- Skill: `loop-triage` (from `skills/` and `starters/minimal-loop`)
-- State: STATE.md (updated by workflow; human reviews weekly issue)
+- State: STATE.md (written by `scripts/github-triage.mjs` from **open PRs + issues**, not from the Loop Ready score)
- Phase: Report-only. Human reviews and decides actions.
-- Handoff: Design decisions, large refactors, new pattern acceptance.
+- Handoff: Blocked fork PRs, unanswered issues, design decisions, new pattern acceptance.
### PR Babysitter (L2 — assisted, manual trigger)
- Cadence: 10–15m during active hours (maintainer `/loop` or future Action)
@@ -81,7 +81,8 @@ bash scripts/before-after-demo.sh
| Loop | Level | Automation | Notes |
|------|-------|------------|-------|
-| Daily Triage | L1 | ✅ `daily-triage.yml` | Weekdays; updates `STATE.md` + `loop-run-log.md` |
+| Daily Triage | L1 | ✅ `daily-triage.yml` | Weekdays; `github-triage.mjs` writes `STATE.md` from open PRs/issues |
+| Fork PR gate | L1 | ✅ `fork-pr-gate.yml` | Content-only fork PRs get `validate`/`audit` statuses without workflow approval |
| Changelog Drafter | L1 | ✅ `changelog-drafter.yml` | Mondays; opens release-prep issue |
| Star History | L1 | ✅ `update-star-history.yml` | Daily; auto-PR to `main`; needs `STAR_HISTORY_TOKEN` secret (PAT). Skips (success) if secret unset — safe for forks |
| Validate + Audit | L1 | ✅ `validate-patterns.yml`, `audit.yml` | On PR + push; readiness score on PRs |
diff --git a/README.md b/README.md
index a16c145..025802e 100644
--- a/README.md
+++ b/README.md
@@ -76,6 +76,7 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent
## Contents
- [Quickstart (5 min)](docs/QUICKSTART.md)
+- [What do you want to do?](docs/jobs.md)
- [Quick Links](#quick-links)
- [Why This Matters](#why-this-matters)
- [The Five Building Blocks + Memory](#the-five-building-blocks--memory)
@@ -94,6 +95,7 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent
| Start here | Description |
|------------|-------------|
| [Quickstart (5 min)](docs/QUICKSTART.md) | `loop init` → `loop doctor` → first loop — **start here if you just landed** |
+| [What do you want to do?](docs/jobs.md) | Jobs table: keep the repo healthy vs **ship a refactor** ([tutorial](docs/refactor.md)) |
| [CLI front door](docs/cli-front-door.md) | Unified `@cobusgreyling/loop` — old packages stay open |
| [Loop Engineering essay](https://cobusgreyling.substack.com/p/loop-engineering) | The concept, primitives, and Grok mapping — read for the why |
| [Pattern Picker](docs/pattern-picker.md) | Which loop to run first — **start here if unsure** |
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index ed471e7..8959075 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -12,6 +12,8 @@ Landed from [X](https://x.com), the [showcase](https://cobusgreyling.github.io/l
## 1. Pick your pain (30 seconds)
+Have a **feature or refactor** to finish, not a maintenance cadence? That is a different job — see [jobs.md](./jobs.md) and the [refactor / change path](./refactor.md). Do not point `daily-triage` at a whole-repo rewrite.
+
Not sure which loop? Use the [interactive pattern picker](https://cobusgreyling.github.io/loop-engineering/#interactive) on the showcase — it recommends a pattern, scaffold command, first `/loop` line, and a token estimate.
Or start with **Daily Triage** if you just want to learn loop discipline with low risk.
diff --git a/docs/area-owners.md b/docs/area-owners.md
index 8892fca..030456e 100644
--- a/docs/area-owners.md
+++ b/docs/area-owners.md
@@ -5,7 +5,7 @@ Optional community ownership for review routing. **Owner** still ships `main` an
| Area | Paths | Owner | Scope |
|------|-------|-------|--------|
| **Maintainer** | repo-wide | [@cobusgreyling](https://github.com/cobusgreyling) | Releases, tools, patterns, safety |
-| **Docs / examples / stories** | `docs/`, `examples/`, `stories/` | [@AIMindCrafter](https://github.com/AIMindCrafter) (triage + review) | QUICKSTART, tool examples, production stories, adopters-adjacent docs |
+| **Docs / examples / stories / skills** | `docs/`, `examples/`, `stories/`, `skills/` | [@AIMindCrafter](https://github.com/AIMindCrafter) (triage + review **by assignment**, not CODEOWNERS) | QUICKSTART, tool examples, production stories, skill prompts |
## What area owners do
@@ -24,4 +24,4 @@ Optional community ownership for review routing. **Owner** still ships `main` an
Multi-PR track record in the area + public invite from the maintainer. Start with [CONTRIBUTING.md](../CONTRIBUTING.md) and the [contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123).
-CODEOWNERS file: [../CODEOWNERS](../CODEOWNERS).
+CODEOWNERS ([../CODEOWNERS](../CODEOWNERS)) lists the **maintainer only**. Area owners are invited on the PR when their review is useful; putting them in CODEOWNERS auto-requests a review on every docs/examples PR and leaves fork PRs `BLOCKED` after the maintainer has already approved.
diff --git a/docs/jobs.md b/docs/jobs.md
new file mode 100644
index 0000000..2057211
--- /dev/null
+++ b/docs/jobs.md
@@ -0,0 +1,23 @@
+# What do you want to do?
+
+This repo is a **pattern library for operating agents around a codebase** — triage, babysit PRs, sweep CI, keep deps current. It is not a “finish my feature / rewrite the module” button.
+
+| I want to… | Start here | Do **not** start here |
+|------------|------------|------------------------|
+| Keep a repo healthy (issues, CI, deps, changelog) | [Quickstart](./QUICKSTART.md) → `daily-triage` | Unattended L3 on day one |
+| Land and babysit pull requests | [PR Babysitter](../patterns/pr-babysitter.md) | Merging from the loop |
+| Fix a red build | [CI Sweeper](../patterns/ci-sweeper.md) | Patching flakes forever |
+| Upgrade dependencies safely | [Dependency Sweeper](../patterns/dependency-sweeper.md) | Major bumps without a human |
+| **Ship a feature or refactor** (break work into todos, run them) | **[Refactor / change path](./refactor.md)** | A single “refactor the repo” loop |
+| Run until a scoped objective is done | [Goal Engineering](https://github.com/cobusgreyling/goal-engineering) (`/goal`) | Pretending `daily-triage` is a task runner |
+| Persist memory across sessions | [Memory Engineering](https://github.com/cobusgreyling/memory-engineering) | Stuffing everything into `STATE.md` |
+| Govern many agents | [Fleet Engineering](https://github.com/cobusgreyling/fleet-engineering) | One `LOOP.md` for a whole org |
+
+**Week-one rule still applies:** report only. Read what the loop writes before you let it act.
+
+```bash
+npx @cobusgreyling/loop init . --pattern daily-triage --tool grok
+npx @cobusgreyling/loop doctor .
+```
+
+Swap `--tool` for `claude`, `codex`, or `opencode`. Unsure which pattern? [Pattern picker](https://cobusgreyling.github.io/loop-engineering/#interactive).
diff --git a/docs/pattern-picker.md b/docs/pattern-picker.md
index dfcf619..945e0b9 100644
--- a/docs/pattern-picker.md
+++ b/docs/pattern-picker.md
@@ -4,7 +4,9 @@ Pick one primary loop per concern. Overlapping loops need coordination — see [
```mermaid
flowchart TD
- A[What hurts right now?] --> B{CI red?}
+ A[What hurts right now?] --> R{Feature or refactor to finish?}
+ R -->|yes| S[Refactor / change path — not a cadence loop]
+ R -->|no| B{CI red?}
B -->|yes| C[CI Sweeper]
B -->|no| D{PRs stalling?}
D -->|yes| E[PR Babysitter]
@@ -21,6 +23,8 @@ flowchart TD
N -->|no| G
```
+Shipping a change (not operating the repo) is documented in [refactor.md](./refactor.md) — there is no whole-repo refactor pattern.
+
## Cost-aware picks
Estimate before you schedule:
diff --git a/docs/refactor.md b/docs/refactor.md
new file mode 100644
index 0000000..0b77433
--- /dev/null
+++ b/docs/refactor.md
@@ -0,0 +1,79 @@
+# Refactor / change path
+
+**There is no “refactor the whole project” pattern.** That is deliberate. A multi-file rewrite sits in the high-risk zone in [safety.md](./safety.md) (denylist + max-files). Loop engineering’s job is to **decompose** that work and run each slice through a maker → verifier → human loop — not to L3 the tree overnight.
+
+If you arrived from “I have a refactor, how do I break it into todos and automate it?” — this is the tutorial. Companion for run-until-done on a **scoped** objective: [goal-engineering](https://github.com/cobusgreyling/goal-engineering).
+
+## The boundary
+
+| This repo (loop-engineering) | Goal-engineering |
+|------------------------------|------------------|
+| Discovers work (triage), babysits PRs, sweeps CI | Finishes a named objective (`/goal`) |
+| `STATE.md` is a queue | A goal has a done-definition and a verifier |
+| Cadence loops (1d, 15m) | Run until the goal is met or the budget trips |
+
+Use **both**: triage to list the slices, `/goal` (or a human) to implement one slice, PR babysitter to land it.
+
+## Path (L1 → L2 → maybe later L3)
+
+### 0. Scaffold, do not code
+
+```bash
+npx @cobusgreyling/loop init . --pattern daily-triage --tool opencode
+npx @cobusgreyling/loop doctor .
+```
+
+`--tool opencode` matches the usual “I want a CLI agent on a schedule” setup. `grok` / `claude` / `codex` work the same. This writes `STATE.md`, `LOOP.md`, `loop-budget.md`, `loop-run-log.md`, and constraints. **Week one: report only.**
+
+### 1. Inventory (L1)
+
+Run daily triage against the repo. The output belongs in `STATE.md` High Priority / Watch — dead code, missing tests, modules to split — **not** in a 40-file PR.
+
+- Pattern: [daily-triage](../patterns/daily-triage.md)
+- OpenCode: [examples/opencode/daily-triage.md](../examples/opencode/daily-triage.md)
+
+A single High Priority line should be small enough for one PR (one module, one test gap, one rename). If it is not, split it before anyone codes.
+
+### 2. One todo = one worktree = one PR (L2)
+
+For each High Priority item:
+
+1. `npx @cobusgreyling/loop-worktree create --run-id <id> --pattern pr-babysitter` (or a manual git worktree).
+2. Implementer changes **only that slice**.
+3. Independent verifier runs the project tests — not the same session, not “looks good”.
+4. Human reviews the PR. The loop does not merge.
+
+- Pattern: [pr-babysitter](../patterns/pr-babysitter.md)
+- OpenCode: [examples/opencode/pr-babysitter.md](../examples/opencode/pr-babysitter.md) · starter: [starters/pr-babysitter-opencode](../starters/pr-babysitter-opencode/)
+- Isolation: [loop-worktree](../tools/loop-worktree/) · [loop-sandbox](../tools/loop-sandbox/)
+
+Optional: name the slice as a `/goal` in [goal-engineering](https://github.com/cobusgreyling/goal-engineering) so the agent has an explicit done-definition instead of “keep refactoring.”
+
+### 3. Automate only what you already trust
+
+After several L2 slices have landed with a real verifier:
+
+- Formatting, tests-only, docs: may go on an auto-merge **allowlist** (`gate.yaml`).
+- Core logic, public API, auth, payments: **denylist**, forever, human merge.
+- Check [loop-design-checklist.md](./loop-design-checklist.md) before anything unattended.
+- Do **not** jump to L3 on the refactor as a whole.
+
+### 4. After each merge
+
+[Post-merge cleanup](../patterns/post-merge-cleanup.md) for leftover TODOs and changelog noise. Then the next STATE.md line.
+
+## Why not one L3 loop?
+
+- Attempt caps exist because infinite fix loops are a known [failure mode](./failure-modes.md).
+- `maxFiles` in `gate.yaml` will escalate a “rewrite src/” diff.
+- A verifier in the same run as the implementer is theater.
+- Token budget on a whole-repo rewrite will burn before the tests go green.
+
+The valuable move is boring: **many small PRs**, each with a verifier, each with a human on the merge button until the allowlist has earned the right to grow.
+
+## Related
+
+- [jobs.md](./jobs.md) — if you wanted a different job
+- [QUICKSTART.md](./QUICKSTART.md) — 5-minute scaffold
+- [safety.md](./safety.md) — denylist / max-files
+- [loop-design-checklist.md](./loop-design-checklist.md) — L3 gates
diff --git a/scripts/ci-validate-gates.sh b/scripts/ci-validate-gates.sh
index 45b47db..65cd29f 100755
--- a/scripts/ci-validate-gates.sh
+++ b/scripts/ci-validate-gates.sh
@@ -37,6 +37,7 @@ node scripts/check-loop-init-sync.mjs
echo "Smoke-testing scripts…"
node scripts/append-run-log.test.mjs
+node scripts/github-triage.test.mjs
echo "Building and testing readiness-core…"
(
diff --git a/scripts/github-triage.mjs b/scripts/github-triage.mjs
new file mode 100644
index 0000000..045af07
--- /dev/null
+++ b/scripts/github-triage.mjs
@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+/**
+ * Inspect live GitHub (open PRs + issues) and write STATE.md High Priority
+ * from that signal — not from the Loop Ready score.
+ *
+ * node scripts/github-triage.mjs --score 100 --level L3 --out-md STATE.md
+ *
+ * Tests pass fixture JSON via --prs-json / --issues-json (no network).
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFile, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+const exec = promisify(execFile);
+const DAY = 24 * 60 * 60 * 1000;
+
+export function parseArgs(argv) {
+ const out = {
+ score: '—',
+ level: '—',
+ failingWorkflows: 0,
+ outMd: '',
+ outJson: '',
+ prsJson: '',
+ issuesJson: '',
+ };
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i];
+ const next = () => argv[++i];
+ if (a === '--score') out.score = next();
+ else if (a === '--level') out.level = next();
+ else if (a === '--failing-workflows') out.failingWorkflows = Number(next()) || 0;
+ else if (a === '--out-md') out.outMd = next();
+ else if (a === '--out-json') out.outJson = next();
+ else if (a === '--prs-json') out.prsJson = next();
+ else if (a === '--issues-json') out.issuesJson = next();
+ else if (a === '--help' || a === '-h') out.help = true;
+ }
+ return out;
+}
+
+function labelsOf(item) {
+ return (item.labels || []).map((l) => (typeof l === 'string' ? l : l.name)).filter(Boolean);
+}
+
+function commentCount(issue) {
+ if (typeof issue.comments === 'number') return issue.comments;
+ if (Array.isArray(issue.comments)) return issue.comments.length;
+ if (typeof issue.commentsCount === 'number') return issue.commentsCount;
+ return 0;
+}
+
+function ageMs(iso, now) {
+ if (!iso) return 0;
+ return Math.max(0, now - new Date(iso).getTime());
+}
+
+function checksOf(pr) {
+ const rollup = pr.statusCheckRollup || [];
+ const fail = rollup.filter((c) => c.conclusion === 'FAILURE' || c.conclusion === 'ERROR');
+ const pending = rollup.filter(
+ (c) => c.status === 'IN_PROGRESS' || c.status === 'QUEUED' || (!c.conclusion && c.status !== 'COMPLETED'),
+ );
+ return { total: rollup.length, fail, pending };
+}
+
+/**
+ * Classify one open PR. Returns { bucket: 'high'|'watch'|'noise', line }.
+ */
+export function classifyPr(pr, now = Date.now()) {
+ const n = `#${pr.number}`;
+ const title = (pr.title || '').replace(/\s+/g, ' ').trim();
+ const url = pr.url || '';
+ const link = url ? `[${n}](${url})` : n;
+ const mss = pr.mergeStateStatus || '';
+ const { total, fail } = checksOf(pr);
+ const author = pr.author?.login || pr.author?.name || 'unknown';
+
+ if (pr.isDraft) {
+ const stale = ageMs(pr.updatedAt || pr.createdAt, now) > 30 * DAY;
+ return {
+ bucket: stale ? 'watch' : 'noise',
+ line: `- Draft ${link} ${title} (@${author}${stale ? '; idle >30d' : ''})`,
+ };
+ }
+
+ if (mss === 'DIRTY' || pr.mergeable === 'CONFLICTING') {
+ return { bucket: 'high', line: `- ${link} **conflicts** — ${title}` };
+ }
+ if (fail.length > 0) {
+ const names = fail.map((c) => c.name).filter(Boolean).slice(0, 3).join(', ');
+ return { bucket: 'high', line: `- ${link} **CI red** (${names || fail.length} failing) — ${title}` };
+ }
+ if (total === 0) {
+ return {
+ bucket: 'high',
+ line: `- ${link} **no CI** (fork workflow likely waiting for approval) — ${title}`,
+ };
+ }
+ if (mss === 'BLOCKED') {
+ return { bucket: 'high', line: `- ${link} **blocked** (missing required checks or review) — ${title}` };
+ }
+ if (pr.reviewDecision === 'CHANGES_REQUESTED') {
+ return { bucket: 'high', line: `- ${link} **changes requested** — ${title}` };
+ }
+ if (mss === 'UNSTABLE') {
+ return { bucket: 'watch', line: `- ${link} merge UNSTABLE — ${title}` };
+ }
+ if (mss === 'CLEAN' || mss === 'HAS_HOOKS' || mss === 'BEHIND') {
+ return { bucket: 'watch', line: `- ${link} CI green, waiting on review/merge — ${title}` };
+ }
+ return { bucket: 'watch', line: `- ${link} ${mss || 'open'} — ${title}` };
+}
+
+/**
+ * Classify one open issue.
+ */
+export function classifyIssue(issue, now = Date.now()) {
+ const n = `#${issue.number}`;
+ const title = (issue.title || '').replace(/\s+/g, ' ').trim();
+ const url = issue.url || '';
+ const link = url ? `[${n}](${url})` : n;
+ const labels = labelsOf(issue);
+ const comments = commentCount(issue);
+ const age = ageMs(issue.createdAt, now);
+ const idle = ageMs(issue.updatedAt || issue.createdAt, now);
+ const author = issue.author?.login || 'unknown';
+ const isBot = Boolean(issue.author?.is_bot) || /\[bot\]$/.test(author) || author === 'app/github-actions';
+
+ if (labels.includes('good first issue') && age > 21 * DAY) {
+ return {
+ bucket: 'watch',
+ line: `- ${link} stale **good first issue** (${Math.floor(age / DAY)}d) — ${title}`,
+ };
+ }
+ if (labels.includes('loop-report') || labels.includes('release-prep')) {
+ return {
+ bucket: idle > 21 * DAY ? 'watch' : 'noise',
+ line: `- ${link} ${labels.includes('release-prep') ? 'release-prep' : 'loop-report'} — ${title}`,
+ };
+ }
+ if (!isBot && comments === 0 && age > 7 * DAY) {
+ return {
+ bucket: 'high',
+ line: `- ${link} **unanswered** ${Math.floor(age / DAY)}d — ${title}`,
+ };
+ }
+ if (!isBot && idle > 14 * DAY) {
+ return {
+ bucket: 'watch',
+ line: `- ${link} idle ${Math.floor(idle / DAY)}d — ${title}`,
+ };
+ }
+ return { bucket: 'noise', line: `- ${link} ${title}` };
+}
+
+export function buildSections({ prs = [], issues = [] }, now = Date.now()) {
+ const high = [];
+ const watch = [];
+ const noise = [];
+ const push = (item) => {
+ if (item.bucket === 'high') high.push(item.line);
+ else if (item.bucket === 'watch') watch.push(item.line);
+ else noise.push(item.line);
+ };
+ for (const pr of prs) push(classifyPr(pr, now));
+ for (const issue of issues) push(classifyIssue(issue, now));
+ return { high, watch, noise };
+}
+
+export function renderState({ high, watch, noise, score, level, date, failingWorkflows = 0 }) {
+ const extraHigh =
+ failingWorkflows > 0
+ ? [
+ `- **${failingWorkflows}** dogfood workflow(s) failing — investigate \`validate-patterns\` / \`audit\`.`,
+ ]
+ : [];
+ const highLines = [...extraHigh, ...high];
+ const highBody =
+ highLines.length > 0
+ ? highLines.join('\n')
+ : '- No blocked PRs, failing checks, or unanswered issues.';
+ const watchBody =
+ watch.length > 0
+ ? watch.join('\n')
+ : '- Expand contributor failure stories (dependency sweeper, multi-loop).\n- Collect a production story for Post-Merge Cleanup.';
+ const noiseBody = noise.length > 0 ? noise.slice(0, 8).join('\n') : '—';
+ const scoreNote =
+ Number(score) < 58
+ ? `- Loop Ready **${score}** (${level}) is below the 58 floor — investigate audit gaps.`
+ : `- Loop Ready **${score}** (${level}) — informational, not a reason to act.`;
+
+ return `# Loop State — loop-engineering reference
+
+Last run: ${date} (automated daily-triage workflow)
+
+## High Priority (loop is acting or waiting on human)
+
+${highBody}
+${Number(score) < 58 ? `${scoreNote}\n` : ''}
+## Watch List
+
+${watchBody}
+${Number(score) >= 58 ? `\n${scoreNote}` : ''}
+
+## Recent Noise (ignored this run)
+
+${noiseBody}
+
+---
+Run log: Updated by \`.github/workflows/daily-triage.yml\` via \`scripts/github-triage.mjs\`. See \`LOOP.md\` for cadence and gates.
+`;
+}
+
+async function ghJson(args) {
+ const { stdout } = await exec('gh', args, { maxBuffer: 10 * 1024 * 1024 });
+ return JSON.parse(stdout);
+}
+
+async function loadList(pathOrEmpty, fetcher) {
+ if (pathOrEmpty) {
+ return JSON.parse(await readFile(pathOrEmpty, 'utf8'));
+ }
+ return fetcher();
+}
+
+async function main(argv = process.argv.slice(2)) {
+ const args = parseArgs(argv);
+ if (args.help) {
+ console.log(
+ 'Usage: github-triage.mjs [--score N] [--level L] [--out-md FILE] [--out-json FILE] [--prs-json FILE] [--issues-json FILE]',
+ );
+ return 0;
+ }
+
+ const prs = await loadList(args.prsJson, () =>
+ ghJson([
+ 'pr',
+ 'list',
+ '--state',
+ 'open',
+ '--limit',
+ '50',
+ '--json',
+ 'number,title,url,isDraft,mergeStateStatus,mergeable,reviewDecision,statusCheckRollup,author,updatedAt,createdAt',
+ ]),
+ );
+ const issues = await loadList(args.issuesJson, () =>
+ ghJson([
+ 'issue',
+ 'list',
+ '--state',
+ 'open',
+ '--limit',
+ '50',
+ '--json',
+ 'number,title,url,labels,createdAt,updatedAt,author,comments',
+ ]),
+ );
+
+ const date = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+ const sections = buildSections({ prs, issues });
+ const md = renderState({
+ ...sections,
+ score: args.score,
+ level: args.level,
+ date,
+ failingWorkflows: args.failingWorkflows,
+ });
+ const summary = {
+ high: sections.high.length,
+ watch: sections.watch.length,
+ noise: sections.noise.length,
+ items_found: sections.high.length + sections.watch.length,
+ };
+
+ if (args.outMd) await writeFile(args.outMd, md);
+ else process.stdout.write(md);
+ if (args.outJson) await writeFile(args.outJson, JSON.stringify(summary, null, 2) + '\n');
+ console.error(
+ `github-triage: high=${summary.high} watch=${summary.watch} noise=${summary.noise}`,
+ );
+ return 0;
+}
+
+const isMain = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+if (isMain) {
+ main().then(
+ (code) => process.exit(code),
+ (err) => {
+ console.error(err);
+ process.exit(1);
+ },
+ );
+}
diff --git a/scripts/github-triage.test.mjs b/scripts/github-triage.test.mjs
new file mode 100644
index 0000000..7168f9d
--- /dev/null
+++ b/scripts/github-triage.test.mjs
@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, writeFile, rm, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { classifyPr, classifyIssue, buildSections, renderState } from './github-triage.mjs';
+
+const exec = promisify(execFile);
+const SCRIPT = new URL('./github-triage.mjs', import.meta.url).pathname;
+const NOW = Date.parse('2026-08-26T12:00:00Z');
+
+test('classifyPr: empty checks is high (fork CI not approved)', () => {
+ const r = classifyPr(
+ {
+ number: 543,
+ title: 'Improve loop constraints startup message',
+ url: 'https://github.com/cobusgreyling/loop-engineering/pull/543',
+ isDraft: false,
+ mergeStateStatus: 'BLOCKED',
+ statusCheckRollup: [],
+ },
+ NOW,
+ );
+ assert.equal(r.bucket, 'high');
+ assert.match(r.line, /no CI/);
+ assert.match(r.line, /#543/);
+});
+
+test('classifyPr: conflicts beat green CI', () => {
+ const r = classifyPr(
+ {
+ number: 41,
+ title: 'bump changesets',
+ mergeable: 'CONFLICTING',
+ mergeStateStatus: 'DIRTY',
+ statusCheckRollup: [{ conclusion: 'SUCCESS', status: 'COMPLETED', name: 'validate' }],
+ },
+ NOW,
+ );
+ assert.equal(r.bucket, 'high');
+ assert.match(r.line, /conflicts/);
+});
+
+test('classifyPr: failing check is high', () => {
+ const r = classifyPr(
+ {
+ number: 12,
+ title: 'ruff bump',
+ mergeStateStatus: 'UNSTABLE',
+ statusCheckRollup: [{ conclusion: 'FAILURE', status: 'COMPLETED', name: 'test' }],
+ },
+ NOW,
+ );
+ assert.equal(r.bucket, 'high');
+ assert.match(r.line, /CI red/);
+});
+
+test('classifyPr: clean ready PR is watch, not high', () => {
+ const r = classifyPr(
+ {
+ number: 537,
+ title: 'successRatePct',
+ mergeStateStatus: 'CLEAN',
+ statusCheckRollup: [{ conclusion: 'SUCCESS', status: 'COMPLETED', name: 'validate' }],
+ },
+ NOW,
+ );
+ assert.equal(r.bucket, 'watch');
+ assert.match(r.line, /waiting on review/);
+});
+
+test('classifyPr: draft is noise unless idle 30d', () => {
+ const fresh = classifyPr(
+ { number: 1, title: 'wip', isDraft: true, updatedAt: '2026-08-20T00:00:00Z' },
+ NOW,
+ );
+ assert.equal(fresh.bucket, 'noise');
+ const stale = classifyPr(
+ { number: 1, title: 'wip', isDraft: true, updatedAt: '2026-06-01T00:00:00Z' },
+ NOW,
+ );
+ assert.equal(stale.bucket, 'watch');
+});
+
+test('classifyIssue: unanswered human issue >7d is high', () => {
+ const r = classifyIssue(
+ {
+ number: 522,
+ title: 'refactor todos',
+ url: 'https://github.com/cobusgreyling/loop-engineering/issues/522',
+ createdAt: '2026-08-15T00:00:00Z',
+ updatedAt: '2026-08-15T00:00:00Z',
+ comments: 0,
+ author: { login: 'hufeide' },
+ labels: [{ name: 'pattern-request' }],
+ },
+ NOW,
+ );
+ assert.equal(r.bucket, 'high');
+ assert.match(r.line, /unanswered/);
+});
+
+test('classifyIssue: stale good-first-issue is watch', () => {
+ const r = classifyIssue(
+ {
+ number: 118,
+ title: 'Share a story',
+ createdAt: '2026-07-01T00:00:00Z',
+ updatedAt: '2026-07-20T00:00:00Z',
+ comments: 2,
+ labels: [{ name: 'good first issue' }],
+ author: { login: 'cobusgreyling' },
+ },
+ NOW,
+ );
+ assert.equal(r.bucket, 'watch');
+ assert.match(r.line, /good first issue/);
+});
+
+test('classifyIssue: bot loop-report is noise unless very idle', () => {
+ const r = classifyIssue(
+ {
+ number: 403,
+ title: 'Loop report',
+ createdAt: '2026-08-20T00:00:00Z',
+ updatedAt: '2026-08-20T00:00:00Z',
+ comments: 0,
+ labels: [{ name: 'loop-report' }],
+ author: { login: 'github-actions[bot]', is_bot: true },
+ },
+ NOW,
+ );
+ assert.equal(r.bucket, 'noise');
+});
+
+test('renderState: score 100 is watch, not high, when GitHub is quiet', () => {
+ const md = renderState({
+ high: [],
+ watch: [],
+ noise: [],
+ score: '100',
+ level: 'L3',
+ date: '2026-08-26T12:00:00Z',
+ });
+ assert.match(md, /No blocked PRs/);
+ assert.match(md, /informational, not a reason to act/);
+ const highBlock = md.split('## Watch List')[0];
+ assert.doesNotMatch(highBlock, /Loop Ready \*\*100\*\*/);
+ assert.match(md.split('## Watch List')[1], /Loop Ready \*\*100\*\*/);
+});
+
+test('renderState: failing dogfood workflows are high even at score 100', () => {
+ const md = renderState({
+ high: [],
+ watch: [],
+ noise: [],
+ score: '100',
+ level: 'L3',
+ date: '2026-08-26T12:00:00Z',
+ failingWorkflows: 2,
+ });
+ assert.match(md, /\*\*2\*\* dogfood workflow/);
+});
+
+test('renderState: score below 58 is high', () => {
+ const md = renderState({
+ high: [],
+ watch: [],
+ noise: [],
+ score: '40',
+ level: 'L1',
+ date: '2026-08-26T12:00:00Z',
+ });
+ assert.match(md, /below the 58 floor/);
+});
+
+test('CLI writes STATE.md from fixtures without calling gh', async () => {
+ const dir = await mkdtemp(path.join(tmpdir(), 'github-triage-'));
+ try {
+ const prs = path.join(dir, 'prs.json');
+ const issues = path.join(dir, 'issues.json');
+ const outMd = path.join(dir, 'STATE.md');
+ const outJson = path.join(dir, 'summary.json');
+ await writeFile(
+ prs,
+ JSON.stringify([
+ {
+ number: 543,
+ title: 'constraints',
+ url: 'https://example.test/543',
+ isDraft: false,
+ mergeStateStatus: 'BLOCKED',
+ statusCheckRollup: [],
+ },
+ ]),
+ );
+ await writeFile(issues, JSON.stringify([]));
+ const { stderr } = await exec('node', [
+ SCRIPT,
+ '--score',
+ '100',
+ '--level',
+ 'L3',
+ '--prs-json',
+ prs,
+ '--issues-json',
+ issues,
+ '--out-md',
+ outMd,
+ '--out-json',
+ outJson,
+ ]);
+ assert.match(stderr, /high=1/);
+ const md = await readFile(outMd, 'utf8');
+ assert.match(md, /no CI/);
+ assert.match(md, /#543/);
+ const summary = JSON.parse(await readFile(outJson, 'utf8'));
+ assert.equal(summary.high, 1);
+ } finally {
+ await rm(dir, { recursive: true, force: true });
+ }
+});
+
+test('buildSections counts mixed buckets', () => {
+ const { high, watch } = buildSections(
+ {
+ prs: [
+ { number: 1, title: 'a', mergeStateStatus: 'CLEAN', statusCheckRollup: [{ conclusion: 'SUCCESS', status: 'COMPLETED' }] },
+ { number: 2, title: 'b', mergeStateStatus: 'BLOCKED', statusCheckRollup: [] },
+ ],
+ issues: [],
+ },
+ NOW,
+ );
+ assert.equal(high.length, 1);
+ assert.equal(watch.length, 1);
+});
diff --git a/skills/loop-triage/SKILL.md b/skills/loop-triage/SKILL.md
index 6ca6e91..067051c 100644
--- a/skills/loop-triage/SKILL.md
+++ b/skills/loop-triage/SKILL.md
@@ -13,11 +13,14 @@ You are an expert engineering triage agent. Your job is to produce a clean, prio
## Inputs (the loop will provide these)
- Recent CI / test failures (last 24h)
-- Open issues / Linear tickets assigned to the team
+- Open PRs: merge conflicts, failing checks, **no CI** (fork workflows waiting for approval), `BLOCKED`, changes requested
+- Open issues / Linear tickets — especially unanswered >7d and stale `good first issue`s
- Recent commits on main (last 24–48h)
- Any Slack / chat threads the loop has visibility into
- The current state file (what the loop already knows about)
+On this reference repo, `scripts/github-triage.mjs` (via `.github/workflows/daily-triage.yml`) is the mechanical source for High Priority. A Loop Ready score of 100 is **watch**, not an all-clear, if GitHub still has blocked PRs.
+
## Output Format
Produce a markdown report with these sections: