release: Release v0.2.0

[pedronauck]

Release v0.2.0

This PR prepares the release of version v0.2.0.

Changelog

0.2.0 - 2026-05-07

🎉 Features

• Support few new commands

• BREAKING: support few new commands

📚 Documentation

• Update readme

• Remove skill from readme

• Remove wrong skill

• Improve readme and skill

• Update readme

Release Notes

Breaking Changes

skeeper.lock is tracked in the main repo

A new skeeper.lock file is now committed to the main repository. It pins each main commit to exact sidecar commits per namespace and records sidecar URL, source branch, namespace branch, sidecar commit SHA, content digest, file count, and byte count. The managed hooks write and stage it; skeeper verify and the CI Action check it; skeeper hydrate restores from it.

How to upgrade:

1. Run skeeper hooks install once. The installer also configures the skeeper.lock merge driver via .gitattributes.
2. Run skeeper sync to generate the initial lockfile.
3. Commit skeeper.lock alongside your normal change.
4. Add the file to your code-review checklist or grant it auto-merge: it changes on every spec edit.

Do not edit the SHAs in skeeper.lock by hand. Use skeeper sync or skeeper merge-driver to regenerate it.

Strict sync replaces async post-commit

The async post-commit hook with its 750 ms budget and .git/skeeper/queue.json retry queue is gone. Skeeper now installs strict pre-commit, pre-merge-commit, and pre-push hooks that mirror specs, push the sidecar, write skeeper.lock, and stage it before Git creates the main commit. If the sidecar push fails, the main commit fails with it.

This is intentional: a committed main change can no longer silently drift from its sidecar.

How to upgrade:

1. Pull the new release.
2. Run skeeper hooks install once per clone. This removes the legacy post-commit block, installs the strict blocks, writes .gitattributes, and configures the skeeper.lock merge driver.
3. Commit the resulting skeeper.lock if skeeper sync reports new state.
4. If you need to commit during a known-broken sidecar window, use the audited SKEEPER_SKIP=1 bypass and run skeeper sync afterward. git commit --no-verify is unsupported.

Features

New adopt, untrack, and pattern commands

Three new commands cover the full lifecycle of bringing existing files under sidecar coverage and inspecting how globs route into namespaces:

• skeeper adopt <path-or-glob>... mirrors files already in the main index into the sidecar and removes them from main-index tracking in a single transaction. Supports --dry-run, --json, --force, --commit --message <msg>.
• skeeper untrack <path-or-glob>... reverses adoption: stops tracking matched specs in the main repository after the sidecar has the latest content.
• skeeper pattern test <glob> previews which working-tree files a glob would match, scoped to a namespace with --namespace.
• skeeper pattern add <glob> [--namespace <name>] [--exclude <glob>]... [--adopt-existing] updates .skeeper.yml, refreshes the managed .gitignore block, and (with --adopt-existing) runs the adoption transaction in one step.

All four commands accept --json for scripting and --force to override the broad-plan guardrails configured under settings.guardrails.

Audited bypass with SKEEPER_SKIP=1

Skipping a hook should leave a paper trail. Setting SKEEPER_SKIP=1 lets the strict pre-commit and pre-merge-commit hooks pass without syncing, but every bypass:

1. Records a JSON audit entry at .git/skeeper/bypass.json with reason and timestamp.
2. Prints a warning to stderr.
3. Stays visible in skeeper status, skeeper fsck, and the pre-push hook until the next successful skeeper sync clears it.

The variable name is configurable via settings.hooks.allow_skip_env. git commit --no-verify is unsupported because Git skips all hook code and cannot record the audit entry.

Branch-aware namespace history

Sidecar branches now follow the pattern <namespace>/__branches__/<source-branch>, so feature-branch spec history is isolated from main automatically. Two engineers iterating on feature/auth-redesign see their own sidecar branch; main keeps a clean canonical history.

The __branches__ segment is reserved and rejected as a namespace name to keep the routing unambiguous.

Official compozy/skeeper GitHub Action

The repo now ships a same-repository GitHub Action (action.yml) that downloads the released Skeeper binary for the requested version and delegates to the CLI. Default arguments run skeeper verify so pull requests fail when skeeper.lock and the sidecar remote disagree.

- uses: compozy/skeeper@v0.2.0
  with:
    args: |
      verify
      --json
    ssh-private-key: ${{ secrets.SKEEPER_SSH_PRIVATE_KEY }}

Credential precedence: ssh-private-key writes a temp key and sets GIT_SSH_COMMAND; otherwise token configures HTTPS GitHub credentials; otherwise the runner's existing Git/SSH config is used. Secrets are masked before configuration, the temp key is wiped on always() cleanup, and Linux/macOS/Windows on amd64/arm64 are all resolved through the same release manifest.

Merge driver for skeeper.lock

skeeper.lock is a structured file with sidecar SHAs that 3-way text merge cannot reason about safely. The new skeeper merge-driver command resolves conflicts deterministically by re-running reconciliation against the merged worktree, and skeeper hooks install wires it through .gitattributes automatically.

Try it:

skeeper hooks install
git merge other-branch   # any skeeper.lock conflict regenerates instead of aborting

When merging outside the hook (for example a rebase resolved by hand), run skeeper sync to refresh the lock and stage it.

skeeper log --latest

skeeper log <path> reads the locked sidecar commit by default, matching skeeper hydrate. The new --latest flag fetches the namespace branch and reads its current tip instead, which is useful when investigating why the working tree disagrees with the lockfile or when reviewing in-flight changes from another contributor before they land in main.

Repair workflow for failed syncs

When a strict hook fails partway through (network drop, auth expiry, sidecar contention), Skeeper now records a resumable transaction at .git/skeeper/transaction.json instead of leaving the working tree in an unknown state. The new skeeper repair subcommands act on that record:

• skeeper repair status shows the active transaction phase and any pending audit bypass.
• skeeper repair resume re-runs reconciliation against the recorded plan once the underlying problem is fixed.
• skeeper repair abort clears the transaction — only safe before the main index has been mutated.

skeeper status also surfaces the repair state inline so you do not need to remember to check.

Read-only verification commands

Three new read-only commands prove sidecar state without mutating files or refs:

• skeeper verify cross-checks skeeper.lock against the sidecar remote. The same path runs inside the managed pre-push hook and inside the GitHub Action.
• skeeper fsck compares the working tree's spec files against the locked sidecar content and reports drift with structured diagnostic codes.
• skeeper hooks check validates that the managed hook blocks are present, ordered last in pre-commit, and that the merge driver is configured.

Every command supports --json for CI consumption. verify and fsck accept --source-branch to check a specific branch instead of the current HEAD.

Highlights

skeeper hydrate restores from locked commits

skeeper hydrate no longer reaches for a best-effort branch tip. It reads the exact sidecar commit SHA stored in skeeper.lock for the current main commit and restores spec files from that commit. Fresh clones, bisects, and historical checkouts all see the spec state that actually shipped with the code, not whatever happens to be at the head of the namespace branch today.

If you need the live tip for diagnostics, skeeper log <path> --latest and skeeper status still surface it.

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (15)

• .release-notes/archive/v0.2.0/adopt-untrack-pattern-commands.md is excluded by !**/*.md
• .release-notes/archive/v0.2.0/audited-bypass.md is excluded by !**/*.md
• .release-notes/archive/v0.2.0/branch-aware-namespace-branches.md is excluded by !**/*.md
• .release-notes/archive/v0.2.0/github-action.md is excluded by !**/*.md
• .release-notes/archive/v0.2.0/hydrate-from-locked-commits.md is excluded by !**/*.md
• .release-notes/archive/v0.2.0/lockfile-merge-driver.md is excluded by !**/*.md
• .release-notes/archive/v0.2.0/log-latest-flag.md is excluded by !**/*.md
• .release-notes/archive/v0.2.0/repair-workflow.md is excluded by !**/*.md
• .release-notes/archive/v0.2.0/skeeper-lock-tracked-in-main.md is excluded by !**/*.md
• .release-notes/archive/v0.2.0/strict-sync-replaces-post-commit.md is excluded by !**/*.md
• .release-notes/archive/v0.2.0/verify-fsck-hooks-check.md is excluded by !**/*.md
• CHANGELOG.md is excluded by !**/*.md
• RELEASE_BODY.md is excluded by !**/*.md
• RELEASE_NOTES.md is excluded by !**/*.md
• package.json is excluded by !**/*.json

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 8ac8ce71-147e-4778-8b00-5d439b7b4af2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch release/v0.2.0

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

✅ Dry-Run Completed Successfully

📊 Build Summary

• Version: 0.0.0-1778190481
• Commit: 1e68bca

📦 Built Artifacts

Not available.

---

This is an automated comment from the release dry-run check.