@davesheffer/hunch 1.8.2 → 1.9.2

package/README.md

@@ -13,6 +13,14 @@ relevant context before it makes a change.
 Memory starts **advisory**. Nothing blocks until you explicitly trust a precise rule and choose
 strict enforcement.
 
+**Memory is the input. The product boundary is the receipt:** relevant evidence before an edit,
+then a deterministic check of the change against the rules your team has explicitly trusted.
+
+> **New in v1.9.2:** Matrix mode gives the whole team one live, private Git memory across fresh
+> clones, worktrees, CLI checks, and MCP assistants. npm publishes with short-lived OIDC
+> credentials, while the editor companion ships as one immutable, publicly verified Open VSX
+> artifact.
+
 ## Start in five minutes
 
 Requires Node 22.13+ and a git repository.
@@ -66,6 +74,81 @@ hunch firmness strict
 hunch check --staged --strict
 ```
 
+## Share one living team memory
+
+Matrix mode keeps the team's decisions, corrections, constraints, and proofs in one dedicated Git
+repository, separate from the code repository. Hunch does not host that repository: create a private
+Git repo that every teammate can access, install the Matrix release on team machines and CI, then
+have one maintainer run:
+
+```bash
+npm i -g @davesheffer/hunch@1.9.2
+hunch shared --repo git@github.com:acme/project-hunch-memory.git
+git add .gitignore .hunch/team.json
+git commit -m "chore: connect shared Hunch memory"
+git push
+```
+
+Use a credential-free URL in the command; keep tokens in your Git credential helper or use SSH.
+If this project already publishes memory in `.hunch/` and you want to move it into the dedicated
+repo, add `--migrate`, review the reported untrack/ignore changes, and follow the commit instructions
+printed by Hunch. Omit `--migrate` for a new setup.
+
+After the pointer commit lands, teammates need Hunch installed and Git access to the memory repo:
+
+```bash
+npm i -g @davesheffer/hunch@1.9.2
+git pull
+hunch init
+hunch doctor
+```
+
+`hunch init` validates and connects an ignored local clone of the memory repo. Memory-reading and
+writing CLI operations attempt a bounded refresh at startup; connected MCP sessions check for new
+team memory at each tool-request boundary and rebuild their local index only when the JSON changed.
+New captures route to that repo and are committed and synchronized automatically by default. If a
+push cannot complete, a later capture or `hunch shared --sync` retries it.
+
+The committed `.hunch/team.json` contains only the credential-free memory-repo locator and canonical
+branch. The ignored `.hunch/local.json` contains local paths and preferences, not credentials;
+authentication stays in SSH or the normal Git credential helper. Shared memory records,
+`.hunch/local.json`, and `.hunch-private/` stay out of code history. Use
+`hunch check --base origin/main --strict --public-only --format markdown` for output that may be
+posted publicly; omit `--public-only` for an internal check that should enforce team memory.
+
+For a correction that Hunch can express as a deterministic policy, create and inspect its
+proof-backed proposal:
+
+```bash
+hunch policy upgrade-correction con_...
+hunch policy card pol_...
+```
+
+The upgrade creates evidence, a plan, and a proof but leaves the policy proposed with
+`authority: none`. In v1.9 its source-currentness activation gate is deliberately blocked, so even a
+human cannot activate an upgraded correction yet. Other proved policy types still require an
+explicit audited human acceptance before they can become advisory or blocking; Hunch never grants
+that authority automatically.
+
+Need to pause or roll back without deleting memory?
+
+```bash
+hunch firmness off
+hunch shared --repo git@github.com:acme/project-hunch-memory.git --no-auto-commit
+# Later, publish any pending local memory explicitly:
+hunch shared --sync
+```
+
+The first command turns off agent-hook enforcement; the second keeps shared reads and local captures
+but stops automatic memory commits and pushes. As a team-coordinated rollback, revert the setup
+commit to stop discovery after teammates pull the revert. Existing machines retain their ignored
+local overlay until they are deliberately disconnected; do not delete the memory repo as part of a
+rollback. For this rollout, reinstall the previous published package with
+`npm i -g @davesheffer/hunch@1.8.5`; the release receipt resolves and records that exact rollback
+target from the npm registry instead of trusting Git tags. Version 1.8.5 fails closed when it sees a
+v1.9 source-gated correction policy, so pause enforcement first as shown above and upgrade every
+team client to v1.9 before resuming Matrix policy workflows.
+
 ## Synthesis without surprise billing
 
 Hunch can draft structured memory through:
@@ -97,12 +180,24 @@ hunch private --repo git@github.com:you/project-memory.git
 
 Local tools see the combined graph; public CI and committed documentation stay public-only.
 
+## Releases you can trace to source
+
+Hunch releases are built and tested without publication credentials. The resulting npm tarball or
+VSIX is content-addressed, carried unchanged into a minimal publisher, and checked again against the
+registry after publication. The npm path also runs native, atomic-write, and Matrix safety checks on
+Windows and macOS and verifies provenance back to the exact source tag.
+
+The editor companion is published from an exact `vscode-v*` tag to
+[Open VSX](https://open-vsx.org/extension/davesheffer/hunch-vscode). The workflow verifies the
+downloaded public VSIX has the same digest as the credential-free release candidate.
+
 ## Learn more
 
 - [Full documentation](https://hunch-pi.vercel.app/docs)
 - [Copy-paste cookbook](https://hunch-pi.vercel.app/cookbook)
-- [VS Code extension](vscode-extension/README.md)
+- [VS Code extension guide](vscode-extension/README.md)
 - [Contributing](CONTRIBUTING.md)
 - [Architecture benchmark](bench/architectural-conformance.md)
+- [Competitive landscape (dated; re-verify before quoting)](docs/competitive-landscape.md)
 
 Apache-2.0