Restructure CLI internals, simplify memory, and harden releases

.github/workflows/ci.yml

@@ -43,12 +43,6 @@ jobs:
 
   build-and-lint:
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        module:
-          - .
-          - memory/tools/knowledge-sync
     steps:
       - uses: actions/checkout@v4
 
@@ -58,22 +52,38 @@ jobs:
           cache: false
 
       - name: Test
-        working-directory: ${{ matrix.module }}
         run: go test ./...
 
       - name: Build
-        working-directory: ${{ matrix.module }}
         run: go build ./...
 
       - name: Vet
-        working-directory: ${{ matrix.module }}
         run: go vet ./...
 
       - name: Lint
         uses: golangci/golangci-lint-action@v7
         with:
           version: v2.12.2
-          working-directory: ${{ matrix.module }}
+
+  memory-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Test memory hooks and lib
+        run: python3 -m unittest discover -s memory/tests
+
+  release-script:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Test release script validation
+        run: sh scripts/release_test.sh
 
   npm-wrapper:
     runs-on: ubuntu-latest

.github/workflows/release.yml

@@ -1,36 +1,82 @@
 name: Release
 
+# Publishing happens from a v* tag, but only after the tag has been verified
+# against main and a green ci.yml run, and after the protected `release`
+# environment approves. Configure that environment in repository settings with
+# required reviewers, and keep HOMEBREW_TAP_TOKEN scoped to it.
+
 on:
   push:
     tags:
       - "v*"
 
 permissions:
-  contents: write
+  contents: read
 
 jobs:
+  verify:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+
+      - name: Verify tag, ancestry, and CI
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -eu
+          tag="${GITHUB_REF_NAME}"
+          if ! printf '%s' "$tag" | grep -Eq '^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$'; then
+            echo "::error::not a stable semver tag: $tag"
+            exit 1
+          fi
+          git fetch --no-tags --quiet origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "::error::$GITHUB_SHA is not on origin/main; releases are cut from main only"
+            exit 1
+          fi
+          successes=$(gh run list --workflow=ci.yml --commit "$GITHUB_SHA" --status completed --limit 20 \
+            --json headSha,conclusion \
+            --jq "[.[] | select(.headSha == \"$GITHUB_SHA\" and .conclusion == \"success\")] | length")
+          if [ "$successes" -lt 1 ]; then
+            echo "::error::no successful ci.yml run found for $GITHUB_SHA"
+            exit 1
+          fi
+          echo "verified $tag at $GITHUB_SHA (on main, ci.yml green)"
+
+      - name: Release script checks
+        run: sh scripts/release_test.sh
+
   goreleaser:
+    needs: verify
     runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-go@v5
+      - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
         with:
           go-version: "1.24"
 
-      - uses: goreleaser/goreleaser-action@v6
+      - uses: goreleaser/goreleaser-action@e435ccd777264be153ace6237001ef4d979d3a7a # v6
         with:
           distribution: goreleaser
-          version: "~> v2"
+          version: "v2.18.2"
           args: release --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           HOMEBREW_TAP_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
 
   npm-publish:
-    needs: goreleaser
+    needs: [verify, goreleaser]
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -39,9 +85,9 @@ jobs:
       run:
         working-directory: npm
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: 24
           registry-url: https://registry.npmjs.org

AGENTS.md

@@ -38,7 +38,7 @@ New starter content requires an explicit product decision and an inventory test
 
 # Development
 
-- Go version and module layout are declared by `go.mod` and `go.work`.
+- Go version and module layout are declared by `go.mod`. The memory tools under `memory/tools/` are packages of that root module; `setup` scaffolds a standalone `go.mod` beside each copied tool so a user-owned config root can build them without the source checkout.
 - Install the development CLI with `go install ./cmd/dotagents`.
 - Use focused package tests while iterating; run `go test ./...` before submission.
 - Use Python 3's standard library for the dependency-free basic memory tier.

README.md

@@ -173,18 +173,24 @@ tailscale serve --bg --set-path /dotagents http://127.0.0.1:8765
 
 ## Releases
 
+Releases are cut from `main` after the release PR is reviewed and merged, and only with explicit approval:
+
 ```bash
-scripts/release.sh v0.7.0    # verify + tag; CI publishes binaries, brew tap, npm
+scripts/release.sh vX.Y.Z    # verify + tag; CI publishes binaries, brew tap, npm
 ```
 
+The script refuses to run unless the tree is clean, `HEAD` matches `origin/main`, the tag is strict `vMAJOR.MINOR.PATCH`, and every check passes. Pushing the tag starts `.github/workflows/release.yml`, which re-verifies the tag against `main` and a green `ci.yml` run, waits on the protected `release` environment, then publishes binaries, the Homebrew tap, and the npm wrapper.
+
 ## Documentation
 
+- [Overview & comparison](https://yourconscience.github.io/dotagents/) — landing page, sync matrix, positioning
 - [docs/setup.md](docs/setup.md) — first-run walkthrough, review screen, multi-machine setup
 - [docs/skills.md](docs/skills.md) — authoring skills, external pins and audits
 - [docs/roles.md](docs/roles.md) — role format, model tiers, per-harness overrides
 - [docs/memory.md](docs/memory.md) — memory tiers, rem workflow, vault layout
 - [docs/comparison.md](docs/comparison.md) — how dotagents differs from rulesync, ruler, openskills
 - [Troubleshooting](docs/troubleshooting.md)
+- [memory/README.md](memory/README.md) — memory layer layout, hooks, and tools
 
 Project-level generators (rulesync, ruler) win on tool breadth; dotagents is user-level — one private repo, nine targets deep, pinned externals, review-first memory. Full table in [docs/comparison.md](docs/comparison.md).