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.

docs: sync version references across README, RELEASE, and CHANGELOG (#238)

Cobus Greyling0954794686e6
diff --git a/README.md b/README.md
index ddfa91a..d2d960b 100644
--- a/README.md
+++ b/README.md
@@ -87,8 +87,8 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent
| [Patterns](patterns/README.md) | 7 production patterns + [interactive picker](https://cobusgreyling.github.io/loop-engineering/#interactive) |
| [Starters](starters/) | Clone-and-run kits (Grok, Claude Code, Codex, Opencode) |
| [Opencode examples](examples/opencode/) | CLI-first loops: cron/systemd + `opencode run`, skills, worktrees |
-| [loop-audit](tools/loop-audit/) | Loop Readiness Score CLI (v1.5 + constraints scoring) — `npx @cobusgreyling/loop-audit . --suggest` · `--badge` for README |
-| [loop-init](tools/loop-init/) | Scaffold starters + budget/run-log + constraints (v1.2) — `npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok` |
+| [loop-audit](tools/loop-audit/) | Loop Readiness Score CLI (v1.6 — constraints + governance scoring) — `npx @cobusgreyling/loop-audit . --suggest` · `--badge` for README |
+| [loop-init](tools/loop-init/) | Scaffold starters + budget/run-log + constraints (v1.3) — `npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok` |
| [loop-cost](tools/loop-cost/) | Token spend estimator — `npx @cobusgreyling/loop-cost` |
| [loop-sync](tools/loop-sync/) | Drift detection between `STATE.md` and `LOOP.md` — `npx @cobusgreyling/loop-sync .` |
| [loop-context](tools/loop-context/) | Stateful memory manager + circuit breaker for long runs — `npx @cobusgreyling/loop-context --check --ledger run.json` |
@@ -98,6 +98,7 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent
| [Stories](stories/) | Real wins and honest failures |
| [Contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123) | **Help wanted:** 25 scoped `good first issues` — comment *I'll take this* to get assigned |
| [Community update](https://github.com/cobusgreyling/loop-engineering/discussions/145) | **July 4:** 5.5k stars, traffic sources, contributor merges |
+| [Community week (Jul 8)](https://github.com/cobusgreyling/loop-engineering/discussions/219) | loop-worktree npm, MCP quickstart, tool appendices |
| [Prior release notes](https://github.com/cobusgreyling/loop-engineering/discussions/89) | v1.5.0 — loop-sync, constraints, MCP server |
| [Add your project](https://github.com/cobusgreyling/loop-engineering/discussions/92) | **Pinned:** Loop Ready badge + adopters list |
@@ -204,7 +205,7 @@ bash scripts/before-after-demo.sh
/loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.
```
-All three CLIs publish to npm from tagged releases — see [docs/RELEASE.md](docs/RELEASE.md). No clone required.
+All npm CLIs publish from tagged releases — see [docs/RELEASE.md](docs/RELEASE.md). No clone required.
**Develop from source** (monorepo contributors):
diff --git a/RELEASE_NOTES_DRAFT.md b/RELEASE_NOTES_DRAFT.md
index e001a7f..5342017 100644
--- a/RELEASE_NOTES_DRAFT.md
+++ b/RELEASE_NOTES_DRAFT.md
@@ -1,13 +1,27 @@
# Release notes draft — since `loop-mcp-server-v1.0.0`
-**Status:** Published to [Discussions](https://github.com/cobusgreyling/loop-engineering/discussions) on 2026-07-08. Archive copy for the next changelog-drafter run.
+**Status:** Published to [Discussions #219](https://github.com/cobusgreyling/loop-engineering/discussions/219) on 2026-07-08. Post-publish additions below (loop-audit 1.6.0). Archive copy for the next changelog-drafter run.
-**Window:** 2026-07-06 → 2026-07-08
+**Window:** 2026-07-06 → 2026-07-09
---
## Highlights
+### loop-audit 1.6.0 — governance scoring ([#233](https://github.com/cobusgreyling/loop-engineering/pull/233))
+
+Readiness scoring now checks multi-agent safety signals:
+
+- Least-privilege tool scope (`allowed-tools` in skills, scoped MCP)
+- Stall / no-progress detection (`loop-context`, circuit breaker, max attempts)
+- Human-escalation path (HITL, handoff language in `LOOP.md` / constraints)
+
+Tagged `loop-audit-v1.6.0`.
+
+```bash
+npx @cobusgreyling/loop-audit . --suggest
+```
+
### New on npm: `@cobusgreyling/loop-worktree` ([#190](https://github.com/cobusgreyling/loop-engineering/pull/190), [#204](https://github.com/cobusgreyling/loop-engineering/pull/204))
Isolated git worktrees per fix attempt — supports PR Babysitter and CI Sweeper L2 patterns without branch collisions. Tagged `loop-worktree-v1.0.0`.
@@ -20,6 +34,13 @@ npx @cobusgreyling/loop-worktree cleanup --older-than 24h
Thanks [@KhaiTrang1995](https://github.com/KhaiTrang1995).
+### Stories
+
+| PR | What shipped |
+|----|--------------|
+| [#234](https://github.com/cobusgreyling/loop-engineering/pull/234) | CI Sweeper infinite flaky-test failure story |
+| [#182](https://github.com/cobusgreyling/loop-engineering/pull/182) | Multi-loop coordination story (@k-anushka14) |
+
### Docs & examples
| PR | Contributor | What shipped |
@@ -28,7 +49,6 @@ Thanks [@KhaiTrang1995](https://github.com/KhaiTrang1995).
| [#202](https://github.com/cobusgreyling/loop-engineering/pull/202) | @Mahizhan-S | Gemini CLI appendix in primitives matrix |
| [#206](https://github.com/cobusgreyling/loop-engineering/pull/206) | @Mahizhan-S | Zed appendix in primitives matrix |
| [#208](https://github.com/cobusgreyling/loop-engineering/pull/208) | @Mahizhan-S | Windsurf PR Babysitter example |
-| [#182](https://github.com/cobusgreyling/loop-engineering/pull/182) | @k-anushka14 | Multi-loop coordination story |
| [#183](https://github.com/cobusgreyling/loop-engineering/pull/183) | @k-anushka14 | Opencode constraints example |
| [#185](https://github.com/cobusgreyling/loop-engineering/pull/185) | @k-anushka14 | Aider appendix link in examples index |
| Hermes index + QUICKSTART | @AshayK003 ([#187](https://github.com/cobusgreyling/loop-engineering/pull/187)–[#189](https://github.com/cobusgreyling/loop-engineering/pull/189)) | `examples/hermes/README.md`, QUICKSTART section |
@@ -43,6 +63,7 @@ Thanks [@KhaiTrang1995](https://github.com/KhaiTrang1995).
### Housekeeping
- **Star-history workflow** — opens an auto-merge PR instead of pushing to protected `main`
+- **loop-audit publish** — install `sigstore` before npm publish ([#236](https://github.com/cobusgreyling/loop-engineering/pull/236))
- Dependabot bumps: `actions/github-script` 7→9, `@types/node` in loop-audit/loop-init
- Stale branch prune + contributor PR backlog triage
@@ -52,13 +73,14 @@ Thanks [@KhaiTrang1995](https://github.com/KhaiTrang1995).
| Package | Version | Notes |
|---------|---------|-------|
+| `@cobusgreyling/loop-audit` | **1.6.0** | Governance scoring — `loop-audit-v1.6.0` |
| `@cobusgreyling/loop-worktree` | **1.0.0** | New — `loop-worktree-v1.0.0` |
+| `@cobusgreyling/loop-init` | 1.3.3 | Contributor CTA after scaffold |
| `@cobusgreyling/loop-mcp-server` | 1.0.0 | No change |
-| `@cobusgreyling/loop-audit` | 1.5.3 | No change |
-| `@cobusgreyling/loop-init` | 1.3.3 | No change |
| `@cobusgreyling/loop-cost` | 1.0.3 | No change |
| `@cobusgreyling/loop-sync` | 1.0.0 | No change |
| `@cobusgreyling/loop-context` | 1.0.0 | No change |
+| `@cobusgreyling/goal-audit` | 1.0.2 | Companion — Goal Engineering stack |
---
diff --git a/STATE.md b/STATE.md
index cbe9217..781a76a 100644
--- a/STATE.md
+++ b/STATE.md
@@ -5,7 +5,7 @@ Last run: 2026-07-09T10:41:53Z (automated daily-triage workflow)
## High Priority (loop is acting or waiting on human)
- Maintain loop readiness score ≥ 58 (current: **100**, level **L3**).
-- Keep npm packages current after tool changes (tag `loop-audit-v*`, `loop-init-v*`, `loop-cost-v*` — see docs/RELEASE.md).
+- Keep npm packages current after tool changes (per-package tags — see [docs/RELEASE.md](docs/RELEASE.md)).
## Watch List
diff --git a/docs/RELEASE.md b/docs/RELEASE.md
index 142c9ea..1755d11 100644
--- a/docs/RELEASE.md
+++ b/docs/RELEASE.md
@@ -1,6 +1,6 @@
# Release playbook — npm packages
-This repo ships six public npm packages from `tools/`:
+This repo ships eight public npm packages from `tools/`:
| Package | Directory | Release tag |
|---------|-----------|-------------|
@@ -10,6 +10,8 @@ This repo ships six public npm packages from `tools/`:
| `@cobusgreyling/loop-sync` | `tools/loop-sync` | `loop-sync-v*` |
| `@cobusgreyling/loop-context` | `tools/loop-context` | `loop-context-v*` |
| `@cobusgreyling/loop-mcp-server` | `tools/mcp-server` | `loop-mcp-server-v*` |
+| `@cobusgreyling/loop-worktree` | `tools/loop-worktree` | `loop-worktree-v*` |
+| `@cobusgreyling/goal-audit` | `tools/goal-audit` | `goal-audit-v*` |
## One-time setup (trusted publishing — recommended)
@@ -23,12 +25,14 @@ Link npm to GitHub, then for **each package** on [npmjs.com](https://www.npmjs.c
| `@cobusgreyling/loop-sync` | `cobusgreyling/loop-engineering` | `release-loop-sync.yml` |
| `@cobusgreyling/loop-context` | `cobusgreyling/loop-engineering` | `release-loop-context.yml` |
| `@cobusgreyling/loop-mcp-server` | `cobusgreyling/loop-engineering` | `release-loop-mcp-server.yml` |
+| `@cobusgreyling/loop-worktree` | `cobusgreyling/loop-engineering` | `release-loop-worktree.yml` |
+| `@cobusgreyling/goal-audit` | `cobusgreyling/loop-engineering` | `release-goal-audit.yml` |
Names must match **exactly** (case-sensitive). No `NPM_TOKEN` secret is required when trusted publishing is configured.
**Auth:** release workflows use repo secret `NPM_TOKEN` (Automation token). Refresh it at [npmjs.com](https://www.npmjs.com/) → Access Tokens if publishes fail with `E401`/`E404`.
-**Retry without re-tagging:** Actions → Release workflow → **Run workflow** → enter the tag (e.g. `loop-audit-v1.4.2`).
+**Retry without re-tagging:** Actions → Release workflow → **Run workflow** → enter the tag (e.g. `loop-audit-v1.6.0`).
**Trusted publishing (optional):** configure per package on npm; OIDC alone is not sufficient unless `NPM_TOKEN` is removed and trusted publishers are verified.
@@ -42,16 +46,16 @@ Tag pushes trigger the release workflows:
```bash
# loop-audit (runs tests before publish)
-git tag loop-audit-v1.3.0
-git push origin loop-audit-v1.3.0
+git tag loop-audit-v1.6.0
+git push origin loop-audit-v1.6.0
# loop-init (bundles starters/templates, runs smoke tests)
-git tag loop-init-v1.2.0
-git push origin loop-init-v1.2.0
+git tag loop-init-v1.3.3
+git push origin loop-init-v1.3.3
# loop-cost (bundles patterns/registry.yaml)
-git tag loop-cost-v1.0.0
-git push origin loop-cost-v1.0.0
+git tag loop-cost-v1.0.3
+git push origin loop-cost-v1.0.3
# loop-sync (drift detection between STATE.md and LOOP.md)
git tag loop-sync-v1.0.0
@@ -64,9 +68,17 @@ git push origin loop-context-v1.0.0
# loop-mcp-server (MCP runtime lookup for patterns, skills, state)
git tag loop-mcp-server-v1.0.0
git push origin loop-mcp-server-v1.0.0
+
+# loop-worktree (isolated git worktrees per fix attempt)
+git tag loop-worktree-v1.0.0
+git push origin loop-worktree-v1.0.0
+
+# goal-audit (Goal Engineering readiness scorer — companion repo)
+git tag goal-audit-v1.0.2
+git push origin goal-audit-v1.0.2
```
-Workflows: `.github/workflows/release-loop-audit.yml`, `.github/workflows/release-loop-init.yml`, `.github/workflows/release-loop-cost.yml`, `.github/workflows/release-loop-sync.yml`, `.github/workflows/release-loop-context.yml`, `.github/workflows/release-loop-mcp-server.yml`.
+Workflows: `.github/workflows/release-loop-audit.yml`, `.github/workflows/release-loop-init.yml`, `.github/workflows/release-loop-cost.yml`, `.github/workflows/release-loop-sync.yml`, `.github/workflows/release-loop-context.yml`, `.github/workflows/release-loop-mcp-server.yml`, `.github/workflows/release-loop-worktree.yml`, `.github/workflows/release-goal-audit.yml`.
## Verify after publish
@@ -77,6 +89,8 @@ npx @cobusgreyling/loop-cost --help
npx @cobusgreyling/loop-sync --help
npx @cobusgreyling/loop-context --help
npx @cobusgreyling/loop-mcp-server --help
+npx @cobusgreyling/loop-worktree --help
+npx @cobusgreyling/goal-audit --help
mkdir /tmp/loop-init-test && cd /tmp/loop-init-test
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --dry-run
diff --git a/tools/loop-audit/CHANGELOG.md b/tools/loop-audit/CHANGELOG.md
index eed7709..9131c9f 100644
--- a/tools/loop-audit/CHANGELOG.md
+++ b/tools/loop-audit/CHANGELOG.md
@@ -2,6 +2,18 @@
All notable changes to `@cobusgreyling/loop-audit` are documented here.
+## [1.6.0] - 2026-07-09
+
+### Added
+- Governance scoring signals: least-privilege tool scope, stall / no-progress detection, human-escalation path
+- `allowed-tools` frontmatter in `SKILL.md` detected as a least-privilege signal
+- `--suggest` recommendations when governance signals are missing
+
+## [1.5.3] - 2026-07-06
+
+### Added
+- Contributor quickstart CTA after CLI runs (skipped for `--json`, `--md`, and `--badge`)
+
## [1.5.2] - 2026-06-30
### Added
diff --git a/tools/loop-audit/README.md b/tools/loop-audit/README.md
index 7af369f..dbe1dae 100644
--- a/tools/loop-audit/README.md
+++ b/tools/loop-audit/README.md
@@ -52,7 +52,7 @@ npm run build
npm publish --access public
```
-## Signals Checked (v1.4+)
+## Signals Checked (v1.6+)
| Signal | Notes |
|-------------------------|-------|
diff --git a/tools/loop-audit/package-lock.json b/tools/loop-audit/package-lock.json
index 9e08396..5e15284 100644
--- a/tools/loop-audit/package-lock.json
+++ b/tools/loop-audit/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "@cobusgreyling/loop-audit",
- "version": "1.5.3",
+ "version": "1.6.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@cobusgreyling/loop-audit",
- "version": "1.5.3",
+ "version": "1.6.0",
"license": "MIT",
"bin": {
"loop-audit": "dist/cli.js"