chore: import upstream snapshot with attribution

cmd/micro/loop/templates/NORTH_STAR.md

@@ -0,0 +1,23 @@
+# North Star
+
+> **Edit this file.** It is the single source of direction the loop aligns every
+> increment to. The planner ranks work against it; the builder builds toward it.
+> Be concrete — vague direction produces vague increments.
+
+## Mission
+
+<One or two sentences: the problem this repository solves and who it's for.>
+
+## Right now
+
+<The current priority — what "better" means this month. The planner weights the
+queue toward this.>
+
+## Guardrails
+
+- One concern per PR; small and reversible.
+- The gate is green CI, not a human review — keep the test/lint suite strong,
+  because the loop is only as good as its evaluator.
+- **Off-limits without a human** (surface as notes, never auto-merge): breaking
+  public API changes, brand/positioning/marketing copy, new dependencies,
+  architectural rewrites, product-default changes with broad behavioral impact.

cmd/micro/loop/templates/PRIORITIES.md

@@ -0,0 +1,16 @@
+# Priorities
+
+A single ranked queue, highest-value first. Each item links a scoped issue the
+loop can build and CI can verify. The **planner** keeps this current; the
+**builder** takes the top item whose issue is still open.
+
+<!--
+Seed this with a few real items to give the loop a running start, e.g.:
+
+1. Add retry with backoff to the HTTP client — #123
+2. Document the config file format — #124
+3. Fix flaky timeout in the cache tests — #125
+
+The planner will re-rank, drop completed items, and file issues for new gaps.
+Reorder or edit this file at any time to redirect the loop.
+-->

cmd/micro/loop/templates/dispatch.yml.tmpl

@@ -0,0 +1,60 @@
+name: "<< .WorkflowName >>"
+
+# Generated by `micro loop init`. A dispatch role of the autonomous loop: on a
+# cadence it opens a fresh tracking issue and posts the instruction in
+# .github/loop/prompts/<< .Role >>.md to the agent (<< .AgentMention >>).
+#
+# The workflow is the MECHANISM; that prompt file is the editable POLICY —
+# change what this role does by editing the prompt, not this YAML. A FRESH
+# issue per run is deliberate: agents derive the PR branch name from the
+# triggering issue, so reusing one tracker collapses every run onto one branch.
+#
+# Gated on << .TokenSecret >>: the agent ignores @mentions from the
+# github-actions bot, so dispatch posts as a real user (a PAT). No token → no-op.
+
+on:
+  workflow_dispatch: {}
+  schedule:
+    - cron: "<< .Cron >>"
+
+permissions:
+  issues: write
+
+concurrency:
+  group: << .Group >>
+  cancel-in-progress: false
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4 # needed to read the prompt file
+      - name: Dispatch << .Role >>
+        env:
+          GH_TOKEN: ${{ secrets.<< .TokenSecret >> || github.token }}
+          HAS_TOKEN: ${{ secrets.<< .TokenSecret >> != '' }}
+          REPO: ${{ github.repository }}
+          RUN_NUMBER: ${{ github.run_number }}
+        run: |
+          if [ "$HAS_TOKEN" != "true" ]; then
+            echo "<< .TokenSecret >> is not set — skipping (the agent ignores bot @mentions)."
+            exit 0
+          fi
+          PROMPT=".github/loop/prompts/<< .Role >>.md"
+          if [ ! -f "$PROMPT" ]; then
+            echo "missing $PROMPT — run 'micro loop init'." >&2
+            exit 1
+          fi
+          ISSUE_URL=$(gh issue create --repo "$REPO" \
+            --title "<< .IssueTitle >> #$RUN_NUMBER" \
+            --body "Autonomous << .Role >> pass. Direction: .github/loop/NORTH_STAR.md; queue: .github/loop/PRIORITIES.md.")
+          ISSUE_NUM="${ISSUE_URL##*/}"
+          echo "Opened issue #$ISSUE_NUM — dispatching << .Role >>."
+          # The prompt file is the policy; strip its editorial <!-- --> header and
+          # substitute the tracking issue number (__ISSUE__) at runtime.
+          {
+            echo "<< .AgentMention >>"
+            echo
+            sed -e '/<!--/,/-->/d' -e "s/__ISSUE__/$ISSUE_NUM/g" "$PROMPT"
+          } > "$RUNNER_TEMP/loop-body.md"
+          gh issue comment "$ISSUE_NUM" --repo "$REPO" --body-file "$RUNNER_TEMP/loop-body.md"

cmd/micro/loop/templates/loop-release.yml.tmpl

@@ -0,0 +1,97 @@
+name: "Loop: Release"
+
+# Generated by `micro loop init`. Cuts the next tag when the default branch has
+# new commits since the latest one, and pushes it with a PAT (<< .TokenSecret >>)
+# so any tag-triggered release workflow fires. The bump reflects what shipped,
+# read from the CHANGELOG [Unreleased] section: new features (Added/Changed) cut
+# a MINOR; fixes/docs only cut a PATCH; breaking changes are skipped so a MAJOR
+# stays a human decision.
+#
+# The tag MUST be pushed with a PAT, not the default GITHUB_TOKEN: a tag pushed
+# by GITHUB_TOKEN does not trigger other workflows (Actions blocks that recursion).
+
+on:
+  workflow_dispatch: {}
+  schedule:
+    - cron: "<< .ReleaseCron >>"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: loop-release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # need full history + all tags
+          # Do NOT persist the default GITHUB_TOKEN as a git credential: it would
+          # be sent on the PAT push below and override it, so the tag push would
+          # authenticate as github-actions[bot] and 403. Letting the PAT in the
+          # push URL be the only credential is the whole point.
+          persist-credentials: false
+      - name: Cut the next patch tag if there are new commits
+        env:
+          RELEASE_TOKEN: ${{ secrets.<< .TokenSecret >> }}
+          REPO: ${{ github.repository }}
+        run: |
+          if [ -z "$RELEASE_TOKEN" ]; then
+            echo "<< .TokenSecret >> is not set — skipping."
+            exit 0
+          fi
+          git fetch --tags --force
+
+          LATEST=$(git tag --list '<< .TagPrefix >>*.*.*' --sort=-v:refname | head -1)
+          if [ -z "$LATEST" ]; then
+            echo "no << .TagPrefix >>MAJOR.MINOR.PATCH tag found — aborting so nothing weird gets tagged."
+            exit 1
+          fi
+          echo "latest tag: $LATEST"
+
+          COUNT=$(git rev-list --count "$LATEST"..HEAD)
+          echo "commits since $LATEST: $COUNT"
+          if [ "$COUNT" -eq 0 ]; then
+            echo "no new commits since $LATEST — no release."
+            exit 0
+          fi
+
+          ver="${LATEST#<< .TagPrefix >>}"
+          major="${ver%%.*}"
+          rest="${ver#*.}"
+          minor="${rest%%.*}"
+          patch="${rest#*.}"
+          case "$major.$minor.$patch" in
+            [0-9]*.[0-9]*.[0-9]*) ;;
+            *) echo "unexpected tag shape: $LATEST" ; exit 1 ;;
+          esac
+
+          # Choose the bump from what actually shipped, read from the CHANGELOG
+          # [Unreleased] section (kept current by the coherence role):
+          #   new features (### Added / ### Changed) -> MINOR
+          #   fixes/docs only                        -> PATCH
+          #   breaking (### Removed / "(breaking)")  -> skip; a major is a human call
+          UNRELEASED=""
+          if [ -f CHANGELOG.md ]; then
+            UNRELEASED=$(awk '/^## \[Unreleased\]/{f=1; next} /^## \[/{f=0} f' CHANGELOG.md)
+          fi
+          if printf '%s\n' "$UNRELEASED" | grep -qiE '^### Removed|^### Changed \(breaking\)|BREAKING'; then
+            echo "CHANGELOG [Unreleased] contains breaking changes — a major release is a human decision. Skipping."
+            exit 0
+          elif printf '%s\n' "$UNRELEASED" | grep -qE '^### (Added|Changed)'; then
+            NEXT="<< .TagPrefix >>${major}.$((minor + 1)).0"
+            KIND="minor (new features)"
+          else
+            NEXT="<< .TagPrefix >>${major}.${minor}.$((patch + 1))"
+            KIND="patch (fixes/docs only)"
+          fi
+          echo "cutting: $NEXT — $KIND ($COUNT commits since $LATEST)"
+
+          git config user.name "loop release bot"
+          git config user.email "noreply@users.noreply.github.com"
+          git tag -a "$NEXT" -m "Release $NEXT — automated $KIND ($COUNT commits since $LATEST)"
+          git push "https://x-access-token:${RELEASE_TOKEN}@github.com/${REPO}.git" "$NEXT"
+          echo "Pushed $NEXT."

cmd/micro/loop/templates/loop-triage.yml.tmpl

@@ -0,0 +1,57 @@
+name: "Loop: Triage"
+
+# Generated by `micro loop init`. The feedback path of the evaluator: when a CI
+# workflow (<< .CIWorkflow >>) fails on a non-PR run, dispatch the agent
+# (<< .AgentMention >>) with the instruction in .github/loop/prompts/triage.md
+# to root-cause the failure and file scoped fix issues back into the queue — so
+# failures become fixes with no human in the middle. Gated on << .TokenSecret >>.
+
+on:
+  workflow_run:
+    workflows: << .CIWorkflowsYAML >>
+    types: [completed]
+
+permissions:
+  issues: write
+
+concurrency:
+  group: loop-triage
+  cancel-in-progress: false
+
+jobs:
+  triage:
+    # Only real failures on branch pushes/schedules — not PR-run failures, which
+    # the PR author already sees.
+    if: ${{ github.event.workflow_run.conclusion == 'failure' && github.event.workflow_run.event != 'pull_request' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4 # needed to read the prompt file
+      - name: Dispatch triage
+        env:
+          GH_TOKEN: ${{ secrets.<< .TokenSecret >> || github.token }}
+          HAS_TOKEN: ${{ secrets.<< .TokenSecret >> != '' }}
+          REPO: ${{ github.repository }}
+          RUN_ID: ${{ github.event.workflow_run.id }}
+          RUN_URL: ${{ github.event.workflow_run.html_url }}
+          WORKFLOW_NAME: ${{ github.event.workflow_run.name }}
+        run: |
+          if [ "$HAS_TOKEN" != "true" ]; then
+            echo "<< .TokenSecret >> is not set — skipping."
+            exit 0
+          fi
+          PROMPT=".github/loop/prompts/triage.md"
+          if [ ! -f "$PROMPT" ]; then
+            echo "missing $PROMPT — run 'micro loop init'." >&2
+            exit 1
+          fi
+          ISSUE_URL=$(gh issue create --repo "$REPO" \
+            --title "Loop: triage failed run $RUN_ID ($WORKFLOW_NAME)" \
+            --body "The '$WORKFLOW_NAME' workflow failed on a non-PR run: $RUN_URL")
+          ISSUE_NUM="${ISSUE_URL##*/}"
+          echo "Opened issue #$ISSUE_NUM — dispatching triage."
+          {
+            echo "<< .AgentMention >>"
+            echo
+            sed -e '/<!--/,/-->/d' -e "s/__ISSUE__/$ISSUE_NUM/g" -e "s#__RUNURL__#$RUN_URL#g" "$PROMPT"
+          } > "$RUNNER_TEMP/loop-body.md"
+          gh issue comment "$ISSUE_NUM" --repo "$REPO" --body-file "$RUNNER_TEMP/loop-body.md"

cmd/micro/loop/templates/prompts/builder.md.tmpl

@@ -0,0 +1,14 @@
+<!--
+The BUILDER prompt — the editable policy for the builder role. The workflow
+prepends the agent @mention and substitutes __ISSUE__ before posting. Keep
+__ISSUE__ literal.
+-->
+Build one increment for this repository, aligned to `.github/loop/NORTH_STAR.md`.
+
+PICK THE WORK: take the highest-ranked item in `.github/loop/PRIORITIES.md` whose linked issue is still OPEN — that is your task, and its issue is the one you close. If the queue is empty or every item's issue is closed, pick the single highest-value improvement yourself.
+
+Implement it, then VERIFY the project builds, tests, and lints (use the commands documented in the README or the CI workflow).
+
+Open the PR YOURSELF from the shell — do NOT use a make_pr tool (it may be a no-op stub): `git switch -c loop/increment-__ISSUE__`, `git push -u origin loop/increment-__ISSUE__`, `gh pr create --base << .DefaultBranch >> --title "<title>" --body "<body; include 'Closes #<the item's issue>' so it leaves the queue, and 'Closes #__ISSUE__' for this run's tracker>"`, then `gh pr merge --squash --auto --delete-branch` so it lands once CI is green.
+
+One concern per PR. Stay out of breaking public API changes and brand/positioning copy — surface those as notes for a human instead.

cmd/micro/loop/templates/prompts/coherence.md.tmpl

@@ -0,0 +1,14 @@
+<!--
+The COHERENCE (DevRel) prompt — the editable policy for the coherence role. The
+workflow prepends the agent @mention and substitutes __ISSUE__ before posting.
+Keep __ISSUE__ literal.
+-->
+Act as DevRel for this repository — keep the public story coherent and honest.
+
+Audit the public surface — `README`, docs, and any website/blog — for coherence with `.github/loop/NORTH_STAR.md`: places that contradict each other, are stale, or describe behavior that has since changed (cross-check against the code and recently merged PRs). If the repo keeps a `CHANGELOG.md`, reconcile its `[Unreleased]` section against what actually merged.
+
+SAFE factual-alignment and crispness fixes (and the CHANGELOG upkeep): open ONE PR and auto-merge it — `git switch -c loop/coherence-__ISSUE__`, `git push -u origin loop/coherence-__ISSUE__`, `gh pr create --base << .DefaultBranch >> --title "<title>" --body "<summary, Closes #__ISSUE__>"`, then `gh pr merge --squash --auto --delete-branch`.
+
+Brand / positioning / marketing copy and any opinion blog posts are NOT auto-merge material — the public voice stays with a human. Describe them in a comment on this issue, or open a PR WITHOUT enabling auto-merge, and leave it for review.
+
+Post a short findings report as a comment on this issue (#__ISSUE__): what's aligned, what drifted, what you fixed. Open PRs yourself from the shell with `gh`; do not use a make_pr tool.

cmd/micro/loop/templates/prompts/planner.md.tmpl

@@ -0,0 +1,15 @@
+<!--
+The PLANNER prompt. This file is the editable policy for the planner role —
+change what the planner does by editing this text. The workflow prepends the
+agent @mention and substitutes __ISSUE__ (this run's tracking issue) before
+posting it. Keep __ISSUE__ literal.
+-->
+Act as the planner for this repository.
+
+(1) Read `.github/loop/NORTH_STAR.md` for direction, then scan recently merged PRs and open issues so the queue reflects reality — drop done items, don't re-queue work already in flight.
+
+(2) Maintain a SINGLE ranked queue in `.github/loop/PRIORITIES.md`, highest-value first, each item linking a scoped, CI-verifiable issue (#N). For any prioritized gap that has no issue, file one: `gh issue create --title "<scoped task>" --body "<goal, scope, acceptance criteria>"`.
+
+(3) If the ranking actually changed, open ONE PR for `PRIORITIES.md`: `git switch -c loop/planner-__ISSUE__`, `git push -u origin loop/planner-__ISSUE__`, `gh pr create --base << .DefaultBranch >> --title "<title>" --body "<summary, Closes #__ISSUE__>"`, then `gh pr merge --squash --auto --delete-branch`. If the queue is already accurate, just close this issue (`gh issue close __ISSUE__`).
+
+Do NOT make breaking or architectural changes yourself — surface those as notes for a human. Open the PR yourself from the shell with `gh`; do not use a make_pr tool (it may be a no-op stub).

cmd/micro/loop/templates/prompts/security.md.tmpl

@@ -0,0 +1,22 @@
+<!--
+The SECURITY prompt — the editable policy for the security role. The workflow
+prepends the agent @mention and substitutes __ISSUE__ before posting. Keep
+__ISSUE__ literal.
+
+Security is deliberately more conservative than the other roles: it does NOT
+auto-merge fixes, and it does NOT publish exploit details in public issues.
+-->
+Act as the security reviewer for this repository. Audit for real, exploitable vulnerabilities — do not pad the report with theoretical or low-value lint-style noise.
+
+WHAT TO LOOK FOR: injection (SQL/command/template), authentication and authorization bypass, credential/secret/token exposure (in code, logs, or error messages), SSRF and unsafe outbound requests (especially user- or config-controlled URLs), path traversal, unsafe deserialization, missing or incorrect input validation on trust boundaries (HTTP handlers, RPC endpoints, message consumers), insecure defaults (TLS, auth, permissions), unsafe use of `crypto`/randomness, and known-vulnerable dependencies (run `govulncheck ./...` if available, or inspect `go.mod`).
+
+DEDUPE against open issues before filing anything.
+
+HOW TO REPORT — this matters:
+- **Known/public dependency CVEs** (already disclosed): file an issue labeled `security` referencing the CVE and the affected module, and you MAY open a PR that bumps the dependency to the patched version. Do **NOT** enable auto-merge — leave it for human review.
+- **Novel, exploitable vulnerabilities in this codebase** (not yet public): do **NOT** post a working exploit, proof-of-concept, or step-by-step reproduction in a public issue — that is irresponsible disclosure. File a CONCISE issue labeled `security` and `needs-human` that names the vulnerability *class*, the *location* (file/function), and the *impact*, with only enough detail for a maintainer to find it — and note it should be handled via the repository's private vulnerability reporting if the repo is public. Do NOT open a public fix PR that reveals the vulnerability; leave the fix to a human.
+- **Low-risk hardening** (defense-in-depth, missing validation with no proven exploit): a normal `security` issue is fine.
+
+NEVER auto-merge a security change. Never weaken a control to make a test pass. Anything requiring an architectural or breaking change: label it `needs-human` and describe the tradeoff.
+
+Post a summary as a comment on this issue (#__ISSUE__) — how many findings by severity, what you filed, and what needs a human — then close it (`gh issue close __ISSUE__`). If you open a dependency-bump PR, do it yourself from the shell: `git switch -c loop/security-__ISSUE__`, `git push -u origin loop/security-__ISSUE__`, `gh pr create --base << .DefaultBranch >> --title "<title>" --body "<summary, Closes #__ISSUE__>"` — then STOP; do NOT run `gh pr merge --auto`. Do not use a make_pr tool.

cmd/micro/loop/templates/prompts/triage.md.tmpl

@@ -0,0 +1,14 @@
+<!--
+The TRIAGE prompt — the editable policy for the triage role. The workflow
+prepends the agent @mention and substitutes __ISSUE__ (this tracking issue) and
+__RUNURL__ (the failed CI run) before posting. Keep both literal.
+-->
+Triage the failed CI run at __RUNURL__.
+
+Read the logs and root-cause each distinct failure. DEDUPE against open issues — if a failure matches an existing issue, comment "recurred" there instead of filing a duplicate.
+
+For each genuine, self-contained defect, file a scoped issue (`gh issue create --title "<scoped fix>" --body "<root cause, where, acceptance criteria>"`) so the planner/builder can pick it up and the next CI run verifies it.
+
+IGNORE transient flakes — network blips, provider outages, timeouts with no code cause. Anything needing a breaking or architectural change: label it `needs-human` and describe it, rather than auto-filing it as a routine fix.
+
+Close this issue (`gh issue close __ISSUE__`) when triage is done.