@theihtisham/agent-shadow-brain 7.22.0 → 7.22.1

package/docs/launch/PROJECT_LEARNING_PLAN_v7.1.4.md

@@ -1,63 +1,63 @@
-# Project learning from reported outcomes
-
-Architecture decision, 2026-11-12. Added after the user's request that Shadow Brain learn from its work and improve relevant memory. Implementation and acceptance are in progress. This extends the [release plan](RESEARCH_AND_PLAN_v7.1.4.md) and [Project Kit](PROJECT_KIT_PLAN_v7.1.4.md).
-
-## What learning means here
-
-The project keeps useful knowledge, records how a saved memory helped or failed on a concrete task, and makes a small, inspectable adjustment when that memory already matches a similar future task. A user can remove a report or disable its ranking influence. The loop is **retrieve → do work → observe outcome → report evidence → adjust relevant future retrieval → inspect or reverse**.
-
-This is persistent retrieval feedback. It does not train model weights, verify the truth of a memory, autonomously improve source code, or prove a model became more capable. A successful tool invocation, a copied context pack, retrieval rank, and an agent's confidence do not establish a successful task. The interface must call feedback a **reported outcome** and retain whether the user or an agent supplied it.
-
-Automatic background consolidation is already an established design elsewhere: Letta documents background agents that review conversations and update its Git-backed memory. Shadow Brain's chosen release scope is a provider-free local feedback mechanism with explicit attribution and bounded ranking influence; no superiority claim follows from that difference. [Letta memory and dreaming, accessed 2026-11-12](https://docs.letta.com/configuration/memory/).
-
-The distinction between retrieval improvement and downstream answer quality matters. LongMemEval separates indexing, retrieval, and reading and tests multiple long-term memory abilities. The acceptance tests below establish deterministic feedback behavior and isolation; they are not a LongMemEval result or evidence of improved general task accuracy. [LongMemEval, revised 2025-03-04, accessed 2026-11-12](https://arxiv.org/abs/2410.10813).
-
-## Local state and explicit operations
-
-Store feedback in `<project>/.shadow-brain/memory-feedback.json`, alongside that project's memory. The file is optional. It has its own revision and enabled flag; it does not add a sixth global feature toggle or modify the base memory schema. The project-local controls remain separate from the existing global workflow.
-
-The shared service is `ProjectFeedbackStore(root, brain)`, with `get()` and `update(command, expectedRevision, reporter)`. All callers use that service. Writes are revision-checked and atomic under a local lock. Corrupt or unsafe files must fail visibly without being overwritten. The store must belong to the canonical project root and database.
-
-Each record includes a stable ID, canonical project and memory IDs, task text, rating, reason, evidence references, reporter, and created/updated timestamps. Ratings are `useful`, `not-useful`, or `incorrect`. The rating is a report, not an authoritative review state.
-
-Bounds: at most 500 records and 2 MiB serialized data; task at most 1,000 characters; mandatory reason at most 600; at most three evidence references of 180 characters each. References are labels and are never fetched. Inputs reject unsupported fields and unsafe control characters.
-
-An upsert replaces the existing report for the same memory, normalized task, and reporter. Repeating the same praise does not create additional votes. At 500 records, a new distinct report is rejected; existing reports can still be updated, and a user can remove records to make room. Removing one record is explicit. Disabling influence preserves the records and removes their effect. No silent age expiry is introduced in this release; report timestamps stay visible for review.
-
-The server assigns attribution: portal and CLI writes are user reports; MCP writes are agent reports. A client cannot elevate an agent report by submitting a `reporter` field. Each mutation resolves the memory and enforces the project before saving.
-
-| Interface | Operation |
-| --- | --- |
-| Project portal HTTP | GET `project-feedback`; POST record/remove/enable with the current revision |
-| Project CLI | `project feedback list`, `record`, `remove`, and `set` |
-| Project-local MCP | `project_feedback` with `kind: list` or `record`; agent attribution assigned by the server |
-| Global/default MCP | Project feedback tool unavailable |
-
-The MCP write description instructs the host to report only observed work and evidence, never success inferred from memory retrieval or tool completion. Users retain removal and enable/disable controls in the portal and CLI. Generated local skills may describe this optional feedback step, while respecting current user and project instructions.
-
-## Retrieval contract
-
-Only an adaptive context request with an explicit project-local feedback snapshot may use the feedback. Legacy ranking and the default global path remain unchanged.
-
-Apply influence after scope and review eligibility and only to candidates with a direct lexical match. Feedback cannot introduce a zero-hit record, revive archived/contested/superseded records, expand the project boundary, turn a graph-only neighbor into a direct match, create a source citation, or remove a caution. Empty-query browsing receives no effect.
-
-Compare normalized substantive query and reported-task terms. Remove generic task verbs; require at least one shared term and Jaccard similarity of at least 0.34. For the same normalized task, prefer the user's report when both user and agent reports exist; an agent report cannot silently displace a human correction. Consider up to three newest distinct relevant-task reports for the candidate after resolving that attribution preference. This deliberately conservative lexical gate does not provide semantic task equivalence.
-
-For each selected report, multiply its rating value by task similarity and attribution weight. Rating values are +0.08 for useful, −0.04 for not-useful, and −0.12 for incorrect; attribution weights are 1 for user and 0.5 for agent. Average the contributions and clamp the result to [−0.12, +0.08]. Add that adjustment to the base ranking score with a lower bound of zero. These constants are design limits, not empirically optimized accuracy estimates.
-
-The mean and ceiling limit repeated reporting influence; attribution reduces, but does not eliminate, the risk of mistaken agent self-assessment. This is not a tamper-resistant trust system. Distinct fabricated reports still cannot be treated as independent verification.
-
-Show the signed `Project task feedback` contribution in candidate explanations, including negative values. Where the response exposes report IDs and reporter kinds, retain only bounded relevant records. Do not hide a negative adjustment because the existing diagnostics previously expected only positive signals. An incorrect report is a prompt for a human to inspect or curate the memory, not an automatic deletion or change of review state.
-
-## Acceptance gates
-
-1. Record, read, update, remove, disable, and re-enable feedback across restart. Preserve other sidecars and base memory bytes for feedback-only mutations.
-2. Reject stale revisions, malformed fields, wrong-project or missing memory IDs, unsafe paths, and serialized bounds without partial changes.
-3. Repeating the same memory/task/reporter upserts rather than accumulates. A 501st distinct record fails without dropping an older record; an existing upsert still succeeds at the cap. User/agent attribution cannot be spoofed through HTTP or MCP, and a newer agent report cannot replace the same task's human signal.
-4. Useful feedback changes only an already matching adaptive candidate by the bounded amount. A negative report produces a visible signed adjustment. Unrelated tasks and empty queries have no effect.
-5. Archived, contested, superseded, zero-hit, graph-only, and foreign-project records remain ineligible for feedback promotion. Legacy output remains unchanged.
-6. Disable and remove restore the baseline score/selection with otherwise identical input. Sources, caution flags, and recorded relationship paths remain intact.
-7. Demonstrate feedback recorded through the local portal, influence in Context Lab and a fresh project-local MCP process, and the same outcome after restart. Verify MCP writes are agent reports, not user reports.
-8. Show the control, outcome attribution, reason, references, timestamps, conflict state, removal, and negative diagnostics in the actual desktop/mobile UI. Keep the terminology consistent in screenshots and documentation.
-
-The release evidence report must record actual outcomes of these gates. No fixed improvement percentage, universal accuracy claim, or automatic truth score is authorized by this plan.
+# Project learning from reported outcomes
+
+Architecture decision, 2026-11-12. Added after the user's request that Shadow Brain learn from its work and improve relevant memory. Implementation and acceptance are in progress. This extends the [release plan](RESEARCH_AND_PLAN_v7.1.4.md) and [Project Kit](PROJECT_KIT_PLAN_v7.1.4.md).
+
+## What learning means here
+
+The project keeps useful knowledge, records how a saved memory helped or failed on a concrete task, and makes a small, inspectable adjustment when that memory already matches a similar future task. A user can remove a report or disable its ranking influence. The loop is **retrieve → do work → observe outcome → report evidence → adjust relevant future retrieval → inspect or reverse**.
+
+This is persistent retrieval feedback. It does not train model weights, verify the truth of a memory, autonomously improve source code, or prove a model became more capable. A successful tool invocation, a copied context pack, retrieval rank, and an agent's confidence do not establish a successful task. The interface must call feedback a **reported outcome** and retain whether the user or an agent supplied it.
+
+Automatic background consolidation is already an established design elsewhere: Letta documents background agents that review conversations and update its Git-backed memory. Shadow Brain's chosen release scope is a provider-free local feedback mechanism with explicit attribution and bounded ranking influence; no superiority claim follows from that difference. [Letta memory and dreaming, accessed 2026-11-12](https://docs.letta.com/configuration/memory/).
+
+The distinction between retrieval improvement and downstream answer quality matters. LongMemEval separates indexing, retrieval, and reading and tests multiple long-term memory abilities. The acceptance tests below establish deterministic feedback behavior and isolation; they are not a LongMemEval result or evidence of improved general task accuracy. [LongMemEval, revised 2025-03-04, accessed 2026-11-12](https://arxiv.org/abs/2410.10813).
+
+## Local state and explicit operations
+
+Store feedback in `<project>/.shadow-brain/memory-feedback.json`, alongside that project's memory. The file is optional. It has its own revision and enabled flag; it does not add a sixth global feature toggle or modify the base memory schema. The project-local controls remain separate from the existing global workflow.
+
+The shared service is `ProjectFeedbackStore(root, brain)`, with `get()` and `update(command, expectedRevision, reporter)`. All callers use that service. Writes are revision-checked and atomic under a local lock. Corrupt or unsafe files must fail visibly without being overwritten. The store must belong to the canonical project root and database.
+
+Each record includes a stable ID, canonical project and memory IDs, task text, rating, reason, evidence references, reporter, and created/updated timestamps. Ratings are `useful`, `not-useful`, or `incorrect`. The rating is a report, not an authoritative review state.
+
+Bounds: at most 500 records and 2 MiB serialized data; task at most 1,000 characters; mandatory reason at most 600; at most three evidence references of 180 characters each. References are labels and are never fetched. Inputs reject unsupported fields and unsafe control characters.
+
+An upsert replaces the existing report for the same memory, normalized task, and reporter. Repeating the same praise does not create additional votes. At 500 records, a new distinct report is rejected; existing reports can still be updated, and a user can remove records to make room. Removing one record is explicit. Disabling influence preserves the records and removes their effect. No silent age expiry is introduced in this release; report timestamps stay visible for review.
+
+The server assigns attribution: portal and CLI writes are user reports; MCP writes are agent reports. A client cannot elevate an agent report by submitting a `reporter` field. Each mutation resolves the memory and enforces the project before saving.
+
+| Interface | Operation |
+| --- | --- |
+| Project portal HTTP | GET `project-feedback`; POST record/remove/enable with the current revision |
+| Project CLI | `project feedback list`, `record`, `remove`, and `set` |
+| Project-local MCP | `project_feedback` with `kind: list` or `record`; agent attribution assigned by the server |
+| Global/default MCP | Project feedback tool unavailable |
+
+The MCP write description instructs the host to report only observed work and evidence, never success inferred from memory retrieval or tool completion. Users retain removal and enable/disable controls in the portal and CLI. Generated local skills may describe this optional feedback step, while respecting current user and project instructions.
+
+## Retrieval contract
+
+Only an adaptive context request with an explicit project-local feedback snapshot may use the feedback. Legacy ranking and the default global path remain unchanged.
+
+Apply influence after scope and review eligibility and only to candidates with a direct lexical match. Feedback cannot introduce a zero-hit record, revive archived/contested/superseded records, expand the project boundary, turn a graph-only neighbor into a direct match, create a source citation, or remove a caution. Empty-query browsing receives no effect.
+
+Compare normalized substantive query and reported-task terms. Remove generic task verbs; require at least one shared term and Jaccard similarity of at least 0.34. For the same normalized task, prefer the user's report when both user and agent reports exist; an agent report cannot silently displace a human correction. Consider up to three newest distinct relevant-task reports for the candidate after resolving that attribution preference. This deliberately conservative lexical gate does not provide semantic task equivalence.
+
+For each selected report, multiply its rating value by task similarity and attribution weight. Rating values are +0.08 for useful, −0.04 for not-useful, and −0.12 for incorrect; attribution weights are 1 for user and 0.5 for agent. Average the contributions and clamp the result to [−0.12, +0.08]. Add that adjustment to the base ranking score with a lower bound of zero. These constants are design limits, not empirically optimized accuracy estimates.
+
+The mean and ceiling limit repeated reporting influence; attribution reduces, but does not eliminate, the risk of mistaken agent self-assessment. This is not a tamper-resistant trust system. Distinct fabricated reports still cannot be treated as independent verification.
+
+Show the signed `Project task feedback` contribution in candidate explanations, including negative values. Where the response exposes report IDs and reporter kinds, retain only bounded relevant records. Do not hide a negative adjustment because the existing diagnostics previously expected only positive signals. An incorrect report is a prompt for a human to inspect or curate the memory, not an automatic deletion or change of review state.
+
+## Acceptance gates
+
+1. Record, read, update, remove, disable, and re-enable feedback across restart. Preserve other sidecars and base memory bytes for feedback-only mutations.
+2. Reject stale revisions, malformed fields, wrong-project or missing memory IDs, unsafe paths, and serialized bounds without partial changes.
+3. Repeating the same memory/task/reporter upserts rather than accumulates. A 501st distinct record fails without dropping an older record; an existing upsert still succeeds at the cap. User/agent attribution cannot be spoofed through HTTP or MCP, and a newer agent report cannot replace the same task's human signal.
+4. Useful feedback changes only an already matching adaptive candidate by the bounded amount. A negative report produces a visible signed adjustment. Unrelated tasks and empty queries have no effect.
+5. Archived, contested, superseded, zero-hit, graph-only, and foreign-project records remain ineligible for feedback promotion. Legacy output remains unchanged.
+6. Disable and remove restore the baseline score/selection with otherwise identical input. Sources, caution flags, and recorded relationship paths remain intact.
+7. Demonstrate feedback recorded through the local portal, influence in Context Lab and a fresh project-local MCP process, and the same outcome after restart. Verify MCP writes are agent reports, not user reports.
+8. Show the control, outcome attribution, reason, references, timestamps, conflict state, removal, and negative diagnostics in the actual desktop/mobile UI. Keep the terminology consistent in screenshots and documentation.
+
+The release evidence report must record actual outcomes of these gates. No fixed improvement percentage, universal accuracy claim, or automatic truth score is authorized by this plan.

package/docs/launch/RELEASE_ACCEPTANCE_v7.22.0.md

@@ -1,48 +1,48 @@
-# 7.22.0 verification record
-
-Checked on 2026-11-14 against the release candidate. The checks below describe observed behavior and its limits. The [CI workflow](https://github.com/theihtishaam/agents-brain/actions/workflows/ci.yml) separately runs the build, tests, type checks, retrieval diagnostics, dependency audit and fresh-package checks on Ubuntu and Windows with Node 22, 24 and 26.
-
-The final local full-suite run passed **452 tests in 64 files**. Four public-metrics validation tests also passed. The matching commit's CI remains the authority for the complete current revision and its supported-platform package checks.
-
-The fresh-consumer package check passed: archive allowlist and integrity, isolated installation, public exports, CLI, all four skill layouts, MCP resources/prompts, PDF extraction, plaintext memory with evidence and retry identity, checkpoint continuation, context ceilings and byte-exact skill restoration. It also verifies that README images are included in the package.
-
-## Practical outcomes
-
-| User action | Evidence | Result |
-| --- | --- | --- |
-| Save “The cupboard is black” | Real portal HTTP, browser and two already-running independent MCP processes | Both clients retrieve the saved fact for a cupboard question; original line evidence resolves; another project cannot retrieve it. |
-| Retry a note or preserve a correction | Source-intake regressions | Identical notes keep their memory IDs; an earlier approved edit is preserved. |
-| Add PDF, JSON and transcript evidence | Real portal and independent MCP processes | Pending and rejected items stay out of retrieval. Approved records retain page/item locators and original versus edited text. |
-| Continue another agent's work | Real MCP subprocess and portal session tests | A digest-verified checkpoint opens a new linked session; original history and ownership remain intact. |
-| Hide a conversation | Warm-client policy tests | Tools, resources, prompts, direct evidence and inherited handoffs respect exclusions. Explicitly linked memories are filtered before ranking and duplicate collapse. |
-| Change context ceilings | Portal, MCP and project CLI tests | Token and entry ceilings also constrain the reference comparison. Corrupt policy storage fails agent delivery closed. |
-| Disable or remove a generated skill | Store tests and actual browser controls | Verified Project Kit files can be moved, restored or removed; edited and unowned files stay intact. Interrupted operations and abandoned locks are covered. |
-| Inspect live work | Browser and real MCP requests | The graph follows observed exchanges; empty memory stays empty. Hidden/reduced-motion behavior, replay expiry and node search are checked. |
-| Inspect models and usage | Real MCP and HTTP receipts | Missing counters remain unknown. Cache/reasoning subsets are not added twice; retries do not double-count. |
-| Inspect tool and worker details | Browser plus exact-identity regressions | Local logos, separate worker models and effort, shared-host ambiguity, custom client identity, keyboard/touch access, and reduced motion are covered. |
-| Count reporting MCP connections | Two independent owned stdio child processes and store/stream tests | No lease before readiness; clean closure removes it. A hard-killed child's retained lease expires under the tested clock. Disabling tool participation blocks recall while preserving the transport count. Recording off is unavailable. |
-
-## Browser and native integration evidence
-
-- The final graph fixture contains **580 synthetic stored memories**, with **504 displayed nodes and 1,925 recorded relationships** in the captured desktop view. Its three client labels come from scripted MCP clients. Eleven graph browser checks passed with no page errors or external requests.
-- Seven project-control browser checks passed, including keyboard-operated sliders, sharing, roles, tool participation and filtered context. Six managed-skill browser checks passed, including preserving an unrelated file.
-- Eleven additional tool-panel browser checks passed with four initialized scripted MCP stream clients, five registered sessions and two synthetic model receipts. These exercised local logos, hover/focus/click details, distinct worker models and effort, source attribution, event-driven motion, reduced motion, narrow layout and session navigation. No page errors or external requests occurred. Expiry/offline counts and custom-client joins also have focused regressions.
-- The plain-text, source-evidence, session paging and checkpoint paths were exercised in the running app. Native navigation and delayed disconnect responses were tested with controlled browser responses; server protocol tests use a separate owned process fixture.
-- Installed **Codex CLI 0.145.0** completed a real initialize/list/disconnect cycle scoped to a newly created empty test workspace. It returned zero conversations. No personal history was read, created or resumed and no model request was sent. This verifies the handshake and empty indexed list, not personal-history paging or every installed-client variant.
-- Claude Code, OpenCode and DeepSeek Harness imports are tested with supported native export fixtures. These do not establish automatic capture or native-client reconnection. MCP project memory and checkpoints are a separate shared interface.
-
-## Measured local cost
-
-One Windows/Node 24.15.0 fixture measured 30 writes reaching the visible browser: ten MCP memory writes, ten session API writes and ten allowed file changes. Median latency was **241 ms**, p95 **386 ms**, maximum **888 ms**. Over a 60-second idle sample, workspace RSS moved from **82.33 to 82.21 MiB**, server CPU averaged **0.365% of one core**, and the page made **zero workspace API refetches**.
-
-These figures describe a small local fixture on an i5-12450H, not a service-level guarantee, large-corpus benchmark or measurement of the optional native connector. Native metadata refreshes every ten seconds while its view is open; it is separate from local pushed activity.
-
-The added MCP presence lease renews every ten seconds, with a thirty-second expiry. An 11.2-second browser observation containing actual fixture tool exchanges and heartbeats produced four telemetry reads and two presence reads, with zero graph, usage, session or overview reads. Heartbeats update presence independently and do not animate work. This is a targeted request-routing check, not a large-team capacity benchmark.
-
-The 14 author-generated retrieval diagnostics passed for adaptive retrieval with no scoped-data leaks or budget violations. They test named retrieval behaviors, not model answer quality or superiority over other tools. The dependency audit reported no known vulnerabilities at the time of checking.
-
-## Boundaries that remain explicit
-
-This is a local project service. Client labels and coordination roles are not authenticated enterprise identities. The service does not inspect hidden reasoning, train model weights, reopen native application tabs, guarantee every host will request memory, or prove reported outcomes true. Context reduction is estimated; provider billing and model execution time are not inferred from it. Previously delivered information cannot be withdrawn from another application.
-
-Source code, installed-package behavior and UI captures are checked separately. Use the matching commit's CI result when assessing a published release.
+# 7.22.0 verification record
+
+Checked on 2026-11-14 against the release candidate. The checks below describe observed behavior and its limits. The [CI workflow](https://github.com/theihtishaam/agents-brain/actions/workflows/ci.yml) separately runs the build, tests, type checks, retrieval diagnostics, dependency audit and fresh-package checks on Ubuntu and Windows with Node 22, 24 and 26.
+
+The final local full-suite run passed **452 tests in 64 files**. Four public-metrics validation tests also passed. The matching commit's CI remains the authority for the complete current revision and its supported-platform package checks.
+
+The fresh-consumer package check passed: archive allowlist and integrity, isolated installation, public exports, CLI, all four skill layouts, MCP resources/prompts, PDF extraction, plaintext memory with evidence and retry identity, checkpoint continuation, context ceilings and byte-exact skill restoration. It also verifies that README images are included in the package.
+
+## Practical outcomes
+
+| User action | Evidence | Result |
+| --- | --- | --- |
+| Save “The cupboard is black” | Real portal HTTP, browser and two already-running independent MCP processes | Both clients retrieve the saved fact for a cupboard question; original line evidence resolves; another project cannot retrieve it. |
+| Retry a note or preserve a correction | Source-intake regressions | Identical notes keep their memory IDs; an earlier approved edit is preserved. |
+| Add PDF, JSON and transcript evidence | Real portal and independent MCP processes | Pending and rejected items stay out of retrieval. Approved records retain page/item locators and original versus edited text. |
+| Continue another agent's work | Real MCP subprocess and portal session tests | A digest-verified checkpoint opens a new linked session; original history and ownership remain intact. |
+| Hide a conversation | Warm-client policy tests | Tools, resources, prompts, direct evidence and inherited handoffs respect exclusions. Explicitly linked memories are filtered before ranking and duplicate collapse. |
+| Change context ceilings | Portal, MCP and project CLI tests | Token and entry ceilings also constrain the reference comparison. Corrupt policy storage fails agent delivery closed. |
+| Disable or remove a generated skill | Store tests and actual browser controls | Verified Project Kit files can be moved, restored or removed; edited and unowned files stay intact. Interrupted operations and abandoned locks are covered. |
+| Inspect live work | Browser and real MCP requests | The graph follows observed exchanges; empty memory stays empty. Hidden/reduced-motion behavior, replay expiry and node search are checked. |
+| Inspect models and usage | Real MCP and HTTP receipts | Missing counters remain unknown. Cache/reasoning subsets are not added twice; retries do not double-count. |
+| Inspect tool and worker details | Browser plus exact-identity regressions | Local logos, separate worker models and effort, shared-host ambiguity, custom client identity, keyboard/touch access, and reduced motion are covered. |
+| Count reporting MCP connections | Two independent owned stdio child processes and store/stream tests | No lease before readiness; clean closure removes it. A hard-killed child's retained lease expires under the tested clock. Disabling tool participation blocks recall while preserving the transport count. Recording off is unavailable. |
+
+## Browser and native integration evidence
+
+- The final graph fixture contains **580 synthetic stored memories**, with **504 displayed nodes and 1,925 recorded relationships** in the captured desktop view. Its three client labels come from scripted MCP clients. Eleven graph browser checks passed with no page errors or external requests.
+- Seven project-control browser checks passed, including keyboard-operated sliders, sharing, roles, tool participation and filtered context. Six managed-skill browser checks passed, including preserving an unrelated file.
+- Eleven additional tool-panel browser checks passed with four initialized scripted MCP stream clients, five registered sessions and two synthetic model receipts. These exercised local logos, hover/focus/click details, distinct worker models and effort, source attribution, event-driven motion, reduced motion, narrow layout and session navigation. No page errors or external requests occurred. Expiry/offline counts and custom-client joins also have focused regressions.
+- The plain-text, source-evidence, session paging and checkpoint paths were exercised in the running app. Native navigation and delayed disconnect responses were tested with controlled browser responses; server protocol tests use a separate owned process fixture.
+- Installed **Codex CLI 0.145.0** completed a real initialize/list/disconnect cycle scoped to a newly created empty test workspace. It returned zero conversations. No personal history was read, created or resumed and no model request was sent. This verifies the handshake and empty indexed list, not personal-history paging or every installed-client variant.
+- Claude Code, OpenCode and DeepSeek Harness imports are tested with supported native export fixtures. These do not establish automatic capture or native-client reconnection. MCP project memory and checkpoints are a separate shared interface.
+
+## Measured local cost
+
+One Windows/Node 24.15.0 fixture measured 30 writes reaching the visible browser: ten MCP memory writes, ten session API writes and ten allowed file changes. Median latency was **241 ms**, p95 **386 ms**, maximum **888 ms**. Over a 60-second idle sample, workspace RSS moved from **82.33 to 82.21 MiB**, server CPU averaged **0.365% of one core**, and the page made **zero workspace API refetches**.
+
+These figures describe a small local fixture on an i5-12450H, not a service-level guarantee, large-corpus benchmark or measurement of the optional native connector. Native metadata refreshes every ten seconds while its view is open; it is separate from local pushed activity.
+
+The added MCP presence lease renews every ten seconds, with a thirty-second expiry. An 11.2-second browser observation containing actual fixture tool exchanges and heartbeats produced four telemetry reads and two presence reads, with zero graph, usage, session or overview reads. Heartbeats update presence independently and do not animate work. This is a targeted request-routing check, not a large-team capacity benchmark.
+
+The 14 author-generated retrieval diagnostics passed for adaptive retrieval with no scoped-data leaks or budget violations. They test named retrieval behaviors, not model answer quality or superiority over other tools. The dependency audit reported no known vulnerabilities at the time of checking.
+
+## Boundaries that remain explicit
+
+This is a local project service. Client labels and coordination roles are not authenticated enterprise identities. The service does not inspect hidden reasoning, train model weights, reopen native application tabs, guarantee every host will request memory, or prove reported outcomes true. Context reduction is estimated; provider billing and model execution time are not inferred from it. Previously delivered information cannot be withdrawn from another application.
+
+Source code, installed-package behavior and UI captures are checked separately. Use the matching commit's CI result when assessing a published release.

package/docs/launch/RELEASE_CHECKLIST_v7.0.0.md

@@ -1,24 +1,24 @@
-# 7.0.0 release checklist
-
-## Build and behavior
-
-- Confirm package.json, lockfile root, CLI, update checker, MCP metadata, dashboard, README, and release notes agree on 7.0.0.
-- Run `npm ci --ignore-scripts` from a clean checkout, then `npm run verify` and `npm run lint`.
-- Verify independent-process writes survive, queued success follows persistence, failed changes remain retryable, external deletions are preserved, and invalid stores remain byte-for-byte unchanged.
-- Verify unrelated agent notes cannot boost corroboration and every score is finite and explained.
-- Run `npm audit --audit-level=high`; record counts with the validation date.
-- Run `npm run test:package`; it packs the build, installs into a fresh temporary consumer, imports the public API, tests both new CLI commands, and verifies configuration isolation.
-
-## Publish the reviewed artifact
-
-- Keep the original 6.3.0 tarball and exact source commit available for rollback comparison.
-- Review `npm pack --dry-run --json` and allowlisted contents. Exclude personal state, node_modules, tests, temporary outputs, and configuration files.
-- Commit the reviewed source and lockfile; push without rewriting existing remote history.
-- Pack once, compute SHA-512/integrity, and publish that exact tarball with `npm publish <tarball> --access public --ignore-scripts` after local npm login by its owner.
-- If npm requests browser authentication or a second factor, the user completes it directly. Never put authentication material into scripts, output, or chat.
-- Verify registry 7.0.0 and `latest`, package integrity, and a fresh downloaded tarball. Publish the matching GitHub tag/release and attach the verified package.
-- Confirm remote CI separately. Do not describe unrun OS/runtime combinations as tested.
-
-## Rollback
-
-Use the preserved pre-upgrade store backup and install the previous package version if required. Stop all writers before restoring data. Published npm versions cannot be overwritten; release a corrective patch rather than silently replacing 7.0.0. Do not unpublish or move the latest tag without an explicit rollback decision.
+# 7.0.0 release checklist
+
+## Build and behavior
+
+- Confirm package.json, lockfile root, CLI, update checker, MCP metadata, dashboard, README, and release notes agree on 7.0.0.
+- Run `npm ci --ignore-scripts` from a clean checkout, then `npm run verify` and `npm run lint`.
+- Verify independent-process writes survive, queued success follows persistence, failed changes remain retryable, external deletions are preserved, and invalid stores remain byte-for-byte unchanged.
+- Verify unrelated agent notes cannot boost corroboration and every score is finite and explained.
+- Run `npm audit --audit-level=high`; record counts with the validation date.
+- Run `npm run test:package`; it packs the build, installs into a fresh temporary consumer, imports the public API, tests both new CLI commands, and verifies configuration isolation.
+
+## Publish the reviewed artifact
+
+- Keep the original 6.3.0 tarball and exact source commit available for rollback comparison.
+- Review `npm pack --dry-run --json` and allowlisted contents. Exclude personal state, node_modules, tests, temporary outputs, and configuration files.
+- Commit the reviewed source and lockfile; push without rewriting existing remote history.
+- Pack once, compute SHA-512/integrity, and publish that exact tarball with `npm publish <tarball> --access public --ignore-scripts` after local npm login by its owner.
+- If npm requests browser authentication or a second factor, the user completes it directly. Never put authentication material into scripts, output, or chat.
+- Verify registry 7.0.0 and `latest`, package integrity, and a fresh downloaded tarball. Publish the matching GitHub tag/release and attach the verified package.
+- Confirm remote CI separately. Do not describe unrun OS/runtime combinations as tested.
+
+## Rollback
+
+Use the preserved pre-upgrade store backup and install the previous package version if required. Stop all writers before restoring data. Published npm versions cannot be overwritten; release a corrective patch rather than silently replacing 7.0.0. Do not unpublish or move the latest tag without an explicit rollback decision.

package/docs/launch/RELEASE_NOTES_v7.0.0.md

@@ -1,44 +1,44 @@
-# Agent Shadow Brain 7.0.0
-
-Release date: 2026-11-11. Development used Astra for planning/review and GPT-6.1 SoL for core implementation. These are development roles, not newly bundled AI model services.
-
-## What changed
-
-Concurrent agents now serialize memory commits and merge their pending additions, access changes, and registrations with the latest valid disk snapshot. Successful queued-write acknowledgements follow persistence. Failed changes remain pending for retry. Corrupt or future-schema stores produce explicit errors while preserving the original bytes.
-
-Scored recall ranks the full matching pool, reports matched keywords and supporting agent identities, uses creation-age recency, and handles malformed numeric values without emitting NaN. Corroboration requires matching normalized content in the same project and category. Repeated text from different agent identities is a heuristic; it does not establish independent fact checking.
-
-New CLI commands:
-
-```sh
-shadow-brain storage-health --json
-shadow-brain storage-health --db ./global.json --json
-shadow-brain recall-explain "release verification" --limit 5
-```
-
-The MCP `global_storage_health` tool exposes the active process's pending operations and latest storage error without starting or flushing a store. Existing `global_recall_scored` results include explanations. The library entry point exports GlobalBrain and associated types.
-
-Installation no longer runs automatic agent setup. CLI help, version, storage-health, and recall-explain do not load provider settings. Dashboard activity rows escape memory text. Diagnostic output no longer prints key fragments. Dependencies are updated and promotional automation is manual-only.
-
-## Compatibility and migration
-
-- Supported runtimes: Node 22.12+ within 22.x, 24.x, or 26+.
-- Back up the store and stop older writers before upgrade. The new protocol cannot coordinate with an old writer that ignores its lock.
-- Store schema remains version 1. Invalid stores must be repaired or restored explicitly; automatic reset is removed.
-- `writeSync` stages an in-memory change. Use `await sync()` for persistence. A queued `write()` resolves after synchronization. A false result means queue rejection or failed persistence; accepted failed operations remain retryable.
-- Recalls use the current process snapshot; a sync refreshes external changes. There is no instantaneous cross-process notification guarantee.
-- Lock waits are bounded (default five seconds, configurable with `lockTimeoutMs`). Locks are never removed merely because they are old. After an interrupted process, inspect the writer and store before manually removing an abandoned `.lock` file.
-- Atomic replacement protects against partial JSON visibility. This release does not claim power-loss durability on every filesystem or safe coordination on all network filesystems.
-- Scores are heuristic rankings. Revisit application-specific `minConfidence` thresholds.
-- New health timestamps refer to the current process, not a persisted lifetime history.
-- Dependency major upgrades can affect applications importing re-exported Zod APIs; consult the upstream Zod 4 and simple-git 4 migration notes.
-
-## Source provenance
-
-The original repository URL returned 404 during this upgrade. The source was recovered from public fork `shadrackohemeng/agent-shadow-brain` at commit `bec756e19647a11cad570f8ae3c363792de84856`, exactly matching npm 6.3.0's `gitHead`. The downloaded 6.3.0 tarball is retained separately as the comparison baseline. Original MIT licensing and history are preserved.
-
-## Validation
-
-The release gate requires type-check/build, full tests, cross-process storage regressions, npm audit, fresh-consumer tarball installation, CLI/library smoke checks, package-content review, and Astra review. Remote CI results and publication status are recorded separately; prepared artifacts are not evidence of publication.
-
-Upstream references: [Vitest migration](https://main.vitest.dev/guide/migration/), [simple-git changelog](https://github.com/steveukx/git-js/blob/main/simple-git/CHANGELOG.md), [Zod migration](https://zod.dev/v4/changelog).
+# Agent Shadow Brain 7.0.0
+
+Release date: 2026-11-11. Development used Astra for planning/review and GPT-6.1 SoL for core implementation. These are development roles, not newly bundled AI model services.
+
+## What changed
+
+Concurrent agents now serialize memory commits and merge their pending additions, access changes, and registrations with the latest valid disk snapshot. Successful queued-write acknowledgements follow persistence. Failed changes remain pending for retry. Corrupt or future-schema stores produce explicit errors while preserving the original bytes.
+
+Scored recall ranks the full matching pool, reports matched keywords and supporting agent identities, uses creation-age recency, and handles malformed numeric values without emitting NaN. Corroboration requires matching normalized content in the same project and category. Repeated text from different agent identities is a heuristic; it does not establish independent fact checking.
+
+New CLI commands:
+
+```sh
+shadow-brain storage-health --json
+shadow-brain storage-health --db ./global.json --json
+shadow-brain recall-explain "release verification" --limit 5
+```
+
+The MCP `global_storage_health` tool exposes the active process's pending operations and latest storage error without starting or flushing a store. Existing `global_recall_scored` results include explanations. The library entry point exports GlobalBrain and associated types.
+
+Installation no longer runs automatic agent setup. CLI help, version, storage-health, and recall-explain do not load provider settings. Dashboard activity rows escape memory text. Diagnostic output no longer prints key fragments. Dependencies are updated and promotional automation is manual-only.
+
+## Compatibility and migration
+
+- Supported runtimes: Node 22.12+ within 22.x, 24.x, or 26+.
+- Back up the store and stop older writers before upgrade. The new protocol cannot coordinate with an old writer that ignores its lock.
+- Store schema remains version 1. Invalid stores must be repaired or restored explicitly; automatic reset is removed.
+- `writeSync` stages an in-memory change. Use `await sync()` for persistence. A queued `write()` resolves after synchronization. A false result means queue rejection or failed persistence; accepted failed operations remain retryable.
+- Recalls use the current process snapshot; a sync refreshes external changes. There is no instantaneous cross-process notification guarantee.
+- Lock waits are bounded (default five seconds, configurable with `lockTimeoutMs`). Locks are never removed merely because they are old. After an interrupted process, inspect the writer and store before manually removing an abandoned `.lock` file.
+- Atomic replacement protects against partial JSON visibility. This release does not claim power-loss durability on every filesystem or safe coordination on all network filesystems.
+- Scores are heuristic rankings. Revisit application-specific `minConfidence` thresholds.
+- New health timestamps refer to the current process, not a persisted lifetime history.
+- Dependency major upgrades can affect applications importing re-exported Zod APIs; consult the upstream Zod 4 and simple-git 4 migration notes.
+
+## Source provenance
+
+The original repository URL returned 404 during this upgrade. The source was recovered from public fork `shadrackohemeng/agent-shadow-brain` at commit `bec756e19647a11cad570f8ae3c363792de84856`, exactly matching npm 6.3.0's `gitHead`. The downloaded 6.3.0 tarball is retained separately as the comparison baseline. Original MIT licensing and history are preserved.
+
+## Validation
+
+The release gate requires type-check/build, full tests, cross-process storage regressions, npm audit, fresh-consumer tarball installation, CLI/library smoke checks, package-content review, and Astra review. Remote CI results and publication status are recorded separately; prepared artifacts are not evidence of publication.
+
+Upstream references: [Vitest migration](https://main.vitest.dev/guide/migration/), [simple-git changelog](https://github.com/steveukx/git-js/blob/main/simple-git/CHANGELOG.md), [Zod migration](https://zod.dev/v4/changelog).

package/docs/launch/RELEASE_NOTES_v7.1.0.md

@@ -1,32 +1,32 @@
-# Agent Shadow Brain 7.1.0
-
-This release adds focused task guidance and project skill installation on top of 7.0.0's durable memory and explained recall.
-
-## Changes
-
-- Six bundled skills: workflow selection, implementation, debugging, review, research, and release.
-- Project skill layouts for Codex, Claude Code, OpenCode, and DeepSeek Harness; portable files for other compatible clients.
-- Preview-first installation that preserves project instruction text, detects local edits, validates destinations and stale plans, records ownership, and backs up managed updates.
-- CLI skill catalog/install commands and advisory request analysis with explicit overrides.
-- Read-only MCP guidance tools and public library functions/types.
-
-The intended workflow is understand, plan when useful, execute authorized work, and verify. A small question stays a small answer. Plan-only, diagnosis-only, and review-only instructions keep their scope. No provider/model setup, credentials, new runtime dependencies, or global configuration changes are required.
-
-## Start
-
-```bash
-npm install -g @theihtisham/agent-shadow-brain@7.1.0
-# Run in the project root:
-shadow-brain skills install . --target codex
-shadow-brain skills install . --target codex --apply
-```
-
-Choose `claude-code`, `opencode`, `deepseek-harness`, `portable`, or `all` instead as appropriate. See the [integration guide](../WORKFLOW_INTEGRATION.md) for host requirements, updates, conflicts, and examples.
-
-## Verification and limits
-
-The release gate covers TypeScript, regression tests, installer preservation/failure scenarios, representative task-routing scenarios, skill frontmatter validation, and an installed npm tarball in a clean consumer project. CI runs on Windows and Linux with Node 22, 24, and 26. Final run counts and publication evidence are recorded in the release report.
-
-The router is a deterministic English-language heuristic; host interpretation and explicit options handle ambiguity. The package provides guidance, not autonomous task execution or authorization. Documented host layouts and automated installation tests do not prove that a running host discovered or followed a skill. DeepSeek Harness needs its skill/context plugins enabled.
-
-This is an additive 7.x release. No memory-store schema migration is introduced; retain the 7.0.0 upgrade guidance when coming from 6.x.
+# Agent Shadow Brain 7.1.0
+
+This release adds focused task guidance and project skill installation on top of 7.0.0's durable memory and explained recall.
+
+## Changes
+
+- Six bundled skills: workflow selection, implementation, debugging, review, research, and release.
+- Project skill layouts for Codex, Claude Code, OpenCode, and DeepSeek Harness; portable files for other compatible clients.
+- Preview-first installation that preserves project instruction text, detects local edits, validates destinations and stale plans, records ownership, and backs up managed updates.
+- CLI skill catalog/install commands and advisory request analysis with explicit overrides.
+- Read-only MCP guidance tools and public library functions/types.
+
+The intended workflow is understand, plan when useful, execute authorized work, and verify. A small question stays a small answer. Plan-only, diagnosis-only, and review-only instructions keep their scope. No provider/model setup, credentials, new runtime dependencies, or global configuration changes are required.
+
+## Start
+
+```bash
+npm install -g @theihtisham/agent-shadow-brain@7.1.0
+# Run in the project root:
+shadow-brain skills install . --target codex
+shadow-brain skills install . --target codex --apply
+```
+
+Choose `claude-code`, `opencode`, `deepseek-harness`, `portable`, or `all` instead as appropriate. See the [integration guide](../WORKFLOW_INTEGRATION.md) for host requirements, updates, conflicts, and examples.
+
+## Verification and limits
+
+The release gate covers TypeScript, regression tests, installer preservation/failure scenarios, representative task-routing scenarios, skill frontmatter validation, and an installed npm tarball in a clean consumer project. CI runs on Windows and Linux with Node 22, 24, and 26. Final run counts and publication evidence are recorded in the release report.
+
+The router is a deterministic English-language heuristic; host interpretation and explicit options handle ambiguity. The package provides guidance, not autonomous task execution or authorization. Documented host layouts and automated installation tests do not prove that a running host discovered or followed a skill. DeepSeek Harness needs its skill/context plugins enabled.
+
+This is an additive 7.x release. No memory-store schema migration is introduced; retain the 7.0.0 upgrade guidance when coming from 6.x.

package/docs/launch/RELEASE_NOTES_v7.1.3.md

@@ -1,40 +1,40 @@
-# Agent Shadow Brain 7.1.3
-
-Version 7.1.3 connects memory review, the workspace graph, and the context handed to an agent. The new live operations portal shows recorded agent activity and tool timing.
-
-## Live operations
-
-Open `/live` on the dashboard address for the session list, activity network, charts, and event timeline. Measured activity comes from the local MCP service. Hosts can explicitly report task phases and tool spans. The portal labels the two sources and uses matched, measured calls for timing metrics.
-
-The shared local journal keeps the latest 500 metadata events. It tracks sequence and journal identity so readers can continue from a cursor and detect gaps or a restarted journal. `activityRecording` controls new records and `liveActivity` controls visibility. Both are enabled by default and can be changed with the other three runtime controls. Use `activity report` to send a host report and `activity tail` to inspect the journal.
-
-## Memory review and relations
-
-Open a memory in the workspace to see its content, recorded references, current review, and history. Set its state to active, archived, or contested. Record a same-project link of type related, supports, contradicts, or supersedes. Supersession links point from the replacement to the older memory.
-
-Context assembly filters inactive memories before ranking, preserves relevant relation and source provenance when collapsing duplicates, and labels recorded contradictions. If a replacement disappears, its older memory stays superseded until you remove the relation. Manual reviews and links record decisions to inspect against the underlying evidence.
-
-The `curate show`, `curate review`, `curate link`, and `curate unlink` commands use the same annotation store as the workspace. The store validates project identities, revisions, duplicate relations, and supersession cycles. It keeps an audit trail alongside the existing memory store.
-
-## Connect a client
-
-The workspace's Integrations view shows project skill-file presence, supported client capabilities, and local runtime and storage checks. Codex, Claude Code, OpenCode, and DeepSeek Harness can use their documented project skill layouts. Host-side discovery depends on client configuration.
-
-The standalone MCP service now runs over standard input and output.
-
-```bash
-shadow-brain mcp --stdio
-```
-
-Configure this command as the executable and arguments in a compatible client. The service exposes nine read-only memory, context, and workflow tools plus the explicit `activity_report` write tool. Activity recording uses a separate journal from the memory store. DeepSeek Harness needs its MCP client and filesystem skill plugins enabled. See the [workspace guide](../WORKSPACE.md) and [skill integration guide](../WORKFLOW_INTEGRATION.md).
-
-## Upgrade
-
-```bash
-npm install -g @theihtisham/agent-shadow-brain@7.1.3
-shadow-brain dash . --no-analysis
-```
-
-Existing memories retain schema version 1. Keep `global.json` and the separate `memory-annotations.json` when backing up your memory and review state. Follow the [7.0 migration notes](RELEASE_NOTES_v7.0.0.md) if you are upgrading from 6.x.
-
-This upgrade uses the maintainer-requested version **7.1.3**, published after 7.2.0. It is assigned the npm `latest` tag, but semver update tools may still prefer 7.2.0. Use the exact install command above.
+# Agent Shadow Brain 7.1.3
+
+Version 7.1.3 connects memory review, the workspace graph, and the context handed to an agent. The new live operations portal shows recorded agent activity and tool timing.
+
+## Live operations
+
+Open `/live` on the dashboard address for the session list, activity network, charts, and event timeline. Measured activity comes from the local MCP service. Hosts can explicitly report task phases and tool spans. The portal labels the two sources and uses matched, measured calls for timing metrics.
+
+The shared local journal keeps the latest 500 metadata events. It tracks sequence and journal identity so readers can continue from a cursor and detect gaps or a restarted journal. `activityRecording` controls new records and `liveActivity` controls visibility. Both are enabled by default and can be changed with the other three runtime controls. Use `activity report` to send a host report and `activity tail` to inspect the journal.
+
+## Memory review and relations
+
+Open a memory in the workspace to see its content, recorded references, current review, and history. Set its state to active, archived, or contested. Record a same-project link of type related, supports, contradicts, or supersedes. Supersession links point from the replacement to the older memory.
+
+Context assembly filters inactive memories before ranking, preserves relevant relation and source provenance when collapsing duplicates, and labels recorded contradictions. If a replacement disappears, its older memory stays superseded until you remove the relation. Manual reviews and links record decisions to inspect against the underlying evidence.
+
+The `curate show`, `curate review`, `curate link`, and `curate unlink` commands use the same annotation store as the workspace. The store validates project identities, revisions, duplicate relations, and supersession cycles. It keeps an audit trail alongside the existing memory store.
+
+## Connect a client
+
+The workspace's Integrations view shows project skill-file presence, supported client capabilities, and local runtime and storage checks. Codex, Claude Code, OpenCode, and DeepSeek Harness can use their documented project skill layouts. Host-side discovery depends on client configuration.
+
+The standalone MCP service now runs over standard input and output.
+
+```bash
+shadow-brain mcp --stdio
+```
+
+Configure this command as the executable and arguments in a compatible client. The service exposes nine read-only memory, context, and workflow tools plus the explicit `activity_report` write tool. Activity recording uses a separate journal from the memory store. DeepSeek Harness needs its MCP client and filesystem skill plugins enabled. See the [workspace guide](../WORKSPACE.md) and [skill integration guide](../WORKFLOW_INTEGRATION.md).
+
+## Upgrade
+
+```bash
+npm install -g @theihtisham/agent-shadow-brain@7.1.3
+shadow-brain dash . --no-analysis
+```
+
+Existing memories retain schema version 1. Keep `global.json` and the separate `memory-annotations.json` when backing up your memory and review state. Follow the [7.0 migration notes](RELEASE_NOTES_v7.0.0.md) if you are upgrading from 6.x.
+
+This upgrade uses the maintainer-requested version **7.1.3**, published after 7.2.0. It is assigned the npm `latest` tag, but semver update tools may still prefer 7.2.0. Use the exact install command above.