@theihtisham/agent-shadow-brain 7.1.0 → 7.1.4

package/docs/evaluation/CONTEXT_EVALUATION_v7.1.4.md

@@ -0,0 +1,36 @@
+# Agent Shadow Brain 7.1.4 context evaluation
+
+Paired runs used the same author-generated corpus and options for each case. Each profile assembled context from the compiled package after its isolated JSON store had loaded.
+
+| Profile | Cases passed | Context recall@5 | Context MRR@5 | Scope leaks | Budget violations | Median assembly |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| legacy | 6 / 14 | 0.679 | 0.731 | 0 / 1 | 0 | 0.225 ms |
+| adaptive | 14 / 14 | 1.000 | 1.000 | 0 / 1 | 0 | 0.756 ms |
+
+| Fixture | Records | Legacy checks | Adaptive checks |
+| --- | ---: | --- | --- |
+| Exact lexical control | 2 | Pass | Pass |
+| No lexical evidence | 1 | Pass | Pass |
+| Exact Java match and metadata boundary | 3 | excludes forbidden IDs, ranks expected record first | Pass |
+| Late identifier remains visible in the excerpt | 1 | shows expected passage in the excerpt | Pass |
+| Exact duplicates leave room for a distinct checksum lesson | 205 | includes relevant IDs, preserves reference and original memory ID | Pass |
+| Whole camelCase query matches snake_case | 2 | includes relevant IDs, ranks expected record first | Pass |
+| Whole snake_case query matches PascalCase | 2 | includes relevant IDs, ranks expected record first | Pass |
+| Relative query matches a recorded Windows source reference | 2 | excludes forbidden IDs | Pass |
+| Unicode text and code punctuation | 2 | Pass | Pass |
+| Cross-project setting alone preserves project scope | 2 | Pass | Pass |
+| Both cross-project gates permit labeled origins | 2 | Pass | Pass |
+| Archived, contested, and superseded states remain excluded | 4 | Pass | Pass |
+| Recorded links stop at one hop and preserve contradiction caution | 6 | includes relevant IDs | Pass |
+| Tight Unicode and code budget still shows the matched identifier | 1 | includes relevant IDs, shows expected passage in the excerpt | Pass |
+
+Runtime used v24.15.0 on win32/x64. Each case has one warm-store assembly measurement per profile. The first profile alternates by case.
+
+Recall and reciprocal rank use the first 5 selected context entries and explicit relevant IDs. The no-evidence case is evaluated as abstention. Candidate explanations and the new estimate method are checked only where the adaptive profile provides them.
+
+- The author-generated fixtures target named behaviors and do not measure model answer quality or competitor performance.
+- Token counts are profile-specific estimates and may differ from a receiving model’s tokenizer.
+- Timing covers context assembly after loading each store and excludes initialization, packaging, UI, and model calls.
+- Lexical variants and recorded links do not provide general semantic paraphrase retrieval or factual verification.
+
+Run npm run build followed by node tools/evaluate-context.mjs to reproduce the paired JSON results.

package/docs/launch/COMPONENT_MAP_v7.1.4.md

@@ -0,0 +1,307 @@
+# Component map for 7.1.4
+
+Prepared 2026-11-12 from the repository's source. This map explains the selected release architecture and inventories retained code. **A source file's presence is not a claim that its feature is enabled, integrated into the default workflow, or independently verified.** Final verification belongs in the release evidence report.
+
+## The everyday workflow
+
+```mermaid
+flowchart LR
+  A[Agent or user] --> B[MCP, CLI, or local workspace]
+  B --> C[Explicit project and task]
+  C --> D[Memory snapshot]
+  E[Reviews and recorded relations] --> F[Eligible memories]
+  D --> F
+  F --> G[Legacy or adaptive retrieval]
+  G --> H[Bounded context and reasons]
+  H --> I[Inspect and compare]
+  I --> J[Copy context or selected handoff prompt]
+  J --> A
+  I --> K[Explicit revision-checked review]
+  K --> E
+  B --> L[Measured calls or reported phases]
+  L --> M[Bounded activity journal]
+  M --> N[Live view and recorded replay]
+```
+
+The arrows describe data flow. They do not imply that every agent is connected, every tool call is captured, or copied context has been consumed by a model.
+
+## Main components and responsibilities
+
+| Component | Purpose | Boundary |
+| --- | --- | --- |
+| Global memory store | Persist memory records, project/agent identities, storage health, and recorded use | Schema version 1; atomic writes and bounded store policies |
+| Annotation store | Persist reviews, recorded relation types, revisions, and audit history | Explicit review operations; does not verify truth |
+| Feature settings | Persist five actual runtime controls | Validated fields and revisions; separate from provider configuration |
+| Legacy recall | Keep established substring/ranking behavior available | Ranking is heuristic; legacy compatibility is intentional |
+| Adaptive retrieval | Improve technical matching, duplicate handling, excerpts, and bounded recorded-link expansion | Explicit profile; no embeddings or provider call required |
+| Context assembler | Apply scope, curation, selection, exclusions, rendering, and output bounds | Stored text is reference material; sources are not opened |
+| Memory health | Present scoped counts and actionable review signals | Missing sources, age, and unreviewed status are not truth judgments |
+| Subconscious briefing | Supply existing session-start context behavior | Automatic-briefing control applies; profile differences must be documented |
+| Workspace API | Validate requests and expose shared results to the local UI | Same scope/review semantics as CLI and MCP; inspections remain read-only |
+| Workspace UI | Inspect memory, graph relations, attention queue, context, and integrations | Shows recorded evidence and actual results; does not infer connections |
+| MCP stdio | Expose memory/context/workflow tools, resources, and selected prompts | Client capability determines which surfaces are available |
+| CLI | Run context, curation, activity, workflow, skill, and diagnostic operations | Explicit flags select new behavior; old commands remain |
+| Workflow skills | Give clients focused procedures for selecting, implementing, debugging, reviewing, researching, and releasing work | Installing files does not prove host discovery or execution |
+| Client recipes/diagnostics | Produce configuration snippets and inspect managed project skill-file presence | No personal profiles, credentials, or session data are read |
+| Activity reporting | Record measured MCP calls and explicitly reported phases/spans | Records bounded metadata, not model thoughts or a complete host trace |
+| Durable activity journal | Persist the latest bounded events with sequence and journal identity | Readers can detect gaps and restarts |
+| Live portal | Show sessions, events, networks, timing, and recorded playback | A replay is historical; measured and reported events remain distinct |
+| Isolated workspace demo | Serve the real UI with synthetic records and scripted local calls through `demo workspace` | Separate temporary store; no client discovery or personal provider configuration |
+| Project Kit (added scope) | Inspect a chosen project's stack evidence, save explicit local knowledge, and preview/apply a requirement-specific skill | Persistent project store and project skill roots; no automatic source ingestion, global installation, or overwrite of user edits; implementation acceptance pending |
+| Project feedback (added scope) | Persist attributed task outcomes and make bounded, reversible adjustments to relevant adaptive candidates | Project-only sidecar; reported evidence, no model training, truth verification, automatic curation, or global influence; implementation acceptance pending |
+| Package/library exports | Supply CLI binaries and public TypeScript/JavaScript entry points | Verify the packed artifact in a fresh consumer |
+
+## Persistent project workflow
+
+`project workspace` creates an independent memory service pinned to the selected directory. `project-memory.ts` supplies canonical store paths and explicit knowledge writes. `project-kit-inspection.ts` extracts bounded observed markers; `project-kit-paths.ts` checks roots, links, and bounded reads; `project-kit.ts` produces requirement-specific previews and protects applied files with ownership receipts. `project-feedback.ts` owns local outcome persistence and relevance adjustments. The portal, CLI, and MCP use these shared services.
+
+Knowledge and outcomes persist under `.shadow-brain` in the selected project. Generated skill files use the selected client's project skill directory. The local portal must not consume another store's process-wide activity feed. Its MCP recipe includes the exact database and project identity. This persistent workflow is separate from the disposable `demo workspace` tour.
+
+The project learning flag is a local feedback-store control, separate from the five global feature controls below. Its meaning is whether reported outcomes influence adaptive retrieval; switching it off retains the reports. See the [Project Kit plan](PROJECT_KIT_PLAN_v7.1.4.md) and [learning plan](PROJECT_LEARNING_PLAN_v7.1.4.md) for acceptance gates.
+
+## Controls and their effects
+
+| Control | Default | Effect |
+| --- | --- | --- |
+| Context assembly | On | Allows the shared context pack path; disabled requests return before recall |
+| Cross-project context | Off | Permits broader scope only together with an explicit request |
+| Automatic briefing | On | Allows the existing session-start briefing path |
+| Live dashboard activity | On | Allows activity to be shown/refreshed in the dashboard |
+| Record agent activity | On | Allows new bounded activity-journal records |
+
+Visibility and recording are different. Disabling visibility does not erase recorded events. Per-request retrieval profile and relation expansion are request options, not extra persisted global switches.
+
+## What a connection proves
+
+| Observation | What it establishes |
+| --- | --- |
+| Client appears in capability list | A documented recipe or supported layout exists |
+| Skill file is present | The managed project file exists at the inspected path |
+| MCP handshake and tool list succeed | That process can speak the advertised protocol |
+| Host reports a phase | The host explicitly submitted that metadata |
+| Server measures a tool call | The local server observed that call and its timing |
+| User sees a completed host interaction | That particular client workflow operated end to end |
+
+Do not collapse these observations into an unqualified green “connected” badge. Prompts, resources, and tools have different support across clients.
+
+## Retained advanced code
+
+The repository also exports or retains analyzers, memory experiments, team/swarm concepts, graph algorithms, portability, dashboards, speech/visual experiments, and legacy continuity paths. These remain available according to their existing entry points and configuration. Their names are not evidence of general intelligence, autonomous learning, formal correctness, or complete integration with adaptive context.
+
+The `src/index.ts` export surface and CLI/server entry points are the authoritative starting points for checking accessibility. The source inventory below makes every module discoverable without expanding the README into a feature catalogue. Refer to focused tests and release evidence before making a stronger capability claim.
+
+## Source inventory
+
+This inventory is generated from source filenames. It classifies location, not verification status. New 7.1.4 files should be included again when the final package is prepared.
+
+
+### src
+
+- [project-cli.ts](../../src/project-cli.ts)
+
+- [activity-cli.ts](../../src/activity-cli.ts)
+- [cli.ts](../../src/cli.ts)
+- [context-cli.ts](../../src/context-cli.ts)
+- [curation-cli.ts](../../src/curation-cli.ts)
+- [index.ts](../../src/index.ts)
+- [integration-cli.ts](../../src/integration-cli.ts)
+- [types.ts](../../src/types.ts)
+- [workflow-cli.ts](../../src/workflow-cli.ts)
+
+### src/brain
+
+- [project-feedback.ts](../../src/brain/project-feedback.ts)
+- [project-kit.ts](../../src/brain/project-kit.ts)
+- [project-kit-inspection.ts](../../src/brain/project-kit-inspection.ts)
+- [project-kit-paths.ts](../../src/brain/project-kit-paths.ts)
+- [project-memory.ts](../../src/brain/project-memory.ts)
+
+- [accessibility-checker.ts](../../src/brain/accessibility-checker.ts)
+- [activity-journal.ts](../../src/brain/activity-journal.ts)
+- [activity-reporting.ts](../../src/brain/activity-reporting.ts)
+- [adr-engine.ts](../../src/brain/adr-engine.ts)
+- [adversarial-defense.ts](../../src/brain/adversarial-defense.ts)
+- [agent-firewall.ts](../../src/brain/agent-firewall.ts)
+- [agent-handoff.ts](../../src/brain/agent-handoff.ts)
+- [air-gap.ts](../../src/brain/air-gap.ts)
+- [analyzer.ts](../../src/brain/analyzer.ts)
+- [api-contract-analyzer.ts](../../src/brain/api-contract-analyzer.ts)
+- [ast-analyzer.ts](../../src/brain/ast-analyzer.ts)
+- [attention-heatmap.ts](../../src/brain/attention-heatmap.ts)
+- [auto-setup.ts](../../src/brain/auto-setup.ts)
+- [auto-update.ts](../../src/brain/auto-update.ts)
+- [brain-3d.ts](../../src/brain/brain-3d.ts)
+- [brain-active-learner.ts](../../src/brain/brain-active-learner.ts)
+- [brain-ascii.ts](../../src/brain/brain-ascii.ts)
+- [brain-bus.ts](../../src/brain/brain-bus.ts)
+- [brain-chat.ts](../../src/brain/brain-chat.ts)
+- [brain-cinema.ts](../../src/brain/brain-cinema.ts)
+- [brain-coach.ts](../../src/brain/brain-coach.ts)
+- [brain-consolidator.ts](../../src/brain/brain-consolidator.ts)
+- [brain-contradictions.ts](../../src/brain/brain-contradictions.ts)
+- [brain-diff.ts](../../src/brain/brain-diff.ts)
+- [brain-dna.ts](../../src/brain/brain-dna.ts)
+- [brain-doppelganger.ts](../../src/brain/brain-doppelganger.ts)
+- [brain-encryption.ts](../../src/brain/brain-encryption.ts)
+- [brain-exchange.ts](../../src/brain/brain-exchange.ts)
+- [brain-garden.ts](../../src/brain/brain-garden.ts)
+- [brain-graph-walker.ts](../../src/brain/brain-graph-walker.ts)
+- [brain-holiday-card.ts](../../src/brain/brain-holiday-card.ts)
+- [brain-memes.ts](../../src/brain/brain-memes.ts)
+- [brain-memory-tiers.ts](../../src/brain/brain-memory-tiers.ts)
+- [brain-notebook.ts](../../src/brain/brain-notebook.ts)
+- [brain-portability.ts](../../src/brain/brain-portability.ts)
+- [brain-quantize.ts](../../src/brain/brain-quantize.ts)
+- [brain-query-expander.ts](../../src/brain/brain-query-expander.ts)
+- [brain-quest.ts](../../src/brain/brain-quest.ts)
+- [brain-recall-cache.ts](../../src/brain/brain-recall-cache.ts)
+- [brain-reflex.ts](../../src/brain/brain-reflex.ts)
+- [brain-replay.ts](../../src/brain/brain-replay.ts)
+- [brain-rerank.ts](../../src/brain/brain-rerank.ts)
+- [brain-roast.ts](../../src/brain/brain-roast.ts)
+- [brain-sonification.ts](../../src/brain/brain-sonification.ts)
+- [brain-tarot.ts](../../src/brain/brain-tarot.ts)
+- [brain-time-capsule.ts](../../src/brain/brain-time-capsule.ts)
+- [brain-trophies.ts](../../src/brain/brain-trophies.ts)
+- [brain-working-memory.ts](../../src/brain/brain-working-memory.ts)
+- [branch-brain.ts](../../src/brain/branch-brain.ts)
+- [calibration-monitor.ts](../../src/brain/calibration-monitor.ts)
+- [causal-chains.ts](../../src/brain/causal-chains.ts)
+- [client-config.ts](../../src/brain/client-config.ts)
+- [client-integrations.ts](../../src/brain/client-integrations.ts)
+- [code-age-analyzer.ts](../../src/brain/code-age-analyzer.ts)
+- [code-dna.ts](../../src/brain/code-dna.ts)
+- [code-metrics.ts](../../src/brain/code-metrics.ts)
+- [code-similarity.ts](../../src/brain/code-similarity.ts)
+- [cognitive-load.ts](../../src/brain/cognitive-load.ts)
+- [collective-learning.ts](../../src/brain/collective-learning.ts)
+- [collision-detective.ts](../../src/brain/collision-detective.ts)
+- [confidence-gate.ts](../../src/brain/confidence-gate.ts)
+- [config-drift-detector.ts](../../src/brain/config-drift-detector.ts)
+- [consensus-engine.ts](../../src/brain/consensus-engine.ts)
+- [constitution.ts](../../src/brain/constitution.ts)
+- [context-assembly.ts](../../src/brain/context-assembly.ts)
+- [context-completion.ts](../../src/brain/context-completion.ts)
+- [context-continuity.ts](../../src/brain/context-continuity.ts)
+- [context-recall.ts](../../src/brain/context-recall.ts)
+- [context-request.ts](../../src/brain/context-request.ts)
+- [context-retrieval.ts](../../src/brain/context-retrieval.ts)
+- [cost-aware-spawner.ts](../../src/brain/cost-aware-spawner.ts)
+- [cross-agent-protocol.ts](../../src/brain/cross-agent-protocol.ts)
+- [custom-rules.ts](../../src/brain/custom-rules.ts)
+- [dead-code-eliminator.ts](../../src/brain/dead-code-eliminator.ts)
+- [dependency-graph.ts](../../src/brain/dependency-graph.ts)
+- [dream-engine.ts](../../src/brain/dream-engine.ts)
+- [embeddings-v2.ts](../../src/brain/embeddings-v2.ts)
+- [embeddings.ts](../../src/brain/embeddings.ts)
+- [env-analyzer.ts](../../src/brain/env-analyzer.ts)
+- [feature-settings.ts](../../src/brain/feature-settings.ts)
+- [fine-tuning-engine.ts](../../src/brain/fine-tuning-engine.ts)
+- [forgetting-curve.ts](../../src/brain/forgetting-curve.ts)
+- [formal-verification-bridge.ts](../../src/brain/formal-verification-bridge.ts)
+- [framework-presets.ts](../../src/brain/framework-presets.ts)
+- [global-brain.ts](../../src/brain/global-brain.ts)
+- [hallucination-quarantine.ts](../../src/brain/hallucination-quarantine.ts)
+- [health-score.ts](../../src/brain/health-score.ts)
+- [hierarchical-memory.ts](../../src/brain/hierarchical-memory.ts)
+- [hive-accelerator.ts](../../src/brain/hive-accelerator.ts)
+- [hive-voice.ts](../../src/brain/hive-voice.ts)
+- [i18n-detector.ts](../../src/brain/i18n-detector.ts)
+- [influence-map.ts](../../src/brain/influence-map.ts)
+- [intent-engine.ts](../../src/brain/intent-engine.ts)
+- [json-output.ts](../../src/brain/json-output.ts)
+- [knowledge-graph.ts](../../src/brain/knowledge-graph.ts)
+- [l0-cache.ts](../../src/brain/l0-cache.ts)
+- [learning-engine.ts](../../src/brain/learning-engine.ts)
+- [license-compliance.ts](../../src/brain/license-compliance.ts)
+- [live-brain.ts](../../src/brain/live-brain.ts)
+- [llm-client.ts](../../src/brain/llm-client.ts)
+- [local-llm.ts](../../src/brain/local-llm.ts)
+- [lsp-server.ts](../../src/brain/lsp-server.ts)
+- [markdown-export.ts](../../src/brain/markdown-export.ts)
+- [mcp-server.ts](../../src/brain/mcp-server.ts)
+- [mcp-stdio.ts](../../src/brain/mcp-stdio.ts)
+- [memory-annotations.ts](../../src/brain/memory-annotations.ts)
+- [memory-graph.ts](../../src/brain/memory-graph.ts)
+- [memory-inspection.ts](../../src/brain/memory-inspection.ts)
+- [memory-mcp-content.ts](../../src/brain/memory-mcp-content.ts)
+- [memory-seeder.ts](../../src/brain/memory-seeder.ts)
+- [memory-sources.ts](../../src/brain/memory-sources.ts)
+- [model-registry.ts](../../src/brain/model-registry.ts)
+- [multi-project.ts](../../src/brain/multi-project.ts)
+- [multimodal-vision.ts](../../src/brain/multimodal-vision.ts)
+- [mutation-advisor.ts](../../src/brain/mutation-advisor.ts)
+- [neural-mesh.ts](../../src/brain/neural-mesh.ts)
+- [notifier.ts](../../src/brain/notifier.ts)
+- [orchestrator.ts](../../src/brain/orchestrator.ts)
+- [otel-lite.ts](../../src/brain/otel-lite.ts)
+- [pattern-memory.ts](../../src/brain/pattern-memory.ts)
+- [perf-profiler.ts](../../src/brain/perf-profiler.ts)
+- [plugin-system.ts](../../src/brain/plugin-system.ts)
+- [pr-auto-review.ts](../../src/brain/pr-auto-review.ts)
+- [pr-generator.ts](../../src/brain/pr-generator.ts)
+- [pre-mortem.ts](../../src/brain/pre-mortem.ts)
+- [predictive-engine.ts](../../src/brain/predictive-engine.ts)
+- [project-config.ts](../../src/brain/project-config.ts)
+- [project-context.ts](../../src/brain/project-context.ts)
+- [prompt-cache.ts](../../src/brain/prompt-cache.ts)
+- [report-generator.ts](../../src/brain/report-generator.ts)
+- [reputation-ledger.ts](../../src/brain/reputation-ledger.ts)
+- [security-audit.ts](../../src/brain/security-audit.ts)
+- [self-evolution.ts](../../src/brain/self-evolution.ts)
+- [semantic-analyzer.ts](../../src/brain/semantic-analyzer.ts)
+- [session-hooks.ts](../../src/brain/session-hooks.ts)
+- [smart-cache.ts](../../src/brain/smart-cache.ts)
+- [smart-fix.ts](../../src/brain/smart-fix.ts)
+- [sssp-router.ts](../../src/brain/sssp-router.ts)
+- [subagent-bridge.ts](../../src/brain/subagent-bridge.ts)
+- [subconscious.ts](../../src/brain/subconscious.ts)
+- [swarm-debate.ts](../../src/brain/swarm-debate.ts)
+- [swarm-intelligence.ts](../../src/brain/swarm-intelligence.ts)
+- [task-workflow.ts](../../src/brain/task-workflow.ts)
+- [team-brain-sync.ts](../../src/brain/team-brain-sync.ts)
+- [team-mode.ts](../../src/brain/team-mode.ts)
+- [temporal-intelligence.ts](../../src/brain/temporal-intelligence.ts)
+- [token-economy.ts](../../src/brain/token-economy.ts)
+- [turbo-memory.ts](../../src/brain/turbo-memory.ts)
+- [type-safety.ts](../../src/brain/type-safety.ts)
+- [voice-mode.ts](../../src/brain/voice-mode.ts)
+- [vuln-scanner.ts](../../src/brain/vuln-scanner.ts)
+- [workflow-skills.ts](../../src/brain/workflow-skills.ts)
+
+### src/dashboard
+
+- [project-feedback-html.ts](../../src/dashboard/project-feedback-html.ts)
+- [project-kit-html.ts](../../src/dashboard/project-kit-html.ts)
+- [project-workspace.ts](../../src/dashboard/project-workspace.ts)
+
+- [demo-workspace.ts](../../src/dashboard/demo-workspace.ts)
+- [live-workspace-html.ts](../../src/dashboard/live-workspace-html.ts)
+- [server.ts](../../src/dashboard/server.ts)
+- [v6-dashboard-html.ts](../../src/dashboard/v6-dashboard-html.ts)
+- [workspace-api.ts](../../src/dashboard/workspace-api.ts)
+- [workspace-html.ts](../../src/dashboard/workspace-html.ts)
+
+### src/adapters
+
+- [aider.ts](../../src/adapters/aider.ts)
+- [base-adapter.ts](../../src/adapters/base-adapter.ts)
+- [claude-code.ts](../../src/adapters/claude-code.ts)
+- [cline.ts](../../src/adapters/cline.ts)
+- [codex.ts](../../src/adapters/codex.ts)
+- [copilot.ts](../../src/adapters/copilot.ts)
+- [cursor.ts](../../src/adapters/cursor.ts)
+- [index.ts](../../src/adapters/index.ts)
+- [kilo-code.ts](../../src/adapters/kilo-code.ts)
+- [opencode.ts](../../src/adapters/opencode.ts)
+- [roo-code.ts](../../src/adapters/roo-code.ts)
+- [windsurf.ts](../../src/adapters/windsurf.ts)
+
+### src/watchers
+
+- [file-watcher.ts](../../src/watchers/file-watcher.ts)
+- [git-watcher.ts](../../src/watchers/git-watcher.ts)
+
+### src/ui
+
+- [dashboard.tsx](../../src/ui/dashboard.tsx)

package/docs/launch/PROJECT_KIT_PLAN_v7.1.4.md

@@ -0,0 +1,110 @@
+# Project Kit: local knowledge and requirement-specific skills
+
+Added to the 7.1.4 scope on 2026-11-12 following the user's request. Status: implementation in progress. This extends the [research and acceptance plan](RESEARCH_AND_PLAN_v7.1.4.md); it does not change the earlier compatibility requirements.
+
+## Intended behavior
+
+A user opens a chosen project, sees what Shadow Brain can observe about its stack, records knowledge they want an agent to remember, and creates a focused skill for that project's requirement. The knowledge, skill, and settings stay inside that project. The same local memory becomes available in Context Lab and through the project's generated MCP launch recipe.
+
+The workflow is **select project → inspect observed stack → record explicit knowledge → describe requirement → preview skill → apply locally → use local context**. Workspace detection and skill drafting are deterministic and do not require a model provider. “Observed stack” means bounded manifest and directory evidence; it does not mean the program has semantically understood all source code or validated the user's requirement.
+
+## Storage and entry point
+
+Use an additive project-workspace entry point, proposed as `shadow-brain project workspace <directory>`. It serves the existing workspace UI with explicit dependencies pointing at `<project>/.shadow-brain/project-memory.json`. Annotations, settings, activity, and the generated-skill receipt remain in that project's `.shadow-brain` directory. The final CLI spelling must be verified and reflected in the quickstart.
+
+The existing global-backed `dash` and context defaults remain compatible. Do not silently merge or migrate global memories into a project store. An independent explicit `GlobalBrain` instance may be used for the project service; the existing singleton behavior stays intact. A project workspace shuts down its server and flushes its own writes, but **does not delete the persistent project directory or knowledge**. Temporary demo cleanup is a separate code path.
+
+Project recipes must pass the actual local database path with `--db`; setting the MCP process's working directory alone does not select a local store. A new MCP process launched from the recipe must recall a newly saved project note. Generic process-wide BrainBus activity must not leak events from another store into a project-local workspace; use its local journal or an explicit store-specific activity dependency.
+
+## Project inspection
+
+The scanner accepts one existing, explicit project root. It rejects drive roots, home/global agent configuration roots, linked ancestors, and invalid paths. All reads stay beneath that root. Inspection is read-only and returns structured evidence and limitations.
+
+Initial bounds:
+
+- A deterministic relative directory view with a fixed entry count and depth, initially 500 entries and depth 3.
+- A fixed manifest allowlist with regular single-link files, initially at most 64 KiB per inspected manifest.
+- Exclude dependency caches, version-control internals, generated outputs, environment files, authentication/configuration stores, and linked paths before recursion or content reads.
+- Extract known dependency names, known script names, manifest types, and package-manager evidence. Do not expose dependency URL/version values, script bodies, arbitrary metadata, or source-file contents.
+- Read no browser data, provider settings, credential stores, or model configuration. Fetch no remote source and execute no discovered script.
+
+A package manifest can support an observation such as “React dependency declared.” It does not establish that every page uses React or that a command succeeds. Ambiguous package managers, missing manifests, unsupported formats, and scan truncation remain visible. A generic project can still receive a requirement-specific skill, with unknown stack details left explicit.
+
+Suggested profile shape:
+
+```ts
+interface ProjectProfile {
+  schemaVersion: 1;
+  projectId: string;
+  projectName: string;
+  root: string;
+  observedAt: string;
+  stack: string[];
+  packageManagers: string[];
+  evidence: Array<{ path: string; kind: string; signals: string[] }>;
+  checks: Array<{ label: string; command: string; source: string }>;
+  coverage: { entries: number; limit: number; truncated: boolean };
+  warnings: string[];
+}
+```
+
+The worker may refine field names before callers are committed. All interfaces should consume one shared implementation rather than duplicate stack inference.
+
+## Explicit knowledge
+
+Accept bounded user text, a title, an optional category, and an optional recorded reference. A useful initial content bound is 8,000 characters and a source-reference bound is 500. Save the title and supplied content with the canonical project identity in the project's memory store; acknowledge success only after persistence succeeds.
+
+Record metadata such as `origin: project-kit-user` and `inputKind: explicit-knowledge`. Only populate source references when the user supplies an actual reference. Do not manufacture a citation that inflates source-coverage counts. The user-provided knowledge is not independently verified, and source targets are not fetched.
+
+New knowledge must be immediately inspectable in Memories, eligible for scoped Context Lab retrieval, persistent after restart, and visible to the project's MCP recipe. Do not add knowledge automatically from environment files, personal profiles, conversation history, or unrelated projects.
+
+## Generated skills
+
+The service takes an explicit requirement, the observed profile, the chosen client target, an optional name, and optional explicit knowledge. It generates one concise, self-contained `SKILL.md` unless a concrete need justifies additional resources. The required `name` and `description` frontmatter is valid and safely encoded. The description names a narrow task and project context so unrelated tasks do not select it.
+
+The body includes the actual requirement, relevant user knowledge, observed stack evidence, local implementation considerations, and available validation guidance. It must not fabricate commands or evidence, install dependencies, run code, claim tests passed, grant extra permissions, or override the user's current project instructions. Generated guidance should be proportionate to the task rather than turning every request into an elaborate process.
+
+Reuse existing client targets and project skill locations:
+
+| Target | Project-local destination |
+| --- | --- |
+| `codex` | `.agents/skills/<name>/SKILL.md` |
+| `claude-code` | `.claude/skills/<name>/SKILL.md` |
+| `opencode` | `.opencode/skills/<name>/SKILL.md` |
+| `deepseek-harness` | `.dsh/skills/<name>/SKILL.md` |
+| `portable` | `.agents/skills/<name>/SKILL.md` |
+
+Names contain lowercase letters, numbers, and hyphens and stay under 64 characters. A generated default name should be stable for the project and requirement. No generated skill is installed in a home/global skills directory. Do not silently edit `AGENTS.md`, client profiles, provider settings, or authentication files. Skill-file presence is not proof that a host loaded it.
+
+## Preview, apply, and ownership
+
+Preview returns the exact output path and content, observed evidence, conflicts, and a stable plan hash. It creates no directories or files. The UI makes these inspectable before the user applies the local skill.
+
+The hash binds the selected root, target, requirement, explicit knowledge, generated bytes, relevant observed profile, and existing-file state. Exclude observation timestamps and other volatile display fields. Recompute the plan before apply; do not trust a client-supplied arbitrary file path or content object.
+
+Use a dedicated project-local ownership receipt, separate from the bundled workflow installer. Apply verifies root/destination ancestors, rejects links and unexpected file types, and writes only planned generated paths. An unowned existing skill conflicts. An owned skill changed by the user conflicts. An unchanged owned skill can be updated or reported unchanged. Stale plans fail without overwriting recent work. Use bounded locking and atomic replacement; report any partial-write failure accurately.
+
+Suggested public service operations:
+
+```ts
+inspectProject(root)
+planProjectSkill(root, { requirement, target, name?, knowledge? })
+applyProjectSkill(root, request, expectedPlanHash)
+```
+
+HTTP routes operate on the server's pinned root; they do not accept arbitrary filesystem roots from the browser. Knowledge input and skill apply are explicit write actions, separately labeled from inspection and preview. The coordinating agent owns the final route and CLI names.
+
+## Acceptance gates
+
+1. Inspect JavaScript/TypeScript, PHP or another supported stack, ambiguous manifests, and an unknown project without inventing missing facts. Verify deterministic output apart from observation time.
+2. Prove directory/manifest bounds, excluded paths, symlink/hardlink rejection, and refusal of home/global roots using synthetic fixtures. Secret-like values in disallowed fields must never appear in returned profiles or generated skills.
+3. Verify requirement and explicit knowledge materially change the generated skill. Verify valid frontmatter, bounded text, focused description, correct client root, and no unrelated file changes.
+4. Preview produces no filesystem writes. Repeated apply is idempotent. Edited/unowned files and stale plan hashes conflict. Apply never writes outside the selected root.
+5. Save explicit knowledge, retrieve it through Context Lab, restart the project workspace, and retrieve it again. Launch a fresh MCP process using the generated local-store recipe and verify the same committed memory.
+6. Place a foreign sentinel in another synthetic store and process-wide activity source. Verify the project workspace's memories, context, health, activity, and skill generation do not expose it.
+7. Complete the visible inspect→knowledge→skill preview→apply→context workflow on desktop and mobile. Verify error, conflict, empty, and unknown-stack states.
+8. Run inherited regression tests and exact packed-artifact CLI/server tests. Preserve the older global dashboard, bundled skill installer, demo action, and memory schema.
+
+The final README needs a project-local onboarding example and an actual screenshot of this workflow. It must distinguish persistent project knowledge from the disposable synthetic demo and explicitly describe the limits of deterministic workspace detection.
+
+The later [project learning addendum](PROJECT_LEARNING_PLAN_v7.1.4.md) adds attributed memory outcomes and reversible task-relevant retrieval influence to this same local workspace. Its acceptance gates are additional; a successful skill installation alone does not verify the learning loop.

package/docs/launch/PROJECT_LEARNING_PLAN_v7.1.4.md

@@ -0,0 +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.

package/docs/launch/RELEASE_NOTES_v7.1.3.md

@@ -0,0 +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.

package/docs/launch/RELEASE_NOTES_v7.1.4.md

@@ -0,0 +1,30 @@
+# Agent Shadow Brain 7.1.4
+
+The local Brain Hub brings actual saved memory, project documents, collaboration, and the activity journal into one control room. Node.js 22.13+ in the 22.x line, 24.x, or 26+ is required.
+
+## Install and open
+
+```bash
+npm install -g @theihtisham/agent-shadow-brain@latest
+shadow-brain --version
+shadow-brain project workspace . --port 62595
+```
+
+Check for `7.1.4`, then open [the project Brain Hub](http://127.0.0.1:62595/hub). Keep the local process running. Reuse the project directory and port after a restart. The classic workspace is still at `/workspace`; detailed activity is at `/live`. [Quickstart](../QUICKSTART.md)
+
+## What changed
+
+- **Control room.** The graph loads actual project, agent, and memory relationships, with a keyboard-accessible node list and record inspector. The local process reports its own health. The page retries when it loses the server, and it reopens the scope when the process instance changes.
+- **PDF intake.** Project PDFs have bounded extraction, stored fingerprints, and page-level review. Approved pages become cited project memory. Image-only pages surface the need for OCR.
+- **Collaboration.** Project rooms contain proposals, replies, leased task claims, artifacts with recorded digests, acknowledgements, and outcomes. The browser and configured project-local MCP clients share these records.
+- **Context and skills.** Build and compare scoped packs, copy the rendered Markdown, save project knowledge, and preview and apply host-specific project skills. The classic Context Lab retains detailed retrieval explanations and memory curation.
+- **Learning.** A recorded outcome can become a candidate. The operator records evaluation and explicitly promotes an eligible lesson. Rollback archives the promoted memory’s retrieval influence.
+- **Setup and usage.** Persist feature changes and copy native client recipes. The Hub separates measured tool activity from explicit reports. Provider usage receipts, model identity, and cost are unavailable without host evidence. Context pack tokens are estimates.
+
+![The running control room with an isolated checkout fixture](../assets/7.1.4-hub-control-room.png)
+
+## Verification scope
+
+Browser checks used isolated fixture data with actual local stores and MCP calls. They exercised graph selection, context copy, PDF review, feature changes, shared work, durable retry, learning rollback, and same-port reconnect. Host file detection and local tool exchange are separate from native host confirmation. The release does not include autonomous model execution or model training.
+
+[Visual guide](../VISUAL_GUIDE_v7.1.4.md) · [Workflow integration](../WORKFLOW_INTEGRATION.md) · [Changelog](../../CHANGELOG.md)

package/docs/launch/RELEASE_NOTES_v7.2.0.md

@@ -0,0 +1,24 @@
+# Agent Shadow Brain 7.2.0
+
+Version 7.2 makes it easier to see what agents have saved and choose what to hand to a new session. The default local workspace has five views for overview, memory search, the project and agent graph, context assembly, and feature controls. The previous dashboard remains available at `/advanced`.
+
+## What changed
+
+- Context packs rank memories for the selected project and task, collapse exact duplicates, retain recorded source provenance, and explain what fits the rendered budget. Cross-project context requires both a setting and explicit opt-in.
+- Session briefings use the same assembler. Cached briefings follow the current task and feature settings. Disabling automatic briefings suppresses both new and cached output.
+- Four persistent switches control context packs, cross-project access within context packs, automatic briefings, and dashboard activity. The settings store validates updates, detects revision conflicts, and replaces saved settings atomically.
+- The CLI adds `context-pack` and `features list|set`. MCP clients can call `context_pack` and `feature_flags`. Library consumers can import the assembler and settings store directly.
+- The README includes a conceptual memory-flow illustration and screenshots from the running workspace with synthetic data.
+
+## Start the workspace
+
+```bash
+npm install -g @theihtisham/agent-shadow-brain@7.2.0
+shadow-brain dash . --no-analysis
+```
+
+From a second terminal, run `shadow-brain context-pack "import retry behavior" --project . --token-budget 1200` to inspect what an agent would receive for that task.
+
+Memory storage keeps schema version 1. The six bundled skills and the existing skill install workflow remain available. If you are coming from 6.x, follow the [7.0 migration notes](RELEASE_NOTES_v7.0.0.md).
+
+[Workspace guide](../WORKSPACE.md) · [Skill integration guide](../WORKFLOW_INTEGRATION.md)