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.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
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.ymlindex 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.mdid: 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 ]; thenOUTCOME="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.ymlnew file mode 100644index 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.ymlindex 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/CODEOWNERSindex 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/ @cobusgreylingdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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 Checklistdiff --git a/LOOP.md b/LOOP.mdindex 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.mdindex 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.mdindex 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.mdindex 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` anMulti-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.mdnew file mode 100644index 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.mdindex 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 [```mermaidflowchart 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 TDN -->|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 picksEstimate before you schedule:diff --git a/docs/refactor.md b/docs/refactor.mdnew file mode 100644index 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 gatesdiff --git a/scripts/ci-validate-gates.sh b/scripts/ci-validate-gates.shindex 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.mjsecho "Smoke-testing scripts…"node scripts/append-run-log.test.mjs+node scripts/github-triage.test.mjsecho "Building and testing readiness-core…"(diff --git a/scripts/github-triage.mjs b/scripts/github-triage.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mdindex 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 FormatProduce a markdown report with these sections: