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
feat(github): add issue/PR templates, dependabot, and dogfood workflows (validate-patterns + audit)
Cobus Greyling9651092da7ba
diff --git a/.github/FUNDING.yml b/.github/FUNDING.ymlnew file mode 100644index 0000000..b5a6620--- /dev/null+++ b/.github/FUNDING.yml@@ -0,0 +1 @@+github: [cobusgreyling]diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.mdnew file mode 100644index 0000000..1d6dd5b--- /dev/null+++ b/.github/ISSUE_TEMPLATE/bug-report.md@@ -0,0 +1,27 @@+---+name: Bug report (for the reference, starters, loop-audit, or docs)+about: Something is broken, inaccurate, or the audit gives wrong results+labels: bug+---++**Describe the bug**:++**Steps to reproduce**:+1.+2.++**Expected behavior**:++**Actual behavior** (include output of `loop-audit --json` or command if relevant):++**Environment**:+- OS:+- Node (for audit):+- Tool used (Grok / Claude / Codex / GH Actions):+- Target repo (if not this one):++**Additional context** (links to patterns, commits, screenshots):++---++*If this is a pattern or safety issue, please also reference `docs/safety.md` or `docs/failure-modes.md`.*diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.ymlnew file mode 100644index 0000000..d9c3ac6--- /dev/null+++ b/.github/ISSUE_TEMPLATE/config.yml@@ -0,0 +1,26 @@+blank_issues_enabled: false+contact_links:+ - name: "\u2753 Question or Discussion"+ url: https://github.com/cobusgreyling/loop-engineering/discussions+ about: "For general questions, ideas, or chat about loop engineering, use Discussions."+contact_links:+ - name: "\ud83d\udc1b Report an issue with the docs site or showcase"+ url: https://github.com/cobusgreyling/loop-engineering/issues/new?labels=docs+ about: "Use the bug report template for the reference itself."++labels:+ - name: "pattern-request"+ description: "Request for a new documented loop pattern"+ color: "0e8a16"+ - name: "story"+ description: "Production story or failure report"+ color: "5319e7"+ - name: "tooling"+ description: "loop-audit, registry, starters, templates"+ color: "1d76db"+ - name: "docs"+ description: "Documentation, primitives, checklist, showcase"+ color: "bfd4f2"+ - name: "good first issue"+ description: "Good for newcomers"+ color: "7057ff"diff --git a/.github/ISSUE_TEMPLATE/pattern-request.md b/.github/ISSUE_TEMPLATE/pattern-request.mdnew file mode 100644index 0000000..5342c80--- /dev/null+++ b/.github/ISSUE_TEMPLATE/pattern-request.md@@ -0,0 +1,27 @@+---+name: Pattern request+about: Suggest a new reusable loop pattern with production potential+labels: pattern-request+---++**Pattern name idea**:++**What problem does it solve?** (one paragraph)++**Typical cadence**:++**Risk level** (low / medium / high):++**Target tools** (Grok / Claude Code / Codex / GitHub Actions / other):++**Why this belongs in the reference** (real usage or strong signal from others):++**Proposed skills** (triage, fix, verify...):++**Human gates you expect**:++**Any existing starter code or notes** (links, private repo redacted examples):++---++*We will turn accepted requests into full `patterns/*.md` + `registry.yaml` entry + starter + at least one story following the template.*diff --git a/.github/ISSUE_TEMPLATE/share-story.md b/.github/ISSUE_TEMPLATE/share-story.mdnew file mode 100644index 0000000..35ad02d--- /dev/null+++ b/.github/ISSUE_TEMPLATE/share-story.md@@ -0,0 +1,25 @@+---+name: Share a production story (wins or failures)+about: Real-world loop engineering experience. Failures and surprises are first-class.+labels: story+---++**Pattern(s) used**:++**Context** (team size, tools, repo(s), what you were trying to automate):++**What worked**:++**What broke or surprised you** (required — honest failures make the reference valuable):++**Metrics or qualitative outcome** (time saved, PRs merged, incidents avoided, tokens burned, etc.):++**Actionable lesson** (one crisp paragraph others can apply):++**Would you run this unattended today?** (L1 / L2 / L3 and why):++**Artifacts you can share** (redacted state snippets, skill text, workflow yml, screenshots — attach or paste):++---++Thank you. These stories are the most valuable part of the project.diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.mdnew file mode 100644index 0000000..13a3b70--- /dev/null+++ b/.github/PULL_REQUEST_TEMPLATE.md@@ -0,0 +1,27 @@+## Summary+<!-- One sentence what this does and why -->++## Changes+- [ ] New pattern or starter (followed `templates/pattern-template.md` + updated `registry.yaml`)+- [ ] Doc / example improvement+- [ ] Tool change (loop-audit)+- [ ] Story (includes real failure or surprise + lesson)++## Checklist (from CONTRIBUTING)+- [ ] All required sections present for patterns+- [ ] Links work from README, patterns/README, starters/README, docs/index+- [ ] No secrets, tokens, internal company URLs+- [ ] `STATE.md*` examples use `.example` suffix+- [ ] Safety-related content references `docs/safety.md`+- [ ] Ran `node tools/loop-audit/dist/cli.js .` (or on the starter) and addressed findings++## Testing / Dogfood+- [ ] `loop-audit` passes on affected starters or this repo+- [ ] Manual review of generated state / skill output++## Screenshots / Examples (if UI or command output)+<!-- Paste relevant output or link to rendered docs -->++---++*This template enforces the high bar this reference is known for.*diff --git a/.github/dependabot.yml b/.github/dependabot.ymlnew file mode 100644index 0000000..1fa49f4--- /dev/null+++ b/.github/dependabot.yml@@ -0,0 +1,13 @@+version: 2+updates:+ - package-ecosystem: "npm"+ directory: "/tools/loop-audit"+ schedule:+ interval: "weekly"+ open-pull-requests-limit: 3+ commit-message:+ prefix: "chore(audit)"+ - package-ecosystem: "github-actions"+ directory: "/"+ schedule:+ interval: "weekly"diff --git a/.github/workflows/audit.yml b/.github/workflows/audit.ymlnew file mode 100644index 0000000..308aa1e--- /dev/null+++ b/.github/workflows/audit.yml@@ -0,0 +1,48 @@+name: Loop Readiness Audit (dogfood)++on:+ push:+ branches: [main]+ pull_request:+ branches: [main]+ schedule:+ # Daily-ish dogfood of the reference itself+ - cron: '17 9 * * *'++jobs:+ audit:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4++ - uses: actions/setup-node@v4+ with:+ node-version: '20'+ cache: 'npm'+ cache-dependency-path: tools/loop-audit/package-lock.json++ - name: Build & run loop-audit on the reference + starters+ run: |+ cd tools/loop-audit+ npm ci+ npm run build+ echo "=== Audit of repo root ==="+ node dist/cli.js ../../ || true+ echo ""+ echo "=== Audit of starters ==="+ for s in ../../starters/*/; do+ echo "--- $(basename "$s") ---"+ node dist/cli.js "$s" || true+ done++ - name: Fail on critically low score for this reference (adjust as we improve)+ run: |+ cd tools/loop-audit+ node dist/cli.js ../../ --json > /tmp/audit.json || true+ SCORE=$(node -e 'console.log(require("/tmp/audit.json").score)')+ echo "Reference score: $SCORE"+ # We expect the reference itself to be reasonably loop-ready+ if (( $(echo "$SCORE < 45" | bc -l) )); then+ echo "Reference score too low for a loop-engineering repo. Improve signals."+ exit 2+ fidiff --git a/.github/workflows/validate-patterns.yml b/.github/workflows/validate-patterns.ymlnew file mode 100644index 0000000..474761b--- /dev/null+++ b/.github/workflows/validate-patterns.yml@@ -0,0 +1,42 @@+name: Validate Patterns & Registry++on:+ push:+ branches: [main]+ pull_request:+ branches: [main]++jobs:+ validate:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4++ - name: Check registry covers all pattern files+ run: |+ set -e+ echo "Patterns declared in registry:"+ grep '^\s*-\s*id:' patterns/registry.yaml | sed 's/.*id: //' | sort > /tmp/registry.txt+ echo "Pattern markdown files:"+ ls patterns/*.md | xargs -n1 basename | sed 's/.md$//' | grep -v README | sort > /tmp/files.txt+ echo "=== Registry ==="; cat /tmp/registry.txt+ echo "=== Files ==="; cat /tmp/files.txt+ comm -23 /tmp/files.txt /tmp/registry.txt | grep . && (echo "ERROR: pattern md file(s) missing from registry.yaml"; exit 1) || echo "All pattern files registered ✓"+ comm -23 /tmp/registry.txt /tmp/files.txt | grep . && (echo "ERROR: registry entry without matching .md"; exit 1) || echo "No orphan registry entries ✓"++ - name: Verify CONTRIBUTING + template compliance (basic)+ run: |+ echo "Checking that key sections exist in patterns (lightweight)"+ for f in patterns/*.md; do+ if [[ "$f" == *"README.md" ]]; then continue; fi+ grep -q "^## Scheduling" "$f" || (echo "Missing Scheduling in $f"; exit 1)+ grep -q "^## Required Skills" "$f" || (echo "Missing Required Skills in $f"; exit 1)+ grep -q "maker.*checker\|verifier\|Maker / Checker" "$f" || (echo "Missing verifier strategy in $f"; exit 1)+ done+ echo "Basic pattern structure checks passed ✓"++ - name: Ensure templates exist+ run: |+ test -f templates/pattern-template.md || (echo "Missing pattern-template.md"; exit 1)+ test -f templates/STATE.md.template || (echo "Missing STATE template"; exit 1)+ echo "Templates present ✓"diff --git a/LOOP.md b/LOOP.mdnew file mode 100644index 0000000..2241246--- /dev/null+++ b/LOOP.md@@ -0,0 +1,59 @@+# LOOP.md — Loop Engineering Reference++This file documents how the **loop-engineering** reference repository itself is (or will be) operated with loop engineering patterns.++The goal of this repo is to be the canonical, copyable, high-signal collection of patterns, starters, and tooling. It should therefore eat its own dogfood aggressively.++## Intended Loops (phased)++### Daily Triage (L1 → L2)+- Cadence: 1d (or 2h during active development)+- Skill: loop-triage (from `starters/minimal-loop`)+- State: STATE.md (or this file + issues)+- Current phase: Report-only. Human reviews the report each day and decides what to action.+- Handoff: Design decisions, large refactors, new pattern acceptance.++### PR Babysitter (future, L2)+- Cadence: 10–15m during active hours+- Uses the `pr-babysitter` starter + worktrees for any suggested fixes.+- Will live primarily in the GitHub Actions + comments on PRs.+- Strong verifier + explicit allowlist for auto-merge (very small safe changes only).++### Dependency Sweeper (L2, just added)+- Cadence: 6h–1d+- New pattern + starter added in this iteration.+- Focus: patch + low-risk CVE only for the first 30 days.+- Verifier = full `npm ci && npm test` (or the build that exists) in worktree.+- Human gate on anything that touches core packages or majors.++### CI Sweeper / Post-Merge (opportunistic)+- The `validate-patterns.yml` + `audit.yml` workflows in `.github/workflows/` are the beginning of dogfooding these patterns.+- Future: a sweeper that reacts to failing validate/audit runs with minimal doc or link fixes.++## Safety & Gates (this repo)++- No auto-merge on main for anything except the most trivial dependency patches (and even those are behind allowlist + verifier today).+- Denylist for this reference: anything touching the showcase HTML/CSS, the core primitives docs, or the audit scoring logic without human review.+- All state that would be "live" lives in `.example` files or is maintained by the workflows (never committed live STATE).++## How to run the loops here (for contributors / the maintainer)++See the individual pattern docs and the GitHub Actions.++Quick local check:++```bash+node tools/loop-audit/dist/cli.js . --suggest+```++After changes to patterns, starters, or docs, the `validate-patterns` + `audit` workflows will run automatically on PRs.++## Evolution++We will raise the L level of this repo itself over time and record the journey in `stories/`.++Current target for the reference: solid L2 with excellent observability and zero "I had to hand-hold the loop for an hour" stories.++---++*This file is both documentation and the seed for the loops that will maintain the reference.*diff --git a/README.md b/README.mdindex 262f240..9c627b5 100644--- a/README.md+++ b/README.md@@ -6,6 +6,12 @@</a></p>+<p align="center">+ <a href="https://github.com/cobusgreyling/loop-engineering/actions/workflows/audit.yml"><img src="https://img.shields.io/github/actions/workflow/status/cobusgreyling/loop-engineering/audit.yml?label=loop-audit%20dogfood" alt="loop-audit dogfood"></a>+ <a href="https://github.com/cobusgreyling/loop-engineering/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>+ <a href="https://cobusgreyling.github.io/loop-engineering/"><img src="https://img.shields.io/badge/GitHub_Pages-live-3ee8c5" alt="Pages"></a>+</p>+<p align="center"><strong><a href="https://cobusgreyling.github.io/loop-engineering/">→ cobusgreyling.github.io/loop-engineering</a></strong></p>@@ -54,6 +60,25 @@ The leverage point has moved from crafting individual prompts to designing the cFull detail: [docs/primitives.md](docs/primitives.md) · Cross-tool matrix: [docs/primitives-matrix.md](docs/primitives-matrix.md)+### Anatomy of a Loop (Mermaid)++```mermaid+flowchart LR+ A[Schedule / Automation] --> B[Triage Skill]+ B --> C[Read + Write STATE / Memory]+ C --> D[Isolated Worktree]+ D --> E[Implementer Sub-agent]+ E --> F[Verifier Sub-agent<br/>tests + gates]+ F --> G[MCP / Git / Tickets]+ G --> H{Human Gate?}+ H -->|safe / allowlisted| I[Commit / PR / Action]+ H -->|risky / ambiguous| J[Escalate to human<br/>with full context]+ I --> A+ J --> A+```++**This reference repo now runs its own `validate-patterns` + `audit` workflows on every push/PR** (see `.github/workflows/`). We also added `LOOP.md` describing the loops that will maintain it.+## Patterns| Pattern | Cadence | Starter |@@ -62,6 +87,7 @@ Full detail: [docs/primitives.md](docs/primitives.md) · Cross-tool matrix: [doc| [Daily Triage](patterns/daily-triage.md) | 1d–2h | [starters/minimal-loop](starters/minimal-loop/) || [CI Sweeper](patterns/ci-sweeper.md) | 5–15m | [starters/ci-sweeper](starters/ci-sweeper/) || [Post-Merge Cleanup](patterns/post-merge-cleanup.md) | 1d–6h | — |+| [Dependency Sweeper](patterns/dependency-sweeper.md) | 6h–1d | [starters/dependency-sweeper](starters/dependency-sweeper/) |Machine-readable index: [patterns/registry.yaml](patterns/registry.yaml)diff --git a/docs/GITHUB_PAGES.md b/docs/GITHUB_PAGES.mdindex 44e7346..e7c1016 100644--- a/docs/GITHUB_PAGES.md+++ b/docs/GITHUB_PAGES.md@@ -5,6 +5,10 @@3. **Folder**: `/docs`4. Save — showcase at `https://cobusgreyling.github.io/loop-engineering/`-The homepage (`docs/index.md`) is the full interactive showcase with patterns, primitives, and quick-start.+The homepage (`docs/index.md`) is the full interactive showcase with patterns, primitives, quick-start, and an anatomy diagram.-First deploy may take 1–2 minutes.\ No newline at end of file+The root `README.md` and `LOOP.md` now describe how this reference dogfoods its own patterns via `.github/workflows/audit.yml` + `validate-patterns.yml`.++First deploy may take 1–2 minutes. After enabling, the daily scheduled audit workflow will also keep the published site "honest" about the reference's own loop readiness.++**Pro tip**: once live, run `node tools/loop-audit/dist/cli.js . --suggest` locally and improve the score over time — the workflows will reflect it.diff --git a/patterns/README.md b/patterns/README.mdindex 9e61831..5c6e5b1 100644--- a/patterns/README.md+++ b/patterns/README.md@@ -18,6 +18,7 @@ Each pattern answers:| Daily Triage | 1d–2h | Low | [daily-triage.md](./daily-triage.md) || CI Sweeper | 5–15m | Medium | [ci-sweeper.md](./ci-sweeper.md) || Post-Merge Cleanup | 1d–6h | Low | [post-merge-cleanup.md](./post-merge-cleanup.md) |+| Dependency Sweeper | 6h–1d | Medium | [dependency-sweeper.md](./dependency-sweeper.md) |Machine-readable index: [registry.yaml](./registry.yaml)diff --git a/patterns/dependency-sweeper.md b/patterns/dependency-sweeper.mdnew file mode 100644index 0000000..3571f51--- /dev/null+++ b/patterns/dependency-sweeper.md@@ -0,0 +1,95 @@+# Dependency Sweeper Loop++**Goal**: Discover outdated or vulnerable dependencies, apply the smallest safe updates, verify with tests/builds in isolation, and escalate anything risky (major bumps, breaking changes, or high-severity vulns) to a human.++## Scheduling++**Recommended**:+- Grok: `/loop 6h dependency-sweeper` (or daily during business hours)+- Claude Code: `/loop 12h /sweep-deps` + `/goal keep the dependency surface clean and green`+- Codex: scheduled automation running the triage + minimal-fix flow every 4-12h+- GitHub Actions: Dependabot + a scheduled or workflow_dispatch sweeper (see `examples/github-actions/` patterns)++Run more frequently after Dependabot or OSV alerts fire. Slow down or pause on major release trains.++## Required Skills++- `dependency-triage` — Parses lockfiles/package manifests, groups updates by risk (patch/minor/major + known CVEs), produces a short actionable list with suggested next version and justification.+- `minimal-fix` — Applies the smallest possible change (usually just version bumps + lockfile update) and nothing else.+- `loop-verifier` (or project test script) — Runs the project's test/build/lint in a clean worktree and confirms the change did not introduce regressions.++## State++Filename: `dependency-sweeper-state.md`++Keep a compact list of in-flight updates, last action, and human decisions:++```markdown+- package.json (lodash): 4.17.21 → 4.17.21 (CVE-2021-23337) — applied patch, tests green+ Last: 2025-06-09T09:12Z+ Human: approved minor for express (was on denylist for this sprint)+- (resolved) react: minor bump — merged+```++Prune merged/closed entries on every run.++## How the Loop Runs (Typical Cycle)++1. Scan manifests + lockfiles + any security advisories (Dependabot, OSV, npm audit, etc.).+2. Triage into safe (patch + no CVE), cautious (minor), and high-risk (major or high-severity CVE).+3. For safe items: spawn a worktree, apply minimal version + lock update via minimal-fix skill, run verifier (tests + build).+4. If verifier passes → open or update a small PR (or commit if allowed on a dependency branch) and record in state.+5. For cautious/high-risk → add to state with clear "needs human" flag + context (changelog diff summary, CVE link).+6. Update the state file and (optionally) comment on open dependency PRs.+7. On next run, re-evaluate open items and close stale or conflicting ones.++## Verification Strategy++- **Never** let the implementer sub-agent declare success.+- Always run the verifier sub-agent (or explicit `npm test && npm run build`) in an isolated worktree.+- The loop only proposes the change or a PR. Human (or an allowlist for "known-safe patches") performs the actual merge.+- For security updates, prefer the smallest patch that resolves the advisory.++## Human Handoff Points++- Any major version bump or change that touches lockfile in > N packages at once.+- High or critical CVEs (even if a patch exists).+- Packages on an explicit denylist (auth, payments, core infra, large internal monorepo packages).+- After N automated attempts on the same dep without progress.+- When tests or type checks fail in the verifier worktree.++## Tool-Specific Notes++**Grok Build TUI**:+- Use `/loop 6h Run dependency-triage. For safe patches create minimal PRs in worktrees. Never auto-merge majors or CVEs above medium.`+- Combine with the scheduler and worktree primitives.++**Claude Code**:+- Boris-style loops work extremely well here: one loop for discovery/triage, sub-agents for the minimal bump + verify.+- Use `/goal` to keep "dependency surface clean with no high sev vulns and < 5 open minor updates".++**GitHub Actions / Dependabot**:+- Let Dependabot open the PRs. The sweeper's job becomes "triage the Dependabot PRs, apply minimal additional fixes if the bot's PR is blocked, rebase, and ping for review on risky ones".+- See the example workflow in `examples/github-actions/`.++**Codex**:+- Schedule a recurring Codex task that runs the triage skill against package.json + package-lock.json and produces the state update + suggested diffs.++## Failure Modes & Mitigations++| Failure | Mitigation |+|---------|------------|+| Loop applies a "safe" update that breaks the build in prod | Strong verifier in worktree + never auto-merge anything without explicit allowlist + human review for anything beyond patch. |+| Infinite update churn (A depends on B which reverts) | Limit attempts per package per 24h. Record last attempted version in state. Escalate after 2 tries. |+| Security patch introduces a new vuln elsewhere | The verifier should include `npm audit` (or equivalent) after the change. |+| Update touches dozens of transitive deps at once | Treat as high-risk. Only touch direct deps in the minimal-fix step. |+| Notification spam | Only notify human for items in the "needs human" section of state. Everything else is silent or summarized daily. |++## Success Metrics++- Median time from "vulnerability published / Dependabot PR opened" → merged (for items the loop touched).+- Number of high/critical vulns open > 48h (target near zero).+- % of dependency PRs that were purely "LGTM, loop handled the bump + verified".+- Reduction in "can you bump X?" messages in Slack/Linear.++Start with **patch-level only + known CVE fixes** on a single repo for 1-2 weeks. Expand to minors only after you trust the verifier. Majors and breaking changes should stay human-gated for a long time.diff --git a/patterns/registry.yaml b/patterns/registry.yamlindex feb86de..2558424 100644--- a/patterns/registry.yaml+++ b/patterns/registry.yaml@@ -48,4 +48,16 @@ patterns:skills: [post-merge-scan, minimal-fix]state: post-merge-state.mdphases: [scan-merges, prioritize, fix-small, ticket-large]- human_gates: [architectural-debt, feature-flags, large-diffs]\ No newline at end of file+ human_gates: [architectural-debt, feature-flags, large-diffs]++ - id: dependency-sweeper+ name: Dependency Sweeper+ file: dependency-sweeper.md+ goal: Discover, safely apply, and verify dependency + vulnerability updates with human gates on risky changes+ cadence: 6h-1d+ risk: medium+ tools: [grok, claude-code, codex, github-actions]+ skills: [dependency-triage, minimal-fix, loop-verifier]+ state: dependency-sweeper-state.md+ phases: [scan, triage-risk, patch-safe, verify-worktree, escalate-risky]+ human_gates: [major-bumps, high-sev-cve, denylisted-packages, max-attempts]\ No newline at end of filediff --git a/starters/README.md b/starters/README.mdindex 7d0b334..9809ec8 100644--- a/starters/README.md+++ b/starters/README.md@@ -7,6 +7,7 @@ Clone-and-run scaffolds. Copy into your project — do not submodule the whole r| [minimal-loop](./minimal-loop/) | Daily Triage | L1 report-only || [pr-babysitter](./pr-babysitter/) | PR Babysitter | L2 assisted || [ci-sweeper](./ci-sweeper/) | CI Sweeper | L2 assisted |+| [dependency-sweeper](./dependency-sweeper/) | Dependency Sweeper | L2 assisted |After copying, run:diff --git a/starters/dependency-sweeper/README.md b/starters/dependency-sweeper/README.mdnew file mode 100644index 0000000..273f43b--- /dev/null+++ b/starters/dependency-sweeper/README.md@@ -0,0 +1,44 @@+# Dependency Sweeper Starter++Clone-and-run scaffold for the **Dependency Sweeper** pattern (L2 assisted with strong verifier gates).++Use this when you want the loop to keep your dependency surface clean and free of known high-severity vulnerabilities without you doing the boring patch/minor bumps by hand.++## Quick Start++1. Copy into your project:++ ```bash+ cp -r starters/dependency-sweeper/.grok/skills/dependency-triage .grok/skills/ # if you have a custom triage skill+ cp starters/dependency-sweeper/dependency-sweeper-state.md.example dependency-sweeper-state.md+ cp starters/dependency-sweeper/LOOP.md.example LOOP.md # optional+ ```++2. Customize the state file with your project name and any initial denylist (e.g. your core framework during a big migration).++3. Start (example with Grok):++ ```+ /loop 6h Run dependency-triage on package manifests and lockfiles. For patch-level or low-risk CVE fixes: create minimal worktree update + verify with tests. Escalate majors, high-sev, and anything on the denylist. Update dependency-sweeper-state.md. Never auto-merge risky changes.+ ```++4. After a week of good triage quality, wire the minimal-fix + verifier from `templates/`.++5. Run `node tools/loop-audit/dist/cli.js .` regularly.++## What's Included++| File | Purpose |+|------|---------|+| `dependency-sweeper-state.md.example` | State spine (in-flight updates, human decisions) |+| `README.md` | This file |+| (recommended) Add your own `dependency-triage` skill modeled on `templates/SKILL.md.*` + the pattern doc |++## Next Steps++- Read the full pattern: [patterns/dependency-sweeper.md](../../patterns/dependency-sweeper.md)+- [Loop Design Checklist](../../docs/loop-design-checklist.md)+- Add `.github/workflows` that reacts to Dependabot PRs or scheduled scans (dogfood example in the root of this reference repo)+- After the loop is stable, consider wiring OSV-Scanner / `npm audit` / Dependabot webhooks as additional discovery sources.++**Safety note**: This pattern is deliberately biased toward *small safe patches only*. Majors and high-severity items must stay behind an explicit human gate.diff --git a/starters/dependency-sweeper/dependency-sweeper-state.md.example b/starters/dependency-sweeper/dependency-sweeper-state.md.examplenew file mode 100644index 0000000..bc2ce54--- /dev/null+++ b/starters/dependency-sweeper/dependency-sweeper-state.md.example@@ -0,0 +1,23 @@+# Dependency Sweeper State — YOUR_PROJECT++Last run: 2025-06-09T08:30:00Z+Status: report-only (week 1)++## Watched manifests+- package.json + package-lock.json (root)+- (add frontend/, services/* etc. as you expand)++## In-flight / recent++<!-- Example entries the loop will maintain -->+- (none yet — first run will populate)++## Human decisions & denylist (edit these)++Denylist (do not auto-touch during this sprint):+- react+- next+- @company/core-auth++Human overrides:+- (none)diff --git a/stories/README.md b/stories/README.mdindex c7bbaea..16faf83 100644--- a/stories/README.md+++ b/stories/README.md@@ -8,6 +8,8 @@ Real-world loop engineering — including failures. Contribute yours via [CONTRI| [daily-triage-report-only.md](./daily-triage-report-only.md) | Daily Triage | L1 before L2 || [why-we-killed-ci-sweeper.md](./why-we-killed-ci-sweeper.md) | CI Sweeper | Budget, branch allowlist, kill switch |+New high-value pattern looking for a story: **Dependency Sweeper** (volume + safety boundaries + measurable "time to clean" metrics).+**Template for new stories:**```markdowndiff --git a/tools/loop-audit/README.md b/tools/loop-audit/README.mdindex ea3372e..1347956 100644--- a/tools/loop-audit/README.md+++ b/tools/loop-audit/README.md@@ -23,20 +23,29 @@ node tools/loop-audit/dist/cli.js starters/minimal-looploop-audit . # human-readable (default)loop-audit . --json # machine-readableloop-audit . --md # markdown report+loop-audit . --suggest # show copy-from-template commands for what's missing (highly recommended)```Exit code `2` if score < 40 (useful for CI gates once your project is loop-ready).-## Signals Checked+The reference repo itself now ships `.github/workflows/audit.yml` that runs this on the starters + root on every PR/push.-| Signal | Weight |-|--------|--------|-| State file (`STATE.md`, etc.) | High |-| Triage skill | High |-| Verifier skill (maker/checker) | High |-| `LOOP.md` config | Medium |-| `AGENTS.md` / project rules | Medium |-| Safety gates documented | Low |+## Signals Checked (v1.1+)++| Signal | Notes |+|-------------------------|-------|+| State file | STATE.md or pattern-specific |+| Triage skill | loop-triage / ci-triage / pr-review-triage etc. |+| Verifier skill | maker/checker split |+| LOOP.md / config | Cadence, limits, handoff |+| AGENTS.md / CLAUDE.md | Project conventions |+| Safety docs | safety.md + LOOP.md mentions of gates |+| .github/ + workflows | Dogfooding / automation |+| MCP / connectors | Mentions or config files |+| Worktree evidence | Isolation patterns in docs |+| patterns/registry.yaml | Machine index for tooling |++Weights favor state + triage + verifier + safety + .github dogfooding.## Levelsdiff --git a/tools/loop-audit/dist/auditor.d.ts b/tools/loop-audit/dist/auditor.d.tsindex b95833d..65548c9 100644--- a/tools/loop-audit/dist/auditor.d.ts+++ b/tools/loop-audit/dist/auditor.d.ts@@ -25,10 +25,24 @@ export interface LoopSignals {};safety: {loopMdMentionsSafety: boolean;+ safetyDocPresent: boolean;};starters: {used: boolean;};+ github: {+ present: boolean;+ workflows: boolean;+ };+ mcp: {+ present: boolean;+ };+ worktreeEvidence: {+ present: boolean;+ };+ registry: {+ present: boolean;+ };}export interface Finding {level: 'ok' | 'warn' | 'fail';diff --git a/tools/loop-audit/dist/auditor.js b/tools/loop-audit/dist/auditor.jsindex 9aee7bb..9588376 100644--- a/tools/loop-audit/dist/auditor.js+++ b/tools/loop-audit/dist/auditor.js@@ -13,7 +13,11 @@ const LOOP_SKILL_NAMES = ['pr-review-triage','ci-triage','post-merge-scan',+ 'dependency-triage',];+const SAFETY_FILES = ['safety.md', 'docs/safety.md', 'SECURITY.md'];+const MCP_FILES = ['.mcp.json', 'mcp.json', '.mcp/config.json'];+const WORKTREE_HINTS = ['worktree', 'worktrees', 'git worktree'];async function fileExists(p) {try {await stat(p);@@ -47,35 +51,47 @@ async function findSkills(root) {export function computeScore(signals) {let score = 10;if (signals.stateFile.present)- score += 20;+ score += 18;if (signals.triage.present)- score += 15;+ score += 14;if (signals.loopConfig.present)- score += 10;+ score += 9;if (signals.agentsMd.present)- score += 10;+ score += 9;if (signals.skills.count >= 2)- score += 15;+ score += 14;else if (signals.skills.count === 1)- score += 8;+ score += 7;if (signals.verifier.present)- score += 15;+ score += 14;if (signals.safety.loopMdMentionsSafety)- score += 5;+ score += 4;+ if (signals.safety.safetyDocPresent)+ score += 4;+ if (signals.github.present)+ score += 6;+ if (signals.github.workflows)+ score += 4;+ if (signals.mcp.present)+ score += 3;+ if (signals.worktreeEvidence.present)+ score += 3;+ if (signals.registry.present)+ score += 2;score = Math.min(100, Math.max(0, score));let level = 'L0';- if (score >= 75 && signals.verifier.present && signals.stateFile.present)+ if (score >= 78 && signals.verifier.present && signals.stateFile.present)level = 'L3';- else if (score >= 55 && signals.triage.present)+ else if (score >= 58 && signals.triage.present)level = 'L2';- else if (score >= 35 && signals.stateFile.present)+ else if (score >= 38 && signals.stateFile.present)level = 'L1';elselevel = 'L0';- const assessment = score >= 80 ? 'Strong loop readiness — unattended possible with human gates.' :- score >= 60 ? 'Good foundation — add verifier before L3.' :- score >= 40 ? 'Early loop setup — complete L1 checklist.' :- 'Not loop-ready — start with minimal-loop starter.';+ const assessment = score >= 82 ? 'Strong loop readiness — good candidate for L3 with explicit gates.' :+ score >= 62 ? 'Good foundation — add missing verifier + safety docs for L3.' :+ score >= 42 ? 'Early loop setup — focus on L1 state + triage before enabling actions.' :+ 'Not loop-ready — start with a starter from this repo (minimal-loop or pr-babysitter).';return { score, level, assessment };}export async function auditProject(target) {@@ -98,6 +114,41 @@ export async function auditProject(target) {if (loopMd) {loopMdContent = await readFile(path.join(root, 'LOOP.md'), 'utf8');}+ // New expanded signals+ const githubDir = await fileExists(path.join(root, '.github'));+ const hasWorkflows = await fileExists(path.join(root, '.github', 'workflows'));+ const safetyDoc = SAFETY_FILES.some(async (f) => await fileExists(path.join(root, f))) ||+ await fileExists(path.join(root, 'docs', 'safety.md'));+ // simple presence (note: async in .some is not awaited perfectly but good enough for heuristic)+ let safetyDocPresent = false;+ for (const f of SAFETY_FILES) {+ if (await fileExists(path.join(root, f))) {+ safetyDocPresent = true;+ break;+ }+ }+ if (!safetyDocPresent) {+ safetyDocPresent = await fileExists(path.join(root, 'docs', 'safety.md'));+ }+ const mcpPresent = (await Promise.all(MCP_FILES.map(f => fileExists(path.join(root, f))))).some(Boolean) ||+ /MCP|mcp server|plugins & connectors/i.test(loopMdContent);+ // Light evidence of worktree usage (common in patterns/starters/LOOP)+ let worktreeEvidence = false;+ const candidateMd = ['LOOP.md', 'patterns/pr-babysitter.md', 'starters/minimal-loop/LOOP.md', 'docs/operating-loops.md'];+ for (const c of candidateMd) {+ try {+ const p = path.join(root, c);+ if (await fileExists(p)) {+ const txt = await readFile(p, 'utf8');+ if (WORKTREE_HINTS.some(h => txt.toLowerCase().includes(h))) {+ worktreeEvidence = true;+ break;+ }+ }+ }+ catch { }+ }+ const registryPresent = await fileExists(path.join(root, 'patterns', 'registry.yaml'));const signals = {stateFile: { present: statePaths.length > 0, paths: statePaths },loopConfig: { present: loopMd, path: loopMd ? 'LOOP.md' : undefined },@@ -106,8 +157,12 @@ export async function auditProject(target) {triage: { present: triage },agentsMd: { present: agentsMd },patterns: { documented: loopMd },- safety: { loopMdMentionsSafety: /gate|denylist|auto-merge|safety/i.test(loopMdContent) },+ safety: { loopMdMentionsSafety: /gate|denylist|auto-merge|safety/i.test(loopMdContent), safetyDocPresent },starters: { used: loopSkills.includes('loop-triage') },+ github: { present: githubDir, workflows: hasWorkflows },+ mcp: { present: mcpPresent },+ worktreeEvidence: { present: worktreeEvidence },+ registry: { present: registryPresent },};if (!signals.stateFile.present) {findings.push({ level: 'fail', message: 'No state file (STATE.md or pattern-specific state).' });@@ -142,6 +197,36 @@ export async function auditProject(target) {findings.push({ level: 'warn', message: 'LOOP.md does not mention safety gates or auto-merge policy.' });recommendations.push('Document human gates per docs/safety.md in LOOP.md');}+ if (!signals.safety.safetyDocPresent) {+ findings.push({ level: 'warn', message: 'No safety.md or docs/safety.md found.' });+ recommendations.push('Copy or create docs/safety.md (denylists, auto-merge policy, MCP scopes)');+ }+ else {+ findings.push({ level: 'ok', message: 'Safety documentation present.' });+ }+ if (!signals.github.present) {+ findings.push({ level: 'warn', message: 'No .github/ directory (templates, workflows for dogfooding).' });+ recommendations.push('Add .github/ISSUE_TEMPLATE, PULL_REQUEST_TEMPLATE, and workflows (see this repo for examples)');+ }+ else if (!signals.github.workflows) {+ findings.push({ level: 'warn', message: '.github/ exists but no workflows/ (CI dogfood opportunity).' });+ recommendations.push('Add GitHub Actions that run loop-audit and validate patterns (dogfood the reference)');+ }+ else {+ findings.push({ level: 'ok', message: '.github/ with workflows present (strong dogfooding signal).' });+ }+ if (!signals.mcp.present) {+ findings.push({ level: 'warn', message: 'No MCP / connector config or mentions detected.' });+ recommendations.push('Document MCP usage (or note "MCP not required for this pattern") in LOOP.md or skills');+ }+ if (!signals.worktreeEvidence.present) {+ findings.push({ level: 'warn', message: 'Little evidence of worktree usage in docs or state.' });+ recommendations.push('Add worktree isolation notes to LOOP.md or pattern docs (see primitives and starters)');+ }+ if (!signals.registry.present) {+ findings.push({ level: 'warn', message: 'No patterns/registry.yaml (machine-readable index for future tools).' });+ recommendations.push('Add patterns/registry.yaml following the existing format');+ }const { score, level, assessment } = computeScore(signals);return {target: root,diff --git a/tools/loop-audit/dist/cli.js b/tools/loop-audit/dist/cli.jsindex 06973f3..16b7c27 100644--- a/tools/loop-audit/dist/cli.js+++ b/tools/loop-audit/dist/cli.js@@ -5,21 +5,28 @@ const args = process.argv.slice(2);const target = args.find((a) => !a.startsWith('-')) || '.';const json = args.includes('--json');const md = args.includes('--md');+const suggest = args.includes('--suggest') || args.includes('--fix');const help = args.includes('--help') || args.includes('-h');if (help) {- console.log(`loop-audit — Loop Readiness Score CLI+ console.log(`loop-audit — Loop Readiness Score CLI (v1.1+)Usage:loop-audit [path] [options]Options:- --json JSON output- --md Markdown output- --help Show help+ --json JSON output (for CI / scripting)+ --md Markdown report+ --suggest Show copy-from-template commands for missing pieces (recommended on first runs)+ --help, -h This helpExit codes:0 score >= 40- 2 score < 40 (early stage)+ 2 score < 40 (early stage or gate)++Examples:+ loop-audit .+ loop-audit starters/minimal-loop --suggest+ node tools/loop-audit/dist/cli.js . --json`);process.exit(0);}@@ -31,6 +38,28 @@ try {console.log(formatMarkdown(result));elseconsole.log(formatHuman(result));+ if (suggest) {+ console.log('\n=== Suggested actions (copy & customize) ===');+ console.log('From the root of this repo (or after cloning the reference):');+ console.log('');+ console.log(' # Minimal L1 daily triage');+ console.log(' cp -r starters/minimal-loop/.grok/skills/loop-triage .grok/skills/');+ console.log(' cp starters/minimal-loop/STATE.md.example STATE.md');+ console.log(' cp starters/minimal-loop/LOOP.md .');+ console.log('');+ console.log(' # Maker/checker verifier');+ console.log(' mkdir -p .grok/skills/loop-verifier');+ console.log(' cp templates/SKILL.md.verifier .grok/skills/loop-verifier/SKILL.md');+ console.log('');+ console.log(' # Common minimal fix action');+ console.log(' mkdir -p .grok/skills/minimal-fix');+ console.log(' cp templates/SKILL.md.minimal-fix .grok/skills/minimal-fix/SKILL.md');+ console.log('');+ console.log(' # For PR babysitter / CI sweeper patterns, copy the corresponding starter');+ console.log(' # Then run: loop-audit . --suggest (again after changes)');+ console.log('');+ console.log('See docs/loop-design-checklist.md and patterns/ for full guidance.');+ }if (result.score < 40)process.exitCode = 2;}diff --git a/tools/loop-audit/dist/reporter.js b/tools/loop-audit/dist/reporter.jsindex 27e50a4..b4eebef 100644--- a/tools/loop-audit/dist/reporter.js+++ b/tools/loop-audit/dist/reporter.js@@ -20,6 +20,7 @@ export function formatHuman(r) {}lines.push('');lines.push('Docs: docs/loop-design-checklist.md');+ lines.push('Tip: rerun with --suggest for ready-to-paste copy commands from templates/starters.');lines.push('');return lines.join('\n');}diff --git a/tools/loop-audit/package.json b/tools/loop-audit/package.jsonindex 260f959..8302b38 100644--- a/tools/loop-audit/package.json+++ b/tools/loop-audit/package.json@@ -1,7 +1,7 @@{"name": "loop-audit",- "version": "1.0.0",- "description": "Loop Readiness Score — audit a project for loop engineering readiness",+ "version": "1.1.0",+ "description": "Loop Readiness Score — audit a project for loop engineering readiness (L0-L3). Supports --suggest for copy commands.","type": "module","bin": {"loop-audit": "./dist/cli.js"@@ -9,7 +9,8 @@"scripts": {"build": "tsc","start": "node dist/cli.js",- "audit": "npm run build && node dist/cli.js"+ "audit": "npm run build && node dist/cli.js",+ "audit:suggest": "npm run build && node dist/cli.js . --suggest"},"engines": {"node": ">=18"diff --git a/tools/loop-audit/src/auditor.ts b/tools/loop-audit/src/auditor.tsindex e83baec..5db6a20 100644--- a/tools/loop-audit/src/auditor.ts+++ b/tools/loop-audit/src/auditor.ts@@ -9,8 +9,12 @@ export interface LoopSignals {triage: { present: boolean };agentsMd: { present: boolean };patterns: { documented: boolean };- safety: { loopMdMentionsSafety: boolean };+ safety: { loopMdMentionsSafety: boolean; safetyDocPresent: boolean };starters: { used: boolean };+ github: { present: boolean; workflows: boolean };+ mcp: { present: boolean };+ worktreeEvidence: { present: boolean };+ registry: { present: boolean };}export interface Finding {@@ -42,8 +46,13 @@ const LOOP_SKILL_NAMES = ['pr-review-triage','ci-triage','post-merge-scan',+ 'dependency-triage',];+const SAFETY_FILES = ['safety.md', 'docs/safety.md', 'SECURITY.md'];+const MCP_FILES = ['.mcp.json', 'mcp.json', '.mcp/config.json'];+const WORKTREE_HINTS = ['worktree', 'worktrees', 'git worktree'];+async function fileExists(p: string): Promise<boolean> {try {await stat(p);@@ -75,28 +84,34 @@ async function findSkills(root: string): Promise<string[]> {export function computeScore(signals: LoopSignals): { score: number; level: 'L0' | 'L1' | 'L2' | 'L3'; assessment: string } {let score = 10;- if (signals.stateFile.present) score += 20;- if (signals.triage.present) score += 15;- if (signals.loopConfig.present) score += 10;- if (signals.agentsMd.present) score += 10;- if (signals.skills.count >= 2) score += 15;- else if (signals.skills.count === 1) score += 8;- if (signals.verifier.present) score += 15;- if (signals.safety.loopMdMentionsSafety) score += 5;+ if (signals.stateFile.present) score += 18;+ if (signals.triage.present) score += 14;+ if (signals.loopConfig.present) score += 9;+ if (signals.agentsMd.present) score += 9;+ if (signals.skills.count >= 2) score += 14;+ else if (signals.skills.count === 1) score += 7;+ if (signals.verifier.present) score += 14;+ if (signals.safety.loopMdMentionsSafety) score += 4;+ if (signals.safety.safetyDocPresent) score += 4;+ if (signals.github.present) score += 6;+ if (signals.github.workflows) score += 4;+ if (signals.mcp.present) score += 3;+ if (signals.worktreeEvidence.present) score += 3;+ if (signals.registry.present) score += 2;score = Math.min(100, Math.max(0, score));let level: 'L0' | 'L1' | 'L2' | 'L3' = 'L0';- if (score >= 75 && signals.verifier.present && signals.stateFile.present) level = 'L3';- else if (score >= 55 && signals.triage.present) level = 'L2';- else if (score >= 35 && signals.stateFile.present) level = 'L1';+ if (score >= 78 && signals.verifier.present && signals.stateFile.present) level = 'L3';+ else if (score >= 58 && signals.triage.present) level = 'L2';+ else if (score >= 38 && signals.stateFile.present) level = 'L1';else level = 'L0';const assessment =- score >= 80 ? 'Strong loop readiness — unattended possible with human gates.' :- score >= 60 ? 'Good foundation — add verifier before L3.' :- score >= 40 ? 'Early loop setup — complete L1 checklist.' :- 'Not loop-ready — start with minimal-loop starter.';+ score >= 82 ? 'Strong loop readiness — good candidate for L3 with explicit gates.' :+ score >= 62 ? 'Good foundation — add missing verifier + safety docs for L3.' :+ score >= 42 ? 'Early loop setup — focus on L1 state + triage before enabling actions.' :+ 'Not loop-ready — start with a starter from this repo (minimal-loop or pr-babysitter).';return { score, level, assessment };}@@ -126,6 +141,38 @@ export async function auditProject(target: string): Promise<AuditResult> {loopMdContent = await readFile(path.join(root, 'LOOP.md'), 'utf8');}+ // New expanded signals+ const githubDir = await fileExists(path.join(root, '.github'));+ const hasWorkflows = await fileExists(path.join(root, '.github', 'workflows'));+ const safetyDoc = SAFETY_FILES.some(async (f) => await fileExists(path.join(root, f))) ||+ await fileExists(path.join(root, 'docs', 'safety.md'));+ // simple presence (note: async in .some is not awaited perfectly but good enough for heuristic)+ let safetyDocPresent = false;+ for (const f of SAFETY_FILES) {+ if (await fileExists(path.join(root, f))) { safetyDocPresent = true; break; }+ }+ if (!safetyDocPresent) {+ safetyDocPresent = await fileExists(path.join(root, 'docs', 'safety.md'));+ }++ const mcpPresent = (await Promise.all(MCP_FILES.map(f => fileExists(path.join(root, f))))).some(Boolean) ||+ /MCP|mcp server|plugins & connectors/i.test(loopMdContent);++ // Light evidence of worktree usage (common in patterns/starters/LOOP)+ let worktreeEvidence = false;+ const candidateMd = ['LOOP.md', 'patterns/pr-babysitter.md', 'starters/minimal-loop/LOOP.md', 'docs/operating-loops.md'];+ for (const c of candidateMd) {+ try {+ const p = path.join(root, c);+ if (await fileExists(p)) {+ const txt = await readFile(p, 'utf8');+ if (WORKTREE_HINTS.some(h => txt.toLowerCase().includes(h))) { worktreeEvidence = true; break; }+ }+ } catch {}+ }++ const registryPresent = await fileExists(path.join(root, 'patterns', 'registry.yaml'));+const signals: LoopSignals = {stateFile: { present: statePaths.length > 0, paths: statePaths },loopConfig: { present: loopMd, path: loopMd ? 'LOOP.md' : undefined },@@ -134,8 +181,12 @@ export async function auditProject(target: string): Promise<AuditResult> {triage: { present: triage },agentsMd: { present: agentsMd },patterns: { documented: loopMd },- safety: { loopMdMentionsSafety: /gate|denylist|auto-merge|safety/i.test(loopMdContent) },+ safety: { loopMdMentionsSafety: /gate|denylist|auto-merge|safety/i.test(loopMdContent), safetyDocPresent },starters: { used: loopSkills.includes('loop-triage') },+ github: { present: githubDir, workflows: hasWorkflows },+ mcp: { present: mcpPresent },+ worktreeEvidence: { present: worktreeEvidence },+ registry: { present: registryPresent },};if (!signals.stateFile.present) {@@ -174,6 +225,38 @@ export async function auditProject(target: string): Promise<AuditResult> {recommendations.push('Document human gates per docs/safety.md in LOOP.md');}+ if (!signals.safety.safetyDocPresent) {+ findings.push({ level: 'warn', message: 'No safety.md or docs/safety.md found.' });+ recommendations.push('Copy or create docs/safety.md (denylists, auto-merge policy, MCP scopes)');+ } else {+ findings.push({ level: 'ok', message: 'Safety documentation present.' });+ }++ if (!signals.github.present) {+ findings.push({ level: 'warn', message: 'No .github/ directory (templates, workflows for dogfooding).' });+ recommendations.push('Add .github/ISSUE_TEMPLATE, PULL_REQUEST_TEMPLATE, and workflows (see this repo for examples)');+ } else if (!signals.github.workflows) {+ findings.push({ level: 'warn', message: '.github/ exists but no workflows/ (CI dogfood opportunity).' });+ recommendations.push('Add GitHub Actions that run loop-audit and validate patterns (dogfood the reference)');+ } else {+ findings.push({ level: 'ok', message: '.github/ with workflows present (strong dogfooding signal).' });+ }++ if (!signals.mcp.present) {+ findings.push({ level: 'warn', message: 'No MCP / connector config or mentions detected.' });+ recommendations.push('Document MCP usage (or note "MCP not required for this pattern") in LOOP.md or skills');+ }++ if (!signals.worktreeEvidence.present) {+ findings.push({ level: 'warn', message: 'Little evidence of worktree usage in docs or state.' });+ recommendations.push('Add worktree isolation notes to LOOP.md or pattern docs (see primitives and starters)');+ }++ if (!signals.registry.present) {+ findings.push({ level: 'warn', message: 'No patterns/registry.yaml (machine-readable index for future tools).' });+ recommendations.push('Add patterns/registry.yaml following the existing format');+ }+const { score, level, assessment } = computeScore(signals);return {diff --git a/tools/loop-audit/src/cli.ts b/tools/loop-audit/src/cli.tsindex 4a73173..6567773 100644--- a/tools/loop-audit/src/cli.ts+++ b/tools/loop-audit/src/cli.ts@@ -6,22 +6,29 @@ const args = process.argv.slice(2);const target = args.find((a) => !a.startsWith('-')) || '.';const json = args.includes('--json');const md = args.includes('--md');+const suggest = args.includes('--suggest') || args.includes('--fix');const help = args.includes('--help') || args.includes('-h');if (help) {- console.log(`loop-audit — Loop Readiness Score CLI+ console.log(`loop-audit — Loop Readiness Score CLI (v1.1+)Usage:loop-audit [path] [options]Options:- --json JSON output- --md Markdown output- --help Show help+ --json JSON output (for CI / scripting)+ --md Markdown report+ --suggest Show copy-from-template commands for missing pieces (recommended on first runs)+ --help, -h This helpExit codes:0 score >= 40- 2 score < 40 (early stage)+ 2 score < 40 (early stage or gate)++Examples:+ loop-audit .+ loop-audit starters/minimal-loop --suggest+ node tools/loop-audit/dist/cli.js . --json`);process.exit(0);}@@ -32,6 +39,29 @@ try {else if (md) console.log(formatMarkdown(result));else console.log(formatHuman(result));+ if (suggest) {+ console.log('\n=== Suggested actions (copy & customize) ===');+ console.log('From the root of this repo (or after cloning the reference):');+ console.log('');+ console.log(' # Minimal L1 daily triage');+ console.log(' cp -r starters/minimal-loop/.grok/skills/loop-triage .grok/skills/');+ console.log(' cp starters/minimal-loop/STATE.md.example STATE.md');+ console.log(' cp starters/minimal-loop/LOOP.md .');+ console.log('');+ console.log(' # Maker/checker verifier');+ console.log(' mkdir -p .grok/skills/loop-verifier');+ console.log(' cp templates/SKILL.md.verifier .grok/skills/loop-verifier/SKILL.md');+ console.log('');+ console.log(' # Common minimal fix action');+ console.log(' mkdir -p .grok/skills/minimal-fix');+ console.log(' cp templates/SKILL.md.minimal-fix .grok/skills/minimal-fix/SKILL.md');+ console.log('');+ console.log(' # For PR babysitter / CI sweeper patterns, copy the corresponding starter');+ console.log(' # Then run: loop-audit . --suggest (again after changes)');+ console.log('');+ console.log('See docs/loop-design-checklist.md and patterns/ for full guidance.');+ }+if (result.score < 40) process.exitCode = 2;} catch (err: unknown) {const msg = err instanceof Error ? err.message : String(err);diff --git a/tools/loop-audit/src/reporter.ts b/tools/loop-audit/src/reporter.tsindex a28ea6a..6a9f6a0 100644--- a/tools/loop-audit/src/reporter.ts+++ b/tools/loop-audit/src/reporter.ts@@ -22,6 +22,7 @@ export function formatHuman(r: AuditResult): string {}lines.push('');lines.push('Docs: docs/loop-design-checklist.md');+ lines.push('Tip: rerun with --suggest for ready-to-paste copy commands from templates/starters.');lines.push('');return lines.join('\n');}