feat(tools): add loop-sync CLI for drift detection and configuration …

[hsms4710-pixel]

Summary

Adds loop-sync CLI tool for detecting drift between STATE.md and LOOP.md files, and synchronizing them. Addresses a common pain point where state and loop definitions become out of sync over time.

Changes

• New pattern or starter (followed templates/pattern-template.md + updated registry.yaml)
• Doc / example improvement
• Tool change (loop-sync)
• 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 . (score: 100/100) and addressed findings

Testing / Dogfood

• loop-audit passes on this repo (score: 100/100)
• Manual review of generated output - loop-sync . and test suite pass

Screenshots / Examples (if UI or command output)

Real loop-sync . output against this repo:

Loop Sync Report
=============================================
Score: 80/100 (healthy)

Found 2 issue(s):

[WARNINGS]:
   - LOOP.md: LOOP.md does not reference STATE.md
   - STATE.md <-> LOOP.md: Low structural similarity between STATE.md and LOOP.md

Suggestions:
   - Review STATE.md and LOOP.md for consistency

[cobusgreyling]

Thanks for the contribution. CI passed on our side. Before merge please:

1. Add built dist/ files (see how loop-init / loop-audit do it package.json points at dist/cli.js but no dist is committed)

2. Wire into repo CI / root tooling like the other tools

3. Complete the PR checklist

[hsms4710-pixel]

Audit Check Failure - Permission Issue

The audit check is failing with a 403 error:

POST /repos/cobusgreyling/loop-engineering/issues/47/comments
-> 403 Resource not accessible by integration

Root Cause

This is not a code issue with this PR. It is a GitHub Actions permission limitation for fork PRs:

1. This PR is from a fork (hsms4710-pixel/loop-engineering)
2. GitHub uses read-only tokens for fork PR workflows (security restriction)
3. The audit.yml workflow tries to post a comment to this PR
4. Posting comments requires issues: write permission
5. The read-only token does not have this permission -> 403 error

Note

The validate check passed, and the audit logic itself works correctly (it calculated a score of 100/100). The only issue is posting the result as a comment.

The workflow permissions may need to be adjusted to handle fork PRs correctly.

[hsms4710-pixel]

All 3 requirements are now met:

1. Added dist/ directory (built output committed, matching loop-audit and loop-init convention)
2. Wired into root tooling (test:loop-sync and build:tools scripts added to root package.json)
3. Completed PR checklist (updated PR description following the template, all applicable items checked)

loop-audit passes with score 100/100. Ready for review.

[cobusgreyling]

@hsms4710-pixel — friendly ping on this one. It's been open since June 26 with no updates since the review feedback.

Still needed before we can merge:

1. Commit built dist/ files (see loop-init / loop-audit for the pattern)
2. Wire into root CI (package.json test:tools, scripts/ci-validate-gates.sh)
3. Complete the PR checklist in the description

The loop-sync idea is solid — drift between STATE.md and LOOP.md is a real pain point. If you're still interested, rebase onto latest main and push; happy to review quickly.

Closing as stale for now to keep the queue clean. Reopen anytime when ready — no need to open a new PR.

[cobusgreyling]

@hsms4710-pixel — sorry we missed your June 26 update before closing this as stale. You'd already addressed all three review items (dist/, root tooling, checklist) and noted loop-audit at 100/100 — that's on us.

Please reopen when you have a moment and rebase onto latest main (we merged #85–#87 since then). We'll prioritize review.

If easier, push a fresh branch and we'll merge from there. Thanks for sticking with it — loop-sync is still a gap worth filling.

[cobusgreyling]

@hsms4710-pixel — merged in #88. Sorry again for the premature stale close. Your June 26 update had already addressed the review — we rebased, fixed tests/CI wiring, and landed loop-sync on main. 🎉