@theihtisham/agent-shadow-brain 7.22.0 → 7.22.1

package/docs/evaluation/CONTEXT_EVALUATION_v7.1.4.md

@@ -1,36 +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.
+# 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

@@ -1,103 +1,103 @@
-# 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)
+# 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)
@@ -107,14 +107,14 @@ This inventory is generated from source filenames. It classifies location, not v
 - [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)
+
+### 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)
@@ -268,21 +268,21 @@ This inventory is generated from source filenames. It classifies location, not v
 - [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)
+
+### 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
+
+### src/adapters
 
 - [aider.ts](../../src/adapters/aider.ts)
 - [base-adapter.ts](../../src/adapters/base-adapter.ts)
@@ -296,12 +296,12 @@ This inventory is generated from source filenames. It classifies location, not v
 - [opencode.ts](../../src/adapters/opencode.ts)
 - [roo-code.ts](../../src/adapters/roo-code.ts)
 - [windsurf.ts](../../src/adapters/windsurf.ts)
-
-### src/watchers
+
+### src/watchers
 
 - [file-watcher.ts](../../src/watchers/file-watcher.ts)
 - [git-watcher.ts](../../src/watchers/git-watcher.ts)
-
-### src/ui
+
+### src/ui
 
 - [dashboard.tsx](../../src/ui/dashboard.tsx)

package/docs/launch/PROJECT_KIT_PLAN_v7.1.4.md

@@ -1,110 +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.
+# 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.