mason-context 0.20.2 → 0.22.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## Unreleased
 
+## 0.22.0 — 2026-10-12
+
+- Separate CLI scopes: `mason init` prepares shared repository integration without activating it; `mason setup` activates compatible existing configuration using local state only. `mason teardown` now disconnects locally; use `--project` explicitly for shared removal. Initialization and teardown support read-only `--dry-run` previews. Compatible older instructions, supported legacy hooks and JSON formatting do not force shared rewrites; status reports optional template updates separately. MCP exposes matching `init`/`setup` modes. Setup no longer triggers background update checks. Migrate scripts that used setup to generate configuration to `mason init` followed by `mason setup`; scripts removing shared configuration must add `teardown --project`.
+
+- Simplify project integration to MCP, reasoning instructions and decision hooks, prepared by `mason init` and activated locally by `mason setup`. Remove automatic documentation audits, committed-diff review, repair capture and statistics enrollment. Setup results expose a configuration receipt instead of audit findings/report paths; legacy receipt pointers and existing audit artifacts remain intact. Statistics are opt-in through `mason stats --enable`; existing preferences are unchanged. Run `mason init --host <host>` after upgrading to refresh the shorter shared project guidance, review and commit those changes, then run `mason setup --host <host>` locally.
+
+- Separate lifecycle decision checks from documentation-repair automation. Hooks check current decision anchors without discovering document claims, creating repair baselines, or verifying old audit findings. Preserve paired edit observation, source-inspection and human-review boundaries, Stop deduplication, guidance delivery and explicit audit checks. Reuse the event/receipt store with a separate guidance report pointer; status and setup output label verification scope. Old baselines and assessments stay available to explicit checks.
+
+- Consolidate documentation repair and advisory assessment on the existing CLI: remove the duplicate `mason_repair` and `review_advisory` MCP tools. Use `mason audit --prepare-repair`, `mason audit --verify-repair <baselinePath>`, and `mason audit review`. Update project instructions, work orders and hook notices to point to these commands. Run `mason init --host <host>` after upgrading to refresh shared instructions. Existing baselines, review records, hooks and decision review semantics remain supported.
+
+- Remove managed architecture-map creation (`generate_snapshot_batch`, `save_partial_snapshot`, `reduce_snapshot`, and `mason_init` map mode) and general orientation (`full_analysis`, `analyze_project`, `get_code_samples`). Remove batch prompts, partial-store management, the orientation analyzer and sampler. Keep existing map reading, direct saving, drift and verification; direct saves merge supported updates and no longer consume or clear old partials. Missing maps return a short decision-context pointer. Refresh instructions use the agent's source tools and direct saving. Keep 0.21.0 for the old managed build workflow and run `mason init --host <host>` after upgrading to refresh shared project instructions.
+
+- Remove Confluence publishing (`mason_set_confluence`, `export_to_confluence`) and its standalone LLM provider/configuration layer to focus maintenance on engineering reasoning. Remove the Anthropic/OpenAI SDK dependencies. Existing wiki pages, legacy feature settings, and user credentials are left untouched; Mason no longer reads or updates them. `mason_complete_init` no longer accepts `confluenceConfigured` or advertises Confluence status. Users needing wiki publishing should keep 0.21.0 until they migrate that workflow to a separate publisher.
+
+- Deliver file-scoped decision knowledge through standard Claude hooks after `Read` and before `Edit`/`Write`, reusing the existing injector and session deduplication. Confine delivery to the active checkout, retain approval/freshness labels and audit diagnostics, and preserve the standalone PostToolUse contract. Shell commands and Codex remain outside direct lesson injection.
+- Flatten hook commands to `mason install`, `mason config`, and `mason hook --host claude|codex`. Generate shorter hook handlers and migrate existing configurations without duplicates. Retain `mason auto …` aliases and the standalone decision injector for compatibility.
+
+## 0.21.0 — 2026-10-10
+
+- Continue Claude once at Stop when outstanding decision drift overlaps observed session anchor edits. Require source inspection, preserve human approval boundaries, and keep repeat Stops and Codex advisory. Add local `mason auto config --stop-block off|drift` controls and status reporting. Include uncommitted anchor changes in drift findings for accepted and legacy decisions using Git baselines.
+
+- Capture readable decision anchors when saving proposals, so committing a proposal with its implementing code does not create false drift. Later source edits still require inspection; unreadable scopes retain unknown freshness.
+- Add separate source inspections that resolve covered drift without claiming human acceptance or changing the accepted revision. Bind preparation tokens to source bytes, preserve original audit evidence, and reopen inspections after relevant changes.
+- Batch anchor inventories, index path scopes, and reuse decision reads within each inspection while retaining fresh final validation. Add reproducible validation against pinned Now in Android and WordPress Android repositories, with measured hook costs documented in `docs/hook-performance.md`.
+
 ## 0.20.2 — 2026-09-30
 
 - Show decision titles and the inspection command before changed file paths in completion warnings, so long paths cannot hide the reason for review or the next step.

package/README.md

@@ -2,9 +2,9 @@
 
 # Mason
 
-### Your agents are creating tech debt. Mason helps you prevent it.
+### Preserve why your code was built this way.
 
-**Remember why decisions were made · Catch outdated guidance · Find what else needs updating**
+**Record the reason · Review the lesson · Surface applicable guidance · Reconsider it as code changes**
 
 [![npm version](https://img.shields.io/npm/v/mason-context?style=flat-square&labelColor=334155&color=2563eb)](https://www.npmjs.com/package/mason-context)
 [![CI](https://img.shields.io/github/actions/workflow/status/adrianczuczka/mason/ci.yml?branch=main&style=flat-square&labelColor=334155&label=CI)](https://github.com/adrianczuczka/mason/actions/workflows/ci.yml)
@@ -18,6 +18,8 @@
 
 </div>
 
+Mason preserves reviewed engineering reasoning with your repository, so future maintainers and coding agents can retrieve the evidence behind consequential decisions. Record workarounds, rejected approaches and constraints while their reasons are available; revisit them when the underlying code changes.
+
 ## Get started
 
 Install on macOS or Linux:
@@ -39,11 +41,12 @@ New standard standalone installs update automatically in the background. Updates
 Run this in your Git repository (open a new terminal if the installer asks):
 
 ```bash
-mason setup --host codex
+mason init --host codex    # Maintainer: prepare shared configuration for review/commit
+mason setup --host codex   # Each developer: activate locally
 # For Claude Code, use --host claude.
 ```
 
-Setup connects MCP, hooks, and project instructions. Review your host's trust settings, start a new session, and give your agent a normal task.
+If the repository already has compatible Mason configuration, run only `mason setup`. Initialization prepares MCP, hooks and project instructions; setup leaves shared files untouched. Review your host's trust settings, start a new session, and give your agent a normal task.
 
 Check that Mason is being used:
 
@@ -71,7 +74,7 @@ The audit checks claims in README and agent instruction files throughout the rep
 | Old decisions lose their context. | Retrieving recorded rationale and review status, and flagging changes to the code they apply to. |
 | A repair gets interrupted. | Retaining the original findings and verifying them through the final documentation commit. |
 
-After resolving an incident or settling a constraint, ask your agent to record the reason with Mason. Later tasks can retrieve it. Proposals and accepted decisions stay distinct.
+After resolving an incident or settling a constraint, ask your agent to record a sourced proposal with Mason. Review it before accepting it as project guidance. Later tasks can retrieve the operative accepted revision while proposed replacements remain distinct, and changes to referenced code can prompt inspection, revision or retirement.
 
 Mason complements tests, linters, and code review. Findings are evidence to inspect; unavailable checks stay explicit.
 
@@ -79,6 +82,8 @@ Mason complements tests, linters, and code review. Findings are evidence to insp
 
 Earlier read-only decision-retrieval evaluations scored **9.0/10 with Mason vs 7.0/10 without**. The initial ten-task patch comparison tied at **10/10 for both**. Improved patch outcomes remain to be demonstrated. [Results, methodology, and limitations](docs/benchmarks.md)
 
+Maintained notes also succeeded in the reuse trials. Recent hook experiments verified supported file delivery, with additional context cost and no demonstrated correctness gain; direct delivery for ordinary Bash workflows remains open. The current focus is useful preservation and reuse of engineering reasoning during ordinary work, with capture and maintenance effort that feels worthwhile. Preventing repeat mistakes is one intended benefit; comparative superiority remains unestablished. [Positioning and validation plan](ROADMAP.md#historical-context-focus--2026-10-12) · [Current evidence](ROADMAP.md#current-evidence-and-boundaries)
+
 ## Documentation
 
 - [Setup, hooks, and upgrades](docs/setup.md)
@@ -86,3 +91,17 @@ Earlier read-only decision-retrieval evaluations scored **9.0/10 with Mason vs 7
 - [Audits, repair verification, and CI evidence](docs/checks.md)
 - [Decisions, tools, and optional architecture maps](docs/reference.md)
 - [Roadmap](ROADMAP.md) · [Changelog](CHANGELOG.md) · [MIT license](LICENSE)
+
+## Development
+
+For development, use Node 20 (20.19+), Node 22 (22.13+), or Node 24+.
+After `npm ci`, run `npm run format` to format TypeScript sources, tests, and tooling configs.
+CI checks formatting with `npm run format:check` and runs `npm run lint`,
+`npm run typecheck`, and the test suite. Run `npm test` locally to check behavior.
+
+ESLint uses the recommended TypeScript rules plus type-aware checks for unhandled
+promises, misused async callbacks, and invalid awaits. Prettier handles formatting.
+Test fixtures and generated outputs are excluded from formatting and linting.
+Production sources also reject explicit `any` and unsafe assignments, property
+access, calls, arguments, and returns. External data is validated before use.
+Test doubles keep the more permissive rules.