mason-context 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## Unreleased
+
+## 0.23.0 — 2026-10-21
+
+- `save_decision` guidance asks for the constrained functions, types, or settings to be named in backticks, so drift notices can judge relevance. Anchors remain whole files or directories, and anchored changes still require inspection; symbol anchors and automatic clearing of trivial drift were considered and not adopted.
+- Attribute decision drift on a branch to the branch or to the default branch it builds on. Previously a rebase made every decision the default branch had changed look like this checkout's unchecked work. Drift in anchors this branch touched is reported as before; drift that arrived only from the default branch is listed once per session, never blocks Stop, and is reported as usual on the default branch. `review_decision(prepare)` reports the same split in `previews.attribution`. Explicit audits still report all drift.
+- `review_decision(action: "prepare")` previews source, diff and anchor commits since the latest inspection still valid for the record and scope, instead of since the original evidence baseline, and reports the commit used in `previews.diffSince`. Earlier changes were already inspected, so long-lived records no longer return months of truncated history. Pass `diffFrom: "capture"` for the full history. Responses include the latest two inspections and count older ones; the record file keeps them all. Review evidence, tokens and verdict requirements are unchanged.
+- Stop failed, denied and interrupted tool calls from filling the automation store. Previously every new session failed once 128 sessions held unfinished calls, or once `state.json` passed 10 MiB, until the file was edited by hand. Claude configurations now register `PostToolUseFailure`; run `mason init --host claude` to add it, as older configurations stay compatible without it. Pending captures are dropped when the turn ends or after 24 idle hours. Sessions are evicted least recently used even with unfinished calls. `state.json` is written compactly and shrunk instead of failing when oversized, including files left by earlier versions. `mason status --json` reports unfinished tool calls, and an attempt still in flight no longer makes status `unavailable`.
+- Show the changed lines in decision drift notices, including the Claude Stop review, so most irrelevant edits can be dismissed without another tool call. Hunks are diffed against the exact captured content of the last inspection or save. Each notice reports code identifiers named by the decision (backticked names, calls, camelCase or snake_case) that the changed lines or their enclosing declarations mention, or `Low relevance` when none are; decisions naming no identifiers are not assessed. Relevance is a name match only: findings, inspection requirements and Stop blocking are unchanged.
+- Merge decision records automatically when branches each append inspections or review history, instead of conflicting inside the JSON on every rebase of a stacked branch. `mason init` adds a `.gitattributes` entry for `.mason/decisions/*.json`; `mason setup` configures the local `mason-decision` Git merge driver, and `mason status` reports a committed attribute without it. Two different changes to the same field still conflict, and Git's ordinary text conflict is used whenever Mason refuses a merge or is not on PATH. Run `mason init --host <host>` to add the attribute, commit `.gitattributes`, then run `mason setup` in each checkout.
+- Leave Git-ignored files beneath a directory anchor out of its capture instead of marking the capture incomplete, so local setup files no longer block `review_decision` inspection or make the anchor's freshness unknown. Anchors naming only ignored content still stay unknown. An incomplete capture now leaves only its own decision's earlier drift findings unverified instead of every decision's.
+
+## 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.

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)