From 3c1f17eacd40e7e7d1802e81ba8054533a56c1e8 Mon Sep 17 00:00:00 2001 From: 1norahc Date: Sun, 13 Sep 2026 14:54:39 +0200 Subject: [PATCH 1/2] docs: define MAP architecture and MVP contracts (#103) --- .cursor/rules/map.mdc | 164 ++++++++++++++++++ .github/copilot-instructions.md | 164 ++++++++++++++++++ ...02-framework-neutral-deterministic-core.md | 44 +++++ ...0003-stable-pattern-identity-and-schema.md | 44 +++++ .../0004-versioned-cli-json-contracts.md | 43 +++++ ...tatic-analysis-before-assisted-analysis.md | 42 +++++ .../0006-mcp-as-a-separate-adapter.md | 41 +++++ AGENTS.md | 164 ++++++++++++++++++ CLAUDE.md | 164 ++++++++++++++++++ GEMINI.md | 164 ++++++++++++++++++ docs/architecture/CLI.md | 32 ++++ docs/architecture/MCP.md | 16 ++ docs/architecture/PATTERN_GRAPH.md | 30 ++++ docs/architecture/PATTERN_MODEL.md | 39 +++++ docs/architecture/README.md | 43 +++++ docs/architecture/RECOMMENDATION_ENGINE.md | 29 ++++ docs/architecture/SCANNER.md | 32 ++++ docs/architecture/SECURITY.md | 36 ++++ docs/architecture/SYSTEM_ARCHITECTURE.md | 59 +++++++ docs/architecture/VERIFICATION_ENGINE.md | 27 +++ docs/project/GLOSSARY.md | 22 +++ docs/project/IMPLEMENTATION_PLAN.md | 41 +++++ docs/project/MISSION.md | 14 ++ docs/project/MVP.md | 42 +++++ docs/project/NON_GOALS.md | 17 ++ docs/project/PRINCIPLES.md | 23 +++ docs/project/PRODUCT_SPEC.md | 59 +++++++ docs/project/ROADMAP.md | 42 +++++ docs/project/VISION.md | 13 ++ docs/specifications/MAP_MANIFEST.md | 31 ++++ docs/specifications/PATTERN_SCHEMA.md | 49 ++++++ docs/specifications/PATTERN_SPEC.md | 27 +++ docs/specifications/RECOMMENDATION_RESULT.md | 28 +++ docs/specifications/SCAN_RESULT.md | 31 ++++ docs/specifications/VERIFICATION_RESULT.md | 32 ++++ 35 files changed, 1848 insertions(+) create mode 100644 .map/decisions/0002-framework-neutral-deterministic-core.md create mode 100644 .map/decisions/0003-stable-pattern-identity-and-schema.md create mode 100644 .map/decisions/0004-versioned-cli-json-contracts.md create mode 100644 .map/decisions/0005-static-analysis-before-assisted-analysis.md create mode 100644 .map/decisions/0006-mcp-as-a-separate-adapter.md create mode 100644 docs/architecture/CLI.md create mode 100644 docs/architecture/MCP.md create mode 100644 docs/architecture/PATTERN_GRAPH.md create mode 100644 docs/architecture/PATTERN_MODEL.md create mode 100644 docs/architecture/README.md create mode 100644 docs/architecture/RECOMMENDATION_ENGINE.md create mode 100644 docs/architecture/SCANNER.md create mode 100644 docs/architecture/SECURITY.md create mode 100644 docs/architecture/SYSTEM_ARCHITECTURE.md create mode 100644 docs/architecture/VERIFICATION_ENGINE.md create mode 100644 docs/project/GLOSSARY.md create mode 100644 docs/project/IMPLEMENTATION_PLAN.md create mode 100644 docs/project/MISSION.md create mode 100644 docs/project/MVP.md create mode 100644 docs/project/NON_GOALS.md create mode 100644 docs/project/PRINCIPLES.md create mode 100644 docs/project/PRODUCT_SPEC.md create mode 100644 docs/project/ROADMAP.md create mode 100644 docs/project/VISION.md create mode 100644 docs/specifications/MAP_MANIFEST.md create mode 100644 docs/specifications/PATTERN_SCHEMA.md create mode 100644 docs/specifications/PATTERN_SPEC.md create mode 100644 docs/specifications/RECOMMENDATION_RESULT.md create mode 100644 docs/specifications/SCAN_RESULT.md create mode 100644 docs/specifications/VERIFICATION_RESULT.md diff --git a/.cursor/rules/map.mdc b/.cursor/rules/map.mdc index 93585a7..f29ce11 100644 --- a/.cursor/rules/map.mdc +++ b/.cursor/rules/map.mdc @@ -105,6 +105,139 @@ Generated files such as `AGENTS.md` are projections. Authors edit `.map/`, then --- +# ADR-0002: Framework-neutral deterministic core + +## Context + +MAP must describe systems built with many model providers, languages, and agent +frameworks. Binding the domain to one SDK would shorten an initial implementation but +make patterns, scanners, and recommendations obsolete when that SDK changes. Requiring +an LLM would also make baseline results non-repeatable and unavailable offline. + +## Decision + +Registry parsing, graph construction, validation, static scanning, and baseline +recommendation are pure or deterministic core capabilities. They MUST NOT depend on a +model provider, agent framework, remote service, or MCP runtime. + +Framework manifests, coding-agent formats, MCP, semantic indexes, and optional LLM +reasoning are adapters at explicit boundaries. Core types use MAP vocabulary and may +carry adapter evidence without importing adapter-specific types. + +## Consequences + +- Core commands work offline and are straightforward to test. +- Framework integrations can evolve independently. +- Some framework-specific insight will initially be less deep than a dedicated tool. +- Optional assisted output must be labeled and cannot replace deterministic evidence. + +## Verification + +- Core package dependency graphs contain no model SDK. +- Tests use fixed inputs and require no network. +- CLI JSON outputs identify limitations and remain stable for identical inputs. + +--- + +# ADR-0003: Stable pattern identity and schema + +## Context + +MAP already publishes and cross-references slash-form pattern IDs. Proposed examples +sometimes use dotted IDs, and the current YAML contract is described but not enforced. +A silent identifier migration would break links, commands, adopted patterns, and caches. + +## Decision + +Pattern Schema v1 uses canonical IDs matching `^[a-z0-9-]+/[a-z0-9-]+$`. A record has +an explicit `kind` (`pattern` or `anti-pattern`), lifecycle status, optional evidence +maturity, decision guidance, and typed relationships. Flat `related` input remains a +supported compatibility field and normalizes to `works_with` edges. + +Aliases may accept alternate spelling at input boundaries, but public output and graph +nodes return the canonical slash-form ID. Meaning-changing contract updates require a +new schema version and migration notes. + +## Consequences + +- Existing links and CLI workflows remain valid. +- Patterns and anti-patterns share validation and discovery infrastructure. +- Authors must distinguish publication status from evidence maturity. +- Compatibility normalization adds a small amount of registry-builder logic. + +## Verification + +- Schema fixtures cover canonical IDs, anti-patterns, relationships, and failures. +- Registry parsing rejects duplicate IDs and dangling relation targets. +- Existing five published patterns validate without identity changes. + +--- + +# ADR-0004: Versioned CLI JSON contracts + +## Context + +Terminal prose is useful to people but brittle for automation and agent tools. Adding +fields without an envelope also prevents consumers from knowing which contract they +received. + +## Decision + +Commands with machine output emit a JSON document with `schemaVersion`, `kind`, and +command-specific payload. JSON mode writes no headings, colors, or success messages to +standard output. Diagnostic warnings go to standard error. Arrays use documented, +deterministic ordering. + +Existing human output stays the default. Existing commands remain, while clearer names +(`list`, `show`, `search`, `scan`, `suggest`) are additive aliases over the same core +use cases. + +## Consequences + +- Agents can consume CLI results without text scraping. +- Contract changes require deliberate versioning and fixtures. +- Reporter implementations and tests must preserve stdout/stderr separation. + +## Verification + +- JSON outputs validate against published schemas where one exists. +- Alias and original commands produce equivalent payloads. +- Snapshot tests assert deterministic ordering and absence of decoration. + +--- + +# ADR-0005: Static analysis before assisted analysis + +## Context + +Repository analysis can become invasive, expensive, and non-repeatable if it executes +project code, reads secrets, or uploads source to a model. Dependency manifests provide +a narrower but auditable first signal. + +## Decision + +The MVP scanner reads declared dependency manifests as data and never executes project +code. It records file-level evidence, numeric confidence, a derived certainty state, +the analyzers used, and limitations. Unsupported or absent evidence is `unknown`, not +proof that a capability is absent. + +Source, configuration, semantic, runtime, and LLM analyzers are separate future +adapters with explicit permissions and provenance. + +## Consequences + +- MVP scanning is fast, local, and safe by default. +- Results have false negatives and cannot verify implementations. +- Recommendation text must explain the evidence boundary. + +## Verification + +- Scanner tests use fixtures and make no network calls. +- Results list inspected files and analyzer limitations. +- Secret values are never included in output. + +--- + # MAP's own workspace This repository uses the same project structure generated by `map init`. The @@ -139,6 +272,37 @@ the curated, human-maintained picture. --- +# ADR-0006: MCP as a separate adapter + +## Context + +MCP can expose MAP knowledge to agents, but it introduces transport, lifecycle, +permissions, and compatibility concerns unrelated to the core domain. + +## Decision + +MCP is deferred from the deterministic MVP and will live in a separate adapter package. +It will call the same registry, graph, scanner, recommendation, and validation ports as +the CLI. The MCP layer may format or transport results but must not define alternate +pattern semantics. + +Initial MCP tools should be read-only. Any future mutation tool requires an explicit +threat model, path boundary, preview, and human approval policy. + +## Consequences + +- The core remains usable without an MCP runtime. +- CLI and MCP behavior can share contract tests. +- MCP delivery follows rather than blocks the MVP. + +## Verification + +- No MCP dependency exists in core packages. +- Future MCP results validate against the same public contracts as CLI JSON. +- Security review precedes any write-capable MCP tool. + +--- + # Decisions Architecture Decision Records (ADRs) for AI-related choices: RAG vs fine-tuning, diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index ff1c679..7ae2f86 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -100,6 +100,139 @@ Generated files such as `AGENTS.md` are projections. Authors edit `.map/`, then --- +# ADR-0002: Framework-neutral deterministic core + +## Context + +MAP must describe systems built with many model providers, languages, and agent +frameworks. Binding the domain to one SDK would shorten an initial implementation but +make patterns, scanners, and recommendations obsolete when that SDK changes. Requiring +an LLM would also make baseline results non-repeatable and unavailable offline. + +## Decision + +Registry parsing, graph construction, validation, static scanning, and baseline +recommendation are pure or deterministic core capabilities. They MUST NOT depend on a +model provider, agent framework, remote service, or MCP runtime. + +Framework manifests, coding-agent formats, MCP, semantic indexes, and optional LLM +reasoning are adapters at explicit boundaries. Core types use MAP vocabulary and may +carry adapter evidence without importing adapter-specific types. + +## Consequences + +- Core commands work offline and are straightforward to test. +- Framework integrations can evolve independently. +- Some framework-specific insight will initially be less deep than a dedicated tool. +- Optional assisted output must be labeled and cannot replace deterministic evidence. + +## Verification + +- Core package dependency graphs contain no model SDK. +- Tests use fixed inputs and require no network. +- CLI JSON outputs identify limitations and remain stable for identical inputs. + +--- + +# ADR-0003: Stable pattern identity and schema + +## Context + +MAP already publishes and cross-references slash-form pattern IDs. Proposed examples +sometimes use dotted IDs, and the current YAML contract is described but not enforced. +A silent identifier migration would break links, commands, adopted patterns, and caches. + +## Decision + +Pattern Schema v1 uses canonical IDs matching `^[a-z0-9-]+/[a-z0-9-]+$`. A record has +an explicit `kind` (`pattern` or `anti-pattern`), lifecycle status, optional evidence +maturity, decision guidance, and typed relationships. Flat `related` input remains a +supported compatibility field and normalizes to `works_with` edges. + +Aliases may accept alternate spelling at input boundaries, but public output and graph +nodes return the canonical slash-form ID. Meaning-changing contract updates require a +new schema version and migration notes. + +## Consequences + +- Existing links and CLI workflows remain valid. +- Patterns and anti-patterns share validation and discovery infrastructure. +- Authors must distinguish publication status from evidence maturity. +- Compatibility normalization adds a small amount of registry-builder logic. + +## Verification + +- Schema fixtures cover canonical IDs, anti-patterns, relationships, and failures. +- Registry parsing rejects duplicate IDs and dangling relation targets. +- Existing five published patterns validate without identity changes. + +--- + +# ADR-0004: Versioned CLI JSON contracts + +## Context + +Terminal prose is useful to people but brittle for automation and agent tools. Adding +fields without an envelope also prevents consumers from knowing which contract they +received. + +## Decision + +Commands with machine output emit a JSON document with `schemaVersion`, `kind`, and +command-specific payload. JSON mode writes no headings, colors, or success messages to +standard output. Diagnostic warnings go to standard error. Arrays use documented, +deterministic ordering. + +Existing human output stays the default. Existing commands remain, while clearer names +(`list`, `show`, `search`, `scan`, `suggest`) are additive aliases over the same core +use cases. + +## Consequences + +- Agents can consume CLI results without text scraping. +- Contract changes require deliberate versioning and fixtures. +- Reporter implementations and tests must preserve stdout/stderr separation. + +## Verification + +- JSON outputs validate against published schemas where one exists. +- Alias and original commands produce equivalent payloads. +- Snapshot tests assert deterministic ordering and absence of decoration. + +--- + +# ADR-0005: Static analysis before assisted analysis + +## Context + +Repository analysis can become invasive, expensive, and non-repeatable if it executes +project code, reads secrets, or uploads source to a model. Dependency manifests provide +a narrower but auditable first signal. + +## Decision + +The MVP scanner reads declared dependency manifests as data and never executes project +code. It records file-level evidence, numeric confidence, a derived certainty state, +the analyzers used, and limitations. Unsupported or absent evidence is `unknown`, not +proof that a capability is absent. + +Source, configuration, semantic, runtime, and LLM analyzers are separate future +adapters with explicit permissions and provenance. + +## Consequences + +- MVP scanning is fast, local, and safe by default. +- Results have false negatives and cannot verify implementations. +- Recommendation text must explain the evidence boundary. + +## Verification + +- Scanner tests use fixtures and make no network calls. +- Results list inspected files and analyzer limitations. +- Secret values are never included in output. + +--- + # MAP's own workspace This repository uses the same project structure generated by `map init`. The @@ -134,6 +267,37 @@ the curated, human-maintained picture. --- +# ADR-0006: MCP as a separate adapter + +## Context + +MCP can expose MAP knowledge to agents, but it introduces transport, lifecycle, +permissions, and compatibility concerns unrelated to the core domain. + +## Decision + +MCP is deferred from the deterministic MVP and will live in a separate adapter package. +It will call the same registry, graph, scanner, recommendation, and validation ports as +the CLI. The MCP layer may format or transport results but must not define alternate +pattern semantics. + +Initial MCP tools should be read-only. Any future mutation tool requires an explicit +threat model, path boundary, preview, and human approval policy. + +## Consequences + +- The core remains usable without an MCP runtime. +- CLI and MCP behavior can share contract tests. +- MCP delivery follows rather than blocks the MVP. + +## Verification + +- No MCP dependency exists in core packages. +- Future MCP results validate against the same public contracts as CLI JSON. +- Security review precedes any write-capable MCP tool. + +--- + # Decisions Architecture Decision Records (ADRs) for AI-related choices: RAG vs fine-tuning, diff --git a/.map/decisions/0002-framework-neutral-deterministic-core.md b/.map/decisions/0002-framework-neutral-deterministic-core.md new file mode 100644 index 0000000..b4433a2 --- /dev/null +++ b/.map/decisions/0002-framework-neutral-deterministic-core.md @@ -0,0 +1,44 @@ +--- +kind: decision +id: adr-0002-framework-neutral-deterministic-core +title: Framework-neutral deterministic core +status: accepted +date: 2026-09-13 +owners: [rajanbor] +tags: [architecture, core, adapters] +priority: high +targets: [agents, claude, gemini, cursor, copilot] +--- + +# ADR-0002: Framework-neutral deterministic core + +## Context + +MAP must describe systems built with many model providers, languages, and agent +frameworks. Binding the domain to one SDK would shorten an initial implementation but +make patterns, scanners, and recommendations obsolete when that SDK changes. Requiring +an LLM would also make baseline results non-repeatable and unavailable offline. + +## Decision + +Registry parsing, graph construction, validation, static scanning, and baseline +recommendation are pure or deterministic core capabilities. They MUST NOT depend on a +model provider, agent framework, remote service, or MCP runtime. + +Framework manifests, coding-agent formats, MCP, semantic indexes, and optional LLM +reasoning are adapters at explicit boundaries. Core types use MAP vocabulary and may +carry adapter evidence without importing adapter-specific types. + +## Consequences + +- Core commands work offline and are straightforward to test. +- Framework integrations can evolve independently. +- Some framework-specific insight will initially be less deep than a dedicated tool. +- Optional assisted output must be labeled and cannot replace deterministic evidence. + +## Verification + +- Core package dependency graphs contain no model SDK. +- Tests use fixed inputs and require no network. +- CLI JSON outputs identify limitations and remain stable for identical inputs. + diff --git a/.map/decisions/0003-stable-pattern-identity-and-schema.md b/.map/decisions/0003-stable-pattern-identity-and-schema.md new file mode 100644 index 0000000..077508f --- /dev/null +++ b/.map/decisions/0003-stable-pattern-identity-and-schema.md @@ -0,0 +1,44 @@ +--- +kind: decision +id: adr-0003-stable-pattern-identity-and-schema +title: Stable pattern identity and schema +status: accepted +date: 2026-09-13 +owners: [rajanbor] +tags: [patterns, schema, compatibility] +priority: high +targets: [agents, claude, gemini, cursor, copilot] +--- + +# ADR-0003: Stable pattern identity and schema + +## Context + +MAP already publishes and cross-references slash-form pattern IDs. Proposed examples +sometimes use dotted IDs, and the current YAML contract is described but not enforced. +A silent identifier migration would break links, commands, adopted patterns, and caches. + +## Decision + +Pattern Schema v1 uses canonical IDs matching `^[a-z0-9-]+/[a-z0-9-]+$`. A record has +an explicit `kind` (`pattern` or `anti-pattern`), lifecycle status, optional evidence +maturity, decision guidance, and typed relationships. Flat `related` input remains a +supported compatibility field and normalizes to `works_with` edges. + +Aliases may accept alternate spelling at input boundaries, but public output and graph +nodes return the canonical slash-form ID. Meaning-changing contract updates require a +new schema version and migration notes. + +## Consequences + +- Existing links and CLI workflows remain valid. +- Patterns and anti-patterns share validation and discovery infrastructure. +- Authors must distinguish publication status from evidence maturity. +- Compatibility normalization adds a small amount of registry-builder logic. + +## Verification + +- Schema fixtures cover canonical IDs, anti-patterns, relationships, and failures. +- Registry parsing rejects duplicate IDs and dangling relation targets. +- Existing five published patterns validate without identity changes. + diff --git a/.map/decisions/0004-versioned-cli-json-contracts.md b/.map/decisions/0004-versioned-cli-json-contracts.md new file mode 100644 index 0000000..eff75c4 --- /dev/null +++ b/.map/decisions/0004-versioned-cli-json-contracts.md @@ -0,0 +1,43 @@ +--- +kind: decision +id: adr-0004-versioned-cli-json-contracts +title: Versioned CLI JSON contracts +status: accepted +date: 2026-09-13 +owners: [rajanbor] +tags: [cli, contracts, agents] +priority: high +targets: [agents, claude, gemini, cursor, copilot] +--- + +# ADR-0004: Versioned CLI JSON contracts + +## Context + +Terminal prose is useful to people but brittle for automation and agent tools. Adding +fields without an envelope also prevents consumers from knowing which contract they +received. + +## Decision + +Commands with machine output emit a JSON document with `schemaVersion`, `kind`, and +command-specific payload. JSON mode writes no headings, colors, or success messages to +standard output. Diagnostic warnings go to standard error. Arrays use documented, +deterministic ordering. + +Existing human output stays the default. Existing commands remain, while clearer names +(`list`, `show`, `search`, `scan`, `suggest`) are additive aliases over the same core +use cases. + +## Consequences + +- Agents can consume CLI results without text scraping. +- Contract changes require deliberate versioning and fixtures. +- Reporter implementations and tests must preserve stdout/stderr separation. + +## Verification + +- JSON outputs validate against published schemas where one exists. +- Alias and original commands produce equivalent payloads. +- Snapshot tests assert deterministic ordering and absence of decoration. + diff --git a/.map/decisions/0005-static-analysis-before-assisted-analysis.md b/.map/decisions/0005-static-analysis-before-assisted-analysis.md new file mode 100644 index 0000000..cdd6ccc --- /dev/null +++ b/.map/decisions/0005-static-analysis-before-assisted-analysis.md @@ -0,0 +1,42 @@ +--- +kind: decision +id: adr-0005-static-analysis-before-assisted-analysis +title: Static analysis before assisted analysis +status: accepted +date: 2026-09-13 +owners: [rajanbor] +tags: [scanner, security, evidence] +priority: high +targets: [agents, claude, gemini, cursor, copilot] +--- + +# ADR-0005: Static analysis before assisted analysis + +## Context + +Repository analysis can become invasive, expensive, and non-repeatable if it executes +project code, reads secrets, or uploads source to a model. Dependency manifests provide +a narrower but auditable first signal. + +## Decision + +The MVP scanner reads declared dependency manifests as data and never executes project +code. It records file-level evidence, numeric confidence, a derived certainty state, +the analyzers used, and limitations. Unsupported or absent evidence is `unknown`, not +proof that a capability is absent. + +Source, configuration, semantic, runtime, and LLM analyzers are separate future +adapters with explicit permissions and provenance. + +## Consequences + +- MVP scanning is fast, local, and safe by default. +- Results have false negatives and cannot verify implementations. +- Recommendation text must explain the evidence boundary. + +## Verification + +- Scanner tests use fixtures and make no network calls. +- Results list inspected files and analyzer limitations. +- Secret values are never included in output. + diff --git a/.map/decisions/0006-mcp-as-a-separate-adapter.md b/.map/decisions/0006-mcp-as-a-separate-adapter.md new file mode 100644 index 0000000..a70bf33 --- /dev/null +++ b/.map/decisions/0006-mcp-as-a-separate-adapter.md @@ -0,0 +1,41 @@ +--- +kind: decision +id: adr-0006-mcp-as-a-separate-adapter +title: MCP as a separate adapter +status: accepted +date: 2026-09-13 +owners: [rajanbor] +tags: [mcp, adapters, security] +priority: medium +targets: [agents, claude, gemini, cursor, copilot] +--- + +# ADR-0006: MCP as a separate adapter + +## Context + +MCP can expose MAP knowledge to agents, but it introduces transport, lifecycle, +permissions, and compatibility concerns unrelated to the core domain. + +## Decision + +MCP is deferred from the deterministic MVP and will live in a separate adapter package. +It will call the same registry, graph, scanner, recommendation, and validation ports as +the CLI. The MCP layer may format or transport results but must not define alternate +pattern semantics. + +Initial MCP tools should be read-only. Any future mutation tool requires an explicit +threat model, path boundary, preview, and human approval policy. + +## Consequences + +- The core remains usable without an MCP runtime. +- CLI and MCP behavior can share contract tests. +- MCP delivery follows rather than blocks the MVP. + +## Verification + +- No MCP dependency exists in core packages. +- Future MCP results validate against the same public contracts as CLI JSON. +- Security review precedes any write-capable MCP tool. + diff --git a/AGENTS.md b/AGENTS.md index 6223814..e5589bf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,6 +100,139 @@ Generated files such as `AGENTS.md` are projections. Authors edit `.map/`, then --- +# ADR-0002: Framework-neutral deterministic core + +## Context + +MAP must describe systems built with many model providers, languages, and agent +frameworks. Binding the domain to one SDK would shorten an initial implementation but +make patterns, scanners, and recommendations obsolete when that SDK changes. Requiring +an LLM would also make baseline results non-repeatable and unavailable offline. + +## Decision + +Registry parsing, graph construction, validation, static scanning, and baseline +recommendation are pure or deterministic core capabilities. They MUST NOT depend on a +model provider, agent framework, remote service, or MCP runtime. + +Framework manifests, coding-agent formats, MCP, semantic indexes, and optional LLM +reasoning are adapters at explicit boundaries. Core types use MAP vocabulary and may +carry adapter evidence without importing adapter-specific types. + +## Consequences + +- Core commands work offline and are straightforward to test. +- Framework integrations can evolve independently. +- Some framework-specific insight will initially be less deep than a dedicated tool. +- Optional assisted output must be labeled and cannot replace deterministic evidence. + +## Verification + +- Core package dependency graphs contain no model SDK. +- Tests use fixed inputs and require no network. +- CLI JSON outputs identify limitations and remain stable for identical inputs. + +--- + +# ADR-0003: Stable pattern identity and schema + +## Context + +MAP already publishes and cross-references slash-form pattern IDs. Proposed examples +sometimes use dotted IDs, and the current YAML contract is described but not enforced. +A silent identifier migration would break links, commands, adopted patterns, and caches. + +## Decision + +Pattern Schema v1 uses canonical IDs matching `^[a-z0-9-]+/[a-z0-9-]+$`. A record has +an explicit `kind` (`pattern` or `anti-pattern`), lifecycle status, optional evidence +maturity, decision guidance, and typed relationships. Flat `related` input remains a +supported compatibility field and normalizes to `works_with` edges. + +Aliases may accept alternate spelling at input boundaries, but public output and graph +nodes return the canonical slash-form ID. Meaning-changing contract updates require a +new schema version and migration notes. + +## Consequences + +- Existing links and CLI workflows remain valid. +- Patterns and anti-patterns share validation and discovery infrastructure. +- Authors must distinguish publication status from evidence maturity. +- Compatibility normalization adds a small amount of registry-builder logic. + +## Verification + +- Schema fixtures cover canonical IDs, anti-patterns, relationships, and failures. +- Registry parsing rejects duplicate IDs and dangling relation targets. +- Existing five published patterns validate without identity changes. + +--- + +# ADR-0004: Versioned CLI JSON contracts + +## Context + +Terminal prose is useful to people but brittle for automation and agent tools. Adding +fields without an envelope also prevents consumers from knowing which contract they +received. + +## Decision + +Commands with machine output emit a JSON document with `schemaVersion`, `kind`, and +command-specific payload. JSON mode writes no headings, colors, or success messages to +standard output. Diagnostic warnings go to standard error. Arrays use documented, +deterministic ordering. + +Existing human output stays the default. Existing commands remain, while clearer names +(`list`, `show`, `search`, `scan`, `suggest`) are additive aliases over the same core +use cases. + +## Consequences + +- Agents can consume CLI results without text scraping. +- Contract changes require deliberate versioning and fixtures. +- Reporter implementations and tests must preserve stdout/stderr separation. + +## Verification + +- JSON outputs validate against published schemas where one exists. +- Alias and original commands produce equivalent payloads. +- Snapshot tests assert deterministic ordering and absence of decoration. + +--- + +# ADR-0005: Static analysis before assisted analysis + +## Context + +Repository analysis can become invasive, expensive, and non-repeatable if it executes +project code, reads secrets, or uploads source to a model. Dependency manifests provide +a narrower but auditable first signal. + +## Decision + +The MVP scanner reads declared dependency manifests as data and never executes project +code. It records file-level evidence, numeric confidence, a derived certainty state, +the analyzers used, and limitations. Unsupported or absent evidence is `unknown`, not +proof that a capability is absent. + +Source, configuration, semantic, runtime, and LLM analyzers are separate future +adapters with explicit permissions and provenance. + +## Consequences + +- MVP scanning is fast, local, and safe by default. +- Results have false negatives and cannot verify implementations. +- Recommendation text must explain the evidence boundary. + +## Verification + +- Scanner tests use fixtures and make no network calls. +- Results list inspected files and analyzer limitations. +- Secret values are never included in output. + +--- + # MAP's own workspace This repository uses the same project structure generated by `map init`. The @@ -134,6 +267,37 @@ the curated, human-maintained picture. --- +# ADR-0006: MCP as a separate adapter + +## Context + +MCP can expose MAP knowledge to agents, but it introduces transport, lifecycle, +permissions, and compatibility concerns unrelated to the core domain. + +## Decision + +MCP is deferred from the deterministic MVP and will live in a separate adapter package. +It will call the same registry, graph, scanner, recommendation, and validation ports as +the CLI. The MCP layer may format or transport results but must not define alternate +pattern semantics. + +Initial MCP tools should be read-only. Any future mutation tool requires an explicit +threat model, path boundary, preview, and human approval policy. + +## Consequences + +- The core remains usable without an MCP runtime. +- CLI and MCP behavior can share contract tests. +- MCP delivery follows rather than blocks the MVP. + +## Verification + +- No MCP dependency exists in core packages. +- Future MCP results validate against the same public contracts as CLI JSON. +- Security review precedes any write-capable MCP tool. + +--- + # Decisions Architecture Decision Records (ADRs) for AI-related choices: RAG vs fine-tuning, diff --git a/CLAUDE.md b/CLAUDE.md index 4e7c049..d4843a8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -100,6 +100,139 @@ Generated files such as `AGENTS.md` are projections. Authors edit `.map/`, then --- +# ADR-0002: Framework-neutral deterministic core + +## Context + +MAP must describe systems built with many model providers, languages, and agent +frameworks. Binding the domain to one SDK would shorten an initial implementation but +make patterns, scanners, and recommendations obsolete when that SDK changes. Requiring +an LLM would also make baseline results non-repeatable and unavailable offline. + +## Decision + +Registry parsing, graph construction, validation, static scanning, and baseline +recommendation are pure or deterministic core capabilities. They MUST NOT depend on a +model provider, agent framework, remote service, or MCP runtime. + +Framework manifests, coding-agent formats, MCP, semantic indexes, and optional LLM +reasoning are adapters at explicit boundaries. Core types use MAP vocabulary and may +carry adapter evidence without importing adapter-specific types. + +## Consequences + +- Core commands work offline and are straightforward to test. +- Framework integrations can evolve independently. +- Some framework-specific insight will initially be less deep than a dedicated tool. +- Optional assisted output must be labeled and cannot replace deterministic evidence. + +## Verification + +- Core package dependency graphs contain no model SDK. +- Tests use fixed inputs and require no network. +- CLI JSON outputs identify limitations and remain stable for identical inputs. + +--- + +# ADR-0003: Stable pattern identity and schema + +## Context + +MAP already publishes and cross-references slash-form pattern IDs. Proposed examples +sometimes use dotted IDs, and the current YAML contract is described but not enforced. +A silent identifier migration would break links, commands, adopted patterns, and caches. + +## Decision + +Pattern Schema v1 uses canonical IDs matching `^[a-z0-9-]+/[a-z0-9-]+$`. A record has +an explicit `kind` (`pattern` or `anti-pattern`), lifecycle status, optional evidence +maturity, decision guidance, and typed relationships. Flat `related` input remains a +supported compatibility field and normalizes to `works_with` edges. + +Aliases may accept alternate spelling at input boundaries, but public output and graph +nodes return the canonical slash-form ID. Meaning-changing contract updates require a +new schema version and migration notes. + +## Consequences + +- Existing links and CLI workflows remain valid. +- Patterns and anti-patterns share validation and discovery infrastructure. +- Authors must distinguish publication status from evidence maturity. +- Compatibility normalization adds a small amount of registry-builder logic. + +## Verification + +- Schema fixtures cover canonical IDs, anti-patterns, relationships, and failures. +- Registry parsing rejects duplicate IDs and dangling relation targets. +- Existing five published patterns validate without identity changes. + +--- + +# ADR-0004: Versioned CLI JSON contracts + +## Context + +Terminal prose is useful to people but brittle for automation and agent tools. Adding +fields without an envelope also prevents consumers from knowing which contract they +received. + +## Decision + +Commands with machine output emit a JSON document with `schemaVersion`, `kind`, and +command-specific payload. JSON mode writes no headings, colors, or success messages to +standard output. Diagnostic warnings go to standard error. Arrays use documented, +deterministic ordering. + +Existing human output stays the default. Existing commands remain, while clearer names +(`list`, `show`, `search`, `scan`, `suggest`) are additive aliases over the same core +use cases. + +## Consequences + +- Agents can consume CLI results without text scraping. +- Contract changes require deliberate versioning and fixtures. +- Reporter implementations and tests must preserve stdout/stderr separation. + +## Verification + +- JSON outputs validate against published schemas where one exists. +- Alias and original commands produce equivalent payloads. +- Snapshot tests assert deterministic ordering and absence of decoration. + +--- + +# ADR-0005: Static analysis before assisted analysis + +## Context + +Repository analysis can become invasive, expensive, and non-repeatable if it executes +project code, reads secrets, or uploads source to a model. Dependency manifests provide +a narrower but auditable first signal. + +## Decision + +The MVP scanner reads declared dependency manifests as data and never executes project +code. It records file-level evidence, numeric confidence, a derived certainty state, +the analyzers used, and limitations. Unsupported or absent evidence is `unknown`, not +proof that a capability is absent. + +Source, configuration, semantic, runtime, and LLM analyzers are separate future +adapters with explicit permissions and provenance. + +## Consequences + +- MVP scanning is fast, local, and safe by default. +- Results have false negatives and cannot verify implementations. +- Recommendation text must explain the evidence boundary. + +## Verification + +- Scanner tests use fixtures and make no network calls. +- Results list inspected files and analyzer limitations. +- Secret values are never included in output. + +--- + # MAP's own workspace This repository uses the same project structure generated by `map init`. The @@ -134,6 +267,37 @@ the curated, human-maintained picture. --- +# ADR-0006: MCP as a separate adapter + +## Context + +MCP can expose MAP knowledge to agents, but it introduces transport, lifecycle, +permissions, and compatibility concerns unrelated to the core domain. + +## Decision + +MCP is deferred from the deterministic MVP and will live in a separate adapter package. +It will call the same registry, graph, scanner, recommendation, and validation ports as +the CLI. The MCP layer may format or transport results but must not define alternate +pattern semantics. + +Initial MCP tools should be read-only. Any future mutation tool requires an explicit +threat model, path boundary, preview, and human approval policy. + +## Consequences + +- The core remains usable without an MCP runtime. +- CLI and MCP behavior can share contract tests. +- MCP delivery follows rather than blocks the MVP. + +## Verification + +- No MCP dependency exists in core packages. +- Future MCP results validate against the same public contracts as CLI JSON. +- Security review precedes any write-capable MCP tool. + +--- + # Decisions Architecture Decision Records (ADRs) for AI-related choices: RAG vs fine-tuning, diff --git a/GEMINI.md b/GEMINI.md index 357ca2b..a139bf1 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -100,6 +100,139 @@ Generated files such as `AGENTS.md` are projections. Authors edit `.map/`, then --- +# ADR-0002: Framework-neutral deterministic core + +## Context + +MAP must describe systems built with many model providers, languages, and agent +frameworks. Binding the domain to one SDK would shorten an initial implementation but +make patterns, scanners, and recommendations obsolete when that SDK changes. Requiring +an LLM would also make baseline results non-repeatable and unavailable offline. + +## Decision + +Registry parsing, graph construction, validation, static scanning, and baseline +recommendation are pure or deterministic core capabilities. They MUST NOT depend on a +model provider, agent framework, remote service, or MCP runtime. + +Framework manifests, coding-agent formats, MCP, semantic indexes, and optional LLM +reasoning are adapters at explicit boundaries. Core types use MAP vocabulary and may +carry adapter evidence without importing adapter-specific types. + +## Consequences + +- Core commands work offline and are straightforward to test. +- Framework integrations can evolve independently. +- Some framework-specific insight will initially be less deep than a dedicated tool. +- Optional assisted output must be labeled and cannot replace deterministic evidence. + +## Verification + +- Core package dependency graphs contain no model SDK. +- Tests use fixed inputs and require no network. +- CLI JSON outputs identify limitations and remain stable for identical inputs. + +--- + +# ADR-0003: Stable pattern identity and schema + +## Context + +MAP already publishes and cross-references slash-form pattern IDs. Proposed examples +sometimes use dotted IDs, and the current YAML contract is described but not enforced. +A silent identifier migration would break links, commands, adopted patterns, and caches. + +## Decision + +Pattern Schema v1 uses canonical IDs matching `^[a-z0-9-]+/[a-z0-9-]+$`. A record has +an explicit `kind` (`pattern` or `anti-pattern`), lifecycle status, optional evidence +maturity, decision guidance, and typed relationships. Flat `related` input remains a +supported compatibility field and normalizes to `works_with` edges. + +Aliases may accept alternate spelling at input boundaries, but public output and graph +nodes return the canonical slash-form ID. Meaning-changing contract updates require a +new schema version and migration notes. + +## Consequences + +- Existing links and CLI workflows remain valid. +- Patterns and anti-patterns share validation and discovery infrastructure. +- Authors must distinguish publication status from evidence maturity. +- Compatibility normalization adds a small amount of registry-builder logic. + +## Verification + +- Schema fixtures cover canonical IDs, anti-patterns, relationships, and failures. +- Registry parsing rejects duplicate IDs and dangling relation targets. +- Existing five published patterns validate without identity changes. + +--- + +# ADR-0004: Versioned CLI JSON contracts + +## Context + +Terminal prose is useful to people but brittle for automation and agent tools. Adding +fields without an envelope also prevents consumers from knowing which contract they +received. + +## Decision + +Commands with machine output emit a JSON document with `schemaVersion`, `kind`, and +command-specific payload. JSON mode writes no headings, colors, or success messages to +standard output. Diagnostic warnings go to standard error. Arrays use documented, +deterministic ordering. + +Existing human output stays the default. Existing commands remain, while clearer names +(`list`, `show`, `search`, `scan`, `suggest`) are additive aliases over the same core +use cases. + +## Consequences + +- Agents can consume CLI results without text scraping. +- Contract changes require deliberate versioning and fixtures. +- Reporter implementations and tests must preserve stdout/stderr separation. + +## Verification + +- JSON outputs validate against published schemas where one exists. +- Alias and original commands produce equivalent payloads. +- Snapshot tests assert deterministic ordering and absence of decoration. + +--- + +# ADR-0005: Static analysis before assisted analysis + +## Context + +Repository analysis can become invasive, expensive, and non-repeatable if it executes +project code, reads secrets, or uploads source to a model. Dependency manifests provide +a narrower but auditable first signal. + +## Decision + +The MVP scanner reads declared dependency manifests as data and never executes project +code. It records file-level evidence, numeric confidence, a derived certainty state, +the analyzers used, and limitations. Unsupported or absent evidence is `unknown`, not +proof that a capability is absent. + +Source, configuration, semantic, runtime, and LLM analyzers are separate future +adapters with explicit permissions and provenance. + +## Consequences + +- MVP scanning is fast, local, and safe by default. +- Results have false negatives and cannot verify implementations. +- Recommendation text must explain the evidence boundary. + +## Verification + +- Scanner tests use fixtures and make no network calls. +- Results list inspected files and analyzer limitations. +- Secret values are never included in output. + +--- + # MAP's own workspace This repository uses the same project structure generated by `map init`. The @@ -134,6 +267,37 @@ the curated, human-maintained picture. --- +# ADR-0006: MCP as a separate adapter + +## Context + +MCP can expose MAP knowledge to agents, but it introduces transport, lifecycle, +permissions, and compatibility concerns unrelated to the core domain. + +## Decision + +MCP is deferred from the deterministic MVP and will live in a separate adapter package. +It will call the same registry, graph, scanner, recommendation, and validation ports as +the CLI. The MCP layer may format or transport results but must not define alternate +pattern semantics. + +Initial MCP tools should be read-only. Any future mutation tool requires an explicit +threat model, path boundary, preview, and human approval policy. + +## Consequences + +- The core remains usable without an MCP runtime. +- CLI and MCP behavior can share contract tests. +- MCP delivery follows rather than blocks the MVP. + +## Verification + +- No MCP dependency exists in core packages. +- Future MCP results validate against the same public contracts as CLI JSON. +- Security review precedes any write-capable MCP tool. + +--- + # Decisions Architecture Decision Records (ADRs) for AI-related choices: RAG vs fine-tuning, diff --git a/docs/architecture/CLI.md b/docs/architecture/CLI.md new file mode 100644 index 0000000..2d83e2f --- /dev/null +++ b/docs/architecture/CLI.md @@ -0,0 +1,32 @@ +# CLI architecture + +The CLI is a delivery adapter over application services. Commands parse input, invoke +a service, and report a result; they do not embed registry, graph, scan, or +recommendation policy. + +## Vocabulary and compatibility + +| Preferred workflow | Compatible existing command | +|---|---| +| `map list` | `map patterns` without a query | +| `map search ` | `map patterns ` | +| `map show ` | `map explain ` | +| `map scan [path]` | `map analyze [path]` | +| `map suggest [path]` | `map recommend [path]` | + +`init`, `add`, `sync`, `watch`, `optimize`, `doctor`, and `update` retain their current +names. `graph` and `validate` are first-class MVP commands. `diff` remains explicitly +planned until its comparison contract exists. + +## Output + +Human-readable text is the default. Commands supporting `--json` emit one versioned +JSON document and no decorative text on stdout. Errors use nonzero exit status; +warnings and fallback notices use stderr. Stable ordering makes output diffable. + +## Exit behavior + +- `0`: command completed, including a valid empty result. +- `1`: validation, input, or operational failure. +- Parser-specific usage errors retain the argument parser's nonzero status. + diff --git a/docs/architecture/MCP.md b/docs/architecture/MCP.md new file mode 100644 index 0000000..5565675 --- /dev/null +++ b/docs/architecture/MCP.md @@ -0,0 +1,16 @@ +# MCP adapter + +MCP is a later delivery adapter, not part of the deterministic MVP. It will expose the +same application ports and JSON contracts as the CLI. + +Candidate read-only tools are `list_patterns`, `show_pattern`, `search_patterns`, +`scan_project`, `suggest_patterns`, `inspect_graph`, and `validate_map`. Inputs must be +bounded to an approved workspace, results must carry schema versions, and transport +metadata must remain outside core domain objects. + +Write tools are not assumed. Adding one requires a separate ADR covering authorization, +preview, path traversal, overwrite behavior, audit trail, and human approval. The core +must remain installable and testable without MCP dependencies. + +See [ADR-0006](../../.map/decisions/0006-mcp-as-a-separate-adapter.md). + diff --git a/docs/architecture/PATTERN_GRAPH.md b/docs/architecture/PATTERN_GRAPH.md new file mode 100644 index 0000000..0977fe4 --- /dev/null +++ b/docs/architecture/PATTERN_GRAPH.md @@ -0,0 +1,30 @@ +# Pattern graph + +The graph is a deterministic projection of registry records. Every catalog entry is a +node. Every valid typed relationship is a directed edge. + +## Edge vocabulary + +| Type | Meaning | Symmetric? | +|---|---|---| +| `depends_on` | Source normally requires target to function correctly | No | +| `works_with` | Source is commonly composed with target | Conceptually yes; stored direction is preserved | +| `alternative_to` | Target addresses a similar decision with different forces | Conceptually yes | +| `extends` | Source specializes or adds capability to target | No | +| `conflicts_with` | Combining source and target creates a known conflict | Conceptually yes | +| `solves` | Source addresses a named anti-pattern or problem node | No | + +Relations are claims and may include a note and evidence references. CI rejects an +edge whose source or target is not in the registry. Duplicate edges normalize by +`from`, `type`, and `to`; ordering is lexical for stable output. + +In schema version 1, legacy `related` values become `works_with` edges. This is a +compatibility approximation and must not be presented as stronger semantics than the +author supplied. + +## Queries + +The MVP supports listing graph statistics and inspecting outgoing edges for a node. +Later queries may add incoming edges, paths, compatibility checks, and subgraphs, but +must return the same node and edge vocabulary. + diff --git a/docs/architecture/PATTERN_MODEL.md b/docs/architecture/PATTERN_MODEL.md new file mode 100644 index 0000000..ba3175e --- /dev/null +++ b/docs/architecture/PATTERN_MODEL.md @@ -0,0 +1,39 @@ +# Pattern model + +A pattern is a decision record packaged for discovery, comparison, implementation, +and verification. An anti-pattern uses the same base contract because it needs the +same identity, context, evidence, relations, and lifecycle. + +## Identity and lifecycle + +- `id`: immutable `category/slug` identity in schema version 1. +- `kind`: `pattern` or `anti-pattern`. +- `status`: editorial publication state; initially `planned`, `in-progress`, or + `published`. +- `maturity`: field-evidence state, independent from publication. Existing values + (`emerging`, `established`, `declining`) remain valid until a separately evidenced + lifecycle change. +- `version`: version of the pattern content, not the registry or schema. + +## Decision guidance + +Published patterns provide a summary, problem, when-to-use and when-not-to-use +conditions, trade-offs or failure modes, references, implementation guidance, and +acceptance criteria. Structured metadata is concise and points to the complete human +document rather than duplicating every paragraph. + +## Evidence + +Evidence is a source claim with provenance and optional retrieval date. Maturity and +benchmarks must cite evidence. MAP does not treat popularity, a vendor assertion, or +an LLM-generated statement as independent validation. + +## Compatibility + +Existing `pattern.yaml` records remain valid. Missing `kind` normalizes to `pattern`. +Existing flat `related` entries normalize to typed `works_with` edges. Serializers may +emit normalized fields, but consumers accept the compatibility form for all v1 data. + +The normative shape is defined by +[`PATTERN_SCHEMA.md`](../specifications/PATTERN_SCHEMA.md). + diff --git a/docs/architecture/README.md b/docs/architecture/README.md new file mode 100644 index 0000000..5f1d26a --- /dev/null +++ b/docs/architecture/README.md @@ -0,0 +1,43 @@ +# Architecture + +MAP separates durable domain knowledge from delivery mechanisms. The pattern library, +registry contracts, graph, scanner results, recommendations, and verification results +form the core. The CLI, website, coding-agent compilers, future MCP server, framework +mappings, and optional assisted analysis are adapters. + +```text + authors / maintainers + | + Markdown + pattern.yaml + v + schema + registry builder + | + versioned registry + / | \ + v v v + catalog graph recommender + \ | / + \ v / + application ports + / | | \ + CLI website agents MCP (later) + +project files -> scanner adapters -> scan result -> recommendations +.map/ source -> compiler adapters -> agent-specific projections +``` + +## Documents + +- [System architecture](SYSTEM_ARCHITECTURE.md) +- [Pattern model](PATTERN_MODEL.md) +- [Pattern graph](PATTERN_GRAPH.md) +- [Scanner](SCANNER.md) +- [Recommendation engine](RECOMMENDATION_ENGINE.md) +- [Verification engine](VERIFICATION_ENGINE.md) +- [CLI](CLI.md) +- [MCP adapter](MCP.md) +- [Security](SECURITY.md) + +Accepted decisions live in [`.map/decisions`](../../.map/decisions/). Product scope +and delivery order live in [`docs/project`](../project/). + diff --git a/docs/architecture/RECOMMENDATION_ENGINE.md b/docs/architecture/RECOMMENDATION_ENGINE.md new file mode 100644 index 0000000..9d5cc3e --- /dev/null +++ b/docs/architecture/RECOMMENDATION_ENGINE.md @@ -0,0 +1,29 @@ +# Recommendation engine + +The MVP recommender answers: given observed concepts, which published or planned MAP +patterns deserve review, and why? + +Rules are declarative data. A rule lists triggering concepts, concepts whose presence +suppresses it, suggested pattern IDs, priority, and rationale. The engine matches, +deduplicates by pattern, retains the highest priority, unions triggers, and orders by +priority then ID. + +## Explanation contract + +Every suggestion includes: + +- canonical pattern ID and priority; +- human rationale; +- triggering detections; +- supporting evidence references where available; +- limitations inherited from the scan; +- graph context when an explicit relation supports the suggestion. + +A suggestion is advisory. It does not assert that the pattern is absent, suitable, or +implemented, and it never changes project files. An empty scan returns no suggestions +rather than generic advice. + +Future ranking may use declared project intent, verified adopted patterns, and optional +evaluation-backed assisted adapters. Deterministic rules remain available as the +baseline. + diff --git a/docs/architecture/SCANNER.md b/docs/architecture/SCANNER.md new file mode 100644 index 0000000..79b0057 --- /dev/null +++ b/docs/architecture/SCANNER.md @@ -0,0 +1,32 @@ +# Scanner + +The scanner converts static project evidence into a versioned description of detected +AI architecture concepts. It is an observation mechanism, not an implementation +verifier. + +## MVP adapter + +The dependency-manifest adapter reads `package.json`, `requirements.txt`, +`pyproject.toml`, `go.mod`, and `Cargo.toml` at the selected root. It parses them as +data and matches declared dependency names against a reviewed signal table. + +It does not execute package scripts, resolve dependency trees, read environment values, +inspect source code, or contact registries. Monorepo traversal is deferred until path, +ignore, and duplicate-evidence behavior are specified. + +## Result semantics + +Each detection contains a MAP concept, numeric confidence, derived certainty, and +file-level evidence. Certainty maps as follows: + +| Confidence | Certainty | Interpretation | +|---|---|---| +| `>= 0.85` | `detected` | Direct, strong static signal | +| `>= 0.60` | `likely` | Useful but not conclusive signal | +| lower or unavailable | `unknown` | Insufficient support; never equivalent to absent | + +The result also names analyzers, inspected inputs, and limitations. Consumers may use +raw confidence for ordering but must show certainty and evidence when making claims. + +The wire contract is [`SCAN_RESULT.md`](../specifications/SCAN_RESULT.md). + diff --git a/docs/architecture/SECURITY.md b/docs/architecture/SECURITY.md new file mode 100644 index 0000000..c32a926 --- /dev/null +++ b/docs/architecture/SECURITY.md @@ -0,0 +1,36 @@ +# Security architecture + +## Assets and trust boundaries + +MAP handles repository paths, documentation, dependency manifests, generated agent +instructions, registry caches, and future adapter inputs. Repository content and +registry downloads are untrusted data. Agent instruction text can influence downstream +tools even when it is not executable by MAP. + +## MVP controls + +- Static scanners read allowlisted manifest names and do not execute repository code. +- Scanner output records dependency names and file paths, never secret values. +- File operations resolve under an explicit project root and preserve existing files + unless the command contract authorizes overwrite. +- Registry parsing validates shape, schema version, unique IDs, and references. +- Cache corruption degrades to a bundled snapshot with a warning. +- Generated target files are projections from reviewable `.map/` sources. +- Core commands work without network access or credentials. +- Dependencies are pinned through the lockfile and checked by CI and security audit. + +## Threats requiring continued review + +| Threat | Mitigation direction | +|---|---| +| Path traversal in pattern IDs or output paths | Restrictive ID grammar, path containment checks, fixtures | +| Malicious prompt text in a pattern | Provenance, human review, clear source boundaries; never execute text | +| Registry substitution or downgrade | Schema version, source reporting, future integrity metadata | +| Secret disclosure by new analyzers | Allowlisted fields, redaction, tests, explicit permissions | +| Untrusted plugin execution | No executable third-party plugin loading in MVP | +| Agent writes through future MCP | Read-only first; separate threat model and approval policy | +| Denial of service from large inputs or graphs | File-size, node, edge, and traversal bounds in adapters | + +Security reports follow the repository security policy. A new analyzer or write-capable +adapter must document its inputs, permissions, data retention, and failure behavior. + diff --git a/docs/architecture/SYSTEM_ARCHITECTURE.md b/docs/architecture/SYSTEM_ARCHITECTURE.md new file mode 100644 index 0000000..0365b4a --- /dev/null +++ b/docs/architecture/SYSTEM_ARCHITECTURE.md @@ -0,0 +1,59 @@ +# System architecture + +## Boundaries + +| Layer | Owns | Must not own | +|---|---|---| +| Domain | Pattern identity, relations, detections, recommendations, verification vocabulary | Filesystem, terminal, HTTP, model SDKs | +| Application | Use cases and ports for discovery, scan, suggest, graph, validate, compile | Framework-specific parsing or presentation | +| Infrastructure | Registry files, filesystem storage, static analyzers, caches | Alternate domain semantics | +| Delivery | CLI, website, coding-agent output, future MCP | Business rules duplicated from core | + +The TypeScript packages currently combine some application and infrastructure code; +the dependency direction is nevertheless the constraint for new work. A future +package split is optional and must not delay contract stabilization. + +## Source-of-truth model + +- `library/patterns/**` and `library/ROADMAP.md` author the public catalog. +- `library/dist/registry.json` is the generated release artifact. +- `tooling/packages/cli/registry-snapshot/registry.json` is the offline distribution + snapshot and must match the generated artifact at release time. +- `.map/**` is the canonical context for a project. +- root agent files and reports are derived outputs. + +## Primary flows + +### Knowledge publication + +An author changes a pattern and fixtures. CI validates Pattern Schema v1, builds a +registry, checks referential integrity, and makes the same artifact available to the +CLI and website. + +### Project analysis + +A delivery adapter selects a path. Scanner adapters inspect allowed static inputs and +return normalized detections. The application layer adds result metadata and limits. +The recommendation engine evaluates fixed rules and graph context. It never changes +the target project. + +### Project context compilation + +The compiler reads `.map` documents, applies target selection and token policies, and +writes projections for supported coding agents. It does not infer new project rules. + +## Extension rules + +New integrations implement ports, declare capabilities and limitations, and return +core contracts. Core packages do not import an adapter. Extension data uses namespaced +`x-` fields only where a schema permits them. Untrusted executable plugins are outside +the MVP. + +## Failure model + +- Contract errors are fatal and include a location and expected rule. +- Unsupported input produces an `unknown` result or a no-applicable-analyzer message. +- A broken optional cache falls back to the bundled registry with a warning. +- Network failure cannot disable core offline commands. +- Partial evidence remains visible; it is never upgraded silently to certainty. + diff --git a/docs/architecture/VERIFICATION_ENGINE.md b/docs/architecture/VERIFICATION_ENGINE.md new file mode 100644 index 0000000..2f7b0b8 --- /dev/null +++ b/docs/architecture/VERIFICATION_ENGINE.md @@ -0,0 +1,27 @@ +# Verification engine + +Verification compares a declared MAP contract with observable evidence. It is distinct +from scanning: scanning discovers possible concepts, while verification evaluates a +specific claim or acceptance criterion. + +## MVP boundary + +The MVP validates structure and references: + +- pattern metadata conforms to Pattern Schema v1; +- IDs, categories, files, and graph targets are coherent; +- `.map/map.config.json` conforms to the project contract; +- adopted pattern metadata names a catalog entry and required files are present. + +This is contract verification, not proof that an application implements a pattern. + +## Future checks + +Later adapters may provide static source assertions, configuration assertions, test +execution, runtime evidence, and human attestations. Each check reports `pass`, `fail`, +`unknown`, or `not-applicable`, its method, evidence, limitations, and timestamp. +Failure to inspect is never converted into a pass. + +The planned wire contract is +[`VERIFICATION_RESULT.md`](../specifications/VERIFICATION_RESULT.md). + diff --git a/docs/project/GLOSSARY.md b/docs/project/GLOSSARY.md new file mode 100644 index 0000000..55ad88d --- /dev/null +++ b/docs/project/GLOSSARY.md @@ -0,0 +1,22 @@ +# Glossary + +| Term | Meaning | +|---|---| +| Pattern | A reusable architecture decision with context, forces, trade-offs, evidence, and verification guidance. | +| Anti-pattern | A recurring design that creates a documented failure mode; modeled like a pattern with `kind: anti-pattern`. | +| Pattern ID | Stable slash-form identifier: `category/slug`. | +| Catalog | All planned and published entries visible to discovery tools. | +| Registry | Versioned machine-readable artifact compiled from the library. | +| Graph | Patterns as nodes and typed relationships as directed edges. | +| Relation | A typed claim such as `depends_on`, `works_with`, or `conflicts_with`. | +| Evidence | A traceable observation supporting a detection, relation, maturity claim, or recommendation. | +| Signal | A static indicator found by a scanner, such as a declared dependency. | +| Detection | A concept inferred from one or more signals. | +| Certainty | `detected`, `likely`, or `unknown`; a summary of evidence strength, not probability of correctness. | +| Recommendation | A pattern suggestion with priority, reason, triggers, and limitations. | +| Verification | A check comparing declared intent or acceptance criteria with observable evidence. | +| `.map/` workspace | Canonical, versioned project memory consumed by MAP and compiled for tools. | +| Adapter | Boundary component translating a framework, host, manifest, or protocol into core MAP contracts. | +| Status | Publication lifecycle: `planned`, `in-progress`, `published`, or later deprecation states. | +| Maturity | Strength of field evidence for an approach; independent from publication status. | + diff --git a/docs/project/IMPLEMENTATION_PLAN.md b/docs/project/IMPLEMENTATION_PLAN.md new file mode 100644 index 0000000..8b691de --- /dev/null +++ b/docs/project/IMPLEMENTATION_PLAN.md @@ -0,0 +1,41 @@ +# Implementation plan + +Tracking issue: [#103](https://github.com/rajanbor/map/issues/103) + +## Workstream A — contracts + +1. Freeze vocabulary, compatibility, result envelopes, and security boundaries. +2. Ship Pattern Schema v1, scan-result, and recommendation-result schemas. +3. Extend shared TypeScript types and parsers from those contracts. + +Exit: schemas have guides, complete valid examples, invalid fixtures, and CI coverage. + +## Workstream B — graph and registry + +1. Preserve flat `related` as compatible author input. +2. Normalize it to typed `works_with` edges while accepting explicit typed relations. +3. Build the runtime graph from registry data and reject dangling edges. +4. Expose deterministic text and JSON graph queries. + +Exit: every registry entry is a graph node and graph output is stable. + +## Workstream C — CLI workflow + +1. Add compatible discovery aliases: `list`, `search`, `show`, `scan`, `suggest`. +2. Add JSON scan and recommendation envelopes. +3. Add certainty and limitation reporting without changing raw confidence. +4. Add `validate` for public MAP artifacts. + +Exit: the acceptance scenario in `MVP.md` passes locally and in CI. + +## Workstream D — dogfood and release readiness + +1. Refresh the bundled registry and fail CI when it drifts. +2. Scan MAP's tooling workspace and retain a sanitized example result. +3. Update README, changelog, command reference, roadmap, and implementation report. +4. Run registry/schema validation, build, lint, typecheck, tests, audit, installer, and + CLI smoke tests. + +Exit: the consolidated repository tells one accurate story and the MVP is reproducible +from a clean clone. + diff --git a/docs/project/MISSION.md b/docs/project/MISSION.md new file mode 100644 index 0000000..dbdb65b --- /dev/null +++ b/docs/project/MISSION.md @@ -0,0 +1,14 @@ +# Mission + +MAP gives teams a framework-neutral pattern library, a durable `.map/` project memory, +and deterministic tools that connect declared architecture with repository evidence. + +We do this by: + +- documenting reusable AI patterns and anti-patterns with explicit trade-offs; +- publishing versioned contracts that humans and software can read; +- detecting architecture signals without requiring a model or network service; +- producing explainable recommendations rather than opaque scores; +- compiling one canonical project context into the formats used by coding agents; +- keeping optional framework, MCP, semantic, and LLM integrations at the edges. + diff --git a/docs/project/MVP.md b/docs/project/MVP.md new file mode 100644 index 0000000..8261ef6 --- /dev/null +++ b/docs/project/MVP.md @@ -0,0 +1,42 @@ +# MVP + +## Included + +- Pattern Schema v1 and typed relationship vocabulary. +- Registry compatibility with current `category/slug` IDs and flat `related` input. +- Deterministic catalog commands: `list`, `search`, and `show` plus existing aliases. +- Static dependency-manifest scanning through `scan` and existing `analyze`. +- Versioned JSON scan results with evidence, certainty, and limitations. +- Explainable rule-based suggestions through `suggest` and existing `recommend`. +- Versioned JSON recommendation results. +- A working graph command over registry nodes and relationships. +- Validation of repository pattern metadata and initialized `.map` project manifests. +- GitHub-only install, offline bundled catalog, tests, documentation, and dogfooding. + +## Explicitly deferred + +- Source-code AST and semantic scanners. +- Runtime telemetry ingestion and automated implementation verification. +- MCP server and remote registry API. +- LLM-assisted inference, natural-language graph queries, and auto-remediation. +- Executable third-party plugin loading. +- A stable npm distribution promise. + +## Acceptance scenario + +Given a local JavaScript or Python AI project, a user can run: + +```bash +map init +map scan . --json +map suggest . --json +map search retrieval +map show retrieval/chunking --json +map graph retrieval/chunking --json +map validate +map sync +``` + +All commands run without an LLM. Output identifies the registry or result schema +version, and existing command names still produce their established text behavior. + diff --git a/docs/project/NON_GOALS.md b/docs/project/NON_GOALS.md new file mode 100644 index 0000000..eba3c81 --- /dev/null +++ b/docs/project/NON_GOALS.md @@ -0,0 +1,17 @@ +# Non-goals + +MAP is not: + +- an agent framework, model SDK, orchestration runtime, or hosted inference service; +- a replacement for source control, issue tracking, observability, or evaluation + platforms; +- an automatic architecture authority that applies changes without human review; +- a benchmark that declares one framework or model universally best; +- an LLM-dependent scanner or a system that uploads source code by default; +- a package manager for arbitrary executable plugins; +- a guarantee that absence of a static signal means absence of a capability; +- a place for undocumented vendor promotion or maturity claims without evidence. + +MCP, source-level semantic analysis, hosted collaboration, and LLM-assisted reasoning +are valid future adapters, but they are outside the deterministic MVP core. + diff --git a/docs/project/PRINCIPLES.md b/docs/project/PRINCIPLES.md new file mode 100644 index 0000000..acb0022 --- /dev/null +++ b/docs/project/PRINCIPLES.md @@ -0,0 +1,23 @@ +# Product and engineering principles + +1. **Framework neutral.** Core concepts describe architecture. Vendor and framework + knowledge belongs in replaceable adapters. +2. **Deterministic first.** Registry, validation, scanning, graph queries, and baseline + recommendations work offline and return repeatable results. +3. **Evidence before claims.** Every detection and recommendation identifies its + evidence, limits, and reason. Unknown is not treated as absent. +4. **Human and AI readable.** Structured fields carry identity and constraints; prose + carries context, trade-offs, and examples. +5. **Decisions over recipes.** A useful pattern says when to use it, when not to, and + what it costs—not only how to implement it. +6. **Stable core, adaptable edges.** Public contracts evolve by version. Adapters may + move quickly without leaking their dependencies into the domain. +7. **Git-native and reviewable.** `.map/` is source, generated files are projections, + and meaningful changes are visible in ordinary review. +8. **Safe by default.** Scanners avoid secrets and code execution; recommendations do + not mutate projects; generated content never silently overwrites user work. +9. **Progressive adoption.** A team can start with one command or one pattern and grow + into manifests, decisions, verification, and integrations. +10. **Compatibility is a feature.** Existing commands, workspace layouts, and v1 + pattern identifiers remain usable across additive releases. + diff --git a/docs/project/PRODUCT_SPEC.md b/docs/project/PRODUCT_SPEC.md new file mode 100644 index 0000000..9a938e1 --- /dev/null +++ b/docs/project/PRODUCT_SPEC.md @@ -0,0 +1,59 @@ +# Product specification + +## Problem + +AI architecture intent is scattered across source code, prompts, vendor settings, +chat history, and tribal knowledge. Humans struggle to compare designs, while agents +guess project rules from incomplete context. Existing tools usually bind their model +to a particular framework or require a remote model to interpret the repository. + +## Users and jobs + +- **AI engineer:** discover a suitable pattern, inspect trade-offs, adopt it, and + verify the implementation. +- **Architect or tech lead:** review declared decisions and compare them with detected + evidence and known risks. +- **Coding agent:** consume stable JSON and Markdown contracts without scraping prose. +- **Pattern maintainer:** publish evidence-backed knowledge once for the CLI, website, + agents, and future protocol adapters. + +## Product loop + +```text +discover -> show -> scan -> suggest -> adopt -> sync -> validate -> verify +``` + +The MVP implements discovery, display, dependency-based scanning, explainable +suggestions, adoption, compilation, contract validation, and graph inspection. +Verification starts with contract and acceptance-data validation; deeper source and +runtime checks follow later. + +## Functional requirements + +1. A versioned pattern contract supports human guidance and machine fields. +2. Registry data exposes stable IDs, lifecycle, categories, and typed relationships. +3. The CLI lists, searches, and shows patterns in text and JSON. +4. The scanner returns evidence, confidence, certainty, and explicit limitations. +5. The recommendation engine is deterministic and explains every suggestion. +6. The graph can be inspected as nodes and typed edges with no dangling targets. +7. `map validate` checks structured MAP artifacts without executing project code. +8. Existing `patterns`, `explain`, `analyze`, and `recommend` workflows remain valid. +9. Core behavior works offline from the bundled registry snapshot. + +## Quality attributes + +- Same input and registry version produce equivalent ordered results. +- JSON output is versioned and contains no terminal decoration. +- A malformed contract fails with an actionable path and message. +- Scanning does not read secret values, execute repository code, or make network calls. +- Extension fields are explicit; unknown core fields fail validation. +- Documentation describes current behavior separately from roadmap behavior. + +## Success measures + +- A new user can install from GitHub, initialize a project, scan it, receive a reasoned + recommendation, inspect a pattern, and compile agent instructions. +- CI validates every public schema with valid and invalid fixtures. +- MAP can scan its own tooling workspace and produce a stable JSON report. +- The README never advertises a distribution path that does not exist. + diff --git a/docs/project/ROADMAP.md b/docs/project/ROADMAP.md new file mode 100644 index 0000000..619b390 --- /dev/null +++ b/docs/project/ROADMAP.md @@ -0,0 +1,42 @@ +# Product roadmap + +This roadmap describes capabilities. The pattern publication backlog remains in +[`library/ROADMAP.md`](../../library/ROADMAP.md). + +## 0 — Baseline (complete) + +- Consolidate library, tooling, website, and `.map` workspace. +- Repair dependency alerts and verify installation from GitHub. +- Record the repository audit and working baseline. + +## 1 — Contracts and deterministic MVP + +- Publish product, architecture, security, specification, and ADR documents. +- Add Pattern Schema v1 with fixtures and registry integration. +- Define stable scan and recommendation result schemas. +- Connect the pattern graph and expose compatible CLI vocabulary. +- Validate and dogfood the end-to-end local workflow. + +## 2 — Evidence and verification + +- Add recursive workspace discovery and configurable source analyzers. +- Model declared project intent and adopted-pattern verification. +- Add architecture diff, verification reports, and CI policy levels. +- Expand evidence provenance and pattern lifecycle governance. + +## 3 — Ecosystem adapters + +- Publish a protocol-neutral core API. +- Add an MCP adapter as a separate package. +- Define safe adapter and plugin discovery without executing untrusted code. +- Add framework mappings that never become the canonical pattern model. + +## 4 — Assisted intelligence + +- Optional semantic indexing and LLM-assisted explanations. +- Evaluation-backed recommendation ranking. +- Human-approved remediation plans and architecture review workflows. + +Each phase must preserve deterministic offline behavior as the baseline and may add +assisted behavior only as an explicit adapter. + diff --git a/docs/project/VISION.md b/docs/project/VISION.md new file mode 100644 index 0000000..657ef40 --- /dev/null +++ b/docs/project/VISION.md @@ -0,0 +1,13 @@ +# Vision + +MAP is the open architecture layer for AI engineering: a shared, executable language +for describing what an AI system does, why its design was chosen, which risks remain, +and how people or agents can verify it. + +A mature MAP project can be understood without knowing its framework. A developer can +inspect its decisions and patterns, an agent can consume the same contracts, and a +tool can scan the implementation and explain evidence-backed gaps. The knowledge stays +portable when model vendors, SDKs, and agent hosts change. + +MAP succeeds when architecture intent is as reviewable and automatable as source code. + diff --git a/docs/specifications/MAP_MANIFEST.md b/docs/specifications/MAP_MANIFEST.md new file mode 100644 index 0000000..87a7f0e --- /dev/null +++ b/docs/specifications/MAP_MANIFEST.md @@ -0,0 +1,31 @@ +# MAP project manifest + +The project manifest is `.map/map.config.json`. It records workspace contract version, +project identity, analysis boundaries, registry source, tool policy, source selection, +and compiler targets. The current manifest version is `3` and MAP spec version is +`0.1`. + +```json +{ + "version": 3, + "specVersion": "0.1", + "project": { + "name": "example", + "createdAt": "2026-09-13T00:00:00.000Z", + "languages": ["typescript"] + }, + "analysis": { + "analyzers": [], + "include": ["src/**"], + "exclude": ["**/node_modules/**", "**/dist/**", "**/.map/**"] + }, + "registry": { "source": "default" }, + "sources": ["**/*.md"], + "targets": { "agents": { "output": "AGENTS.md" } } +} +``` + +Paths are relative to the project root and MUST NOT escape it. Empty analyzer lists +mean the safe defaults. Unknown manifest versions fail with a migration message rather +than being guessed. Existing version 3 workspaces remain canonical for the MVP. + diff --git a/docs/specifications/PATTERN_SCHEMA.md b/docs/specifications/PATTERN_SCHEMA.md new file mode 100644 index 0000000..816bff9 --- /dev/null +++ b/docs/specifications/PATTERN_SCHEMA.md @@ -0,0 +1,49 @@ +# Pattern Schema v1 + +Pattern Schema v1 validates the structured identity and decision metadata in +`pattern.yaml`. JSON Schema is authoritative; YAML is the authoring syntax. + +## Required fields + +| Field | Meaning | +|---|---| +| `id` | Stable `category/slug` identifier | +| `name` | Human display name | +| `category` | Catalog category matching the ID and directory | +| `summary` | Concise statement of the decision or failure mode | +| `when_to_use` | Conditions supporting adoption; non-empty for a pattern | +| `when_not_to_use` | Conditions arguing against adoption; non-empty | +| `score` | Five MAP Score dimensions, each integer 1–5 | + +`kind` defaults to `pattern` for compatibility. `maturity`, aliases, references, +typed `relations`, and legacy `related` are optional. `related` normalizes to +`works_with`; new authoring SHOULD use typed relations once tooling support ships. + +```yaml +id: retrieval/chunking +kind: pattern +name: Chunking +category: retrieval +summary: Split source material into retrievable units with preserved context. +maturity: established +when_to_use: + - Documents exceed the useful retrieval or model context size. +when_not_to_use: + - The complete source already fits and must be reasoned over as a whole. +relations: + - type: works_with + target: retrieval/hybrid-search + note: Hybrid search operates over the resulting chunks. +score: + complexity: 2 + latency: 2 + cost: 2 + accuracyImpact: 4 + productionReadiness: 5 +references: + - https://example.com/evidence +``` + +Unknown core fields fail validation. Extension fields require an explicitly supported +`x-` container in a future schema revision; arbitrary keys are not accepted in v1. + diff --git a/docs/specifications/PATTERN_SPEC.md b/docs/specifications/PATTERN_SPEC.md new file mode 100644 index 0000000..66af063 --- /dev/null +++ b/docs/specifications/PATTERN_SPEC.md @@ -0,0 +1,27 @@ +# Pattern specification v1 + +Status: MVP contract +Normative schema: `library/schemas/pattern.schema.json` + +A published pattern directory is `library/patterns///` and contains: + +```text +README.md complete human guide and trade-offs +pattern.yaml structured metadata validated by Pattern Schema v1 +prompt.md implementation brief for a coding agent or developer +acceptance.md verifiable acceptance criteria +diagram.mmd source architecture diagram +``` + +The directory path, `id`, and `category` MUST agree. A pattern MUST be useful without +its prompt and MUST remain understandable without executing code. References support +claims; they do not replace the explanation. + +`README.md` SHOULD cover problem, context, decision forces, when to use, when not to +use, flow, trade-offs, failure modes, implementation guidance, verification, related +patterns, and references. An anti-pattern uses the same structure but explains the +harmful recurring design and safer alternatives. + +Compatibility rules and typed relation semantics are defined in +[`PATTERN_SCHEMA.md`](PATTERN_SCHEMA.md). + diff --git a/docs/specifications/RECOMMENDATION_RESULT.md b/docs/specifications/RECOMMENDATION_RESULT.md new file mode 100644 index 0000000..335f35d --- /dev/null +++ b/docs/specifications/RECOMMENDATION_RESULT.md @@ -0,0 +1,28 @@ +# Recommendation result v1 + +Normative schema: `library/schemas/recommendation-result.schema.json` + +```json +{ + "schemaVersion": 1, + "kind": "map.recommendation-result", + "scan": { + "root": "/workspace/example", + "detectedAt": "2026-09-13T00:00:00.000Z" + }, + "recommendations": [{ + "pattern": "security/least-privilege-tool-access", + "priority": "high", + "rationale": "The model can invoke tools; each tool should expose only the narrowest capability it needs.", + "triggeredBy": ["tool_calling"] + }], + "limitations": [ + "Recommendations infer review candidates from static signals; they do not prove a pattern is absent." + ] +} +``` + +Recommendations sort by `high`, `medium`, `low`, then canonical pattern ID. Every item +has a rationale and at least one trigger. An empty recommendation list is a successful +result, not proof that the architecture is complete. + diff --git a/docs/specifications/SCAN_RESULT.md b/docs/specifications/SCAN_RESULT.md new file mode 100644 index 0000000..2474a18 --- /dev/null +++ b/docs/specifications/SCAN_RESULT.md @@ -0,0 +1,31 @@ +# Scan result v1 + +Normative schema: `library/schemas/scan-result.schema.json` + +A scan result is one JSON document: + +```json +{ + "schemaVersion": 1, + "kind": "map.scan-result", + "root": "/workspace/example", + "detectedAt": "2026-09-13T00:00:00.000Z", + "analyzers": ["dependency-manifest"], + "inspected": ["package.json"], + "concepts": [{ + "concept": "tool_calling", + "confidence": 0.95, + "certainty": "detected", + "evidence": ["package.json: @modelcontextprotocol/sdk"] + }], + "limitations": [ + "Dependency manifests indicate declared packages, not whether or how code uses them." + ] +} +``` + +`concepts`, `analyzers`, `inspected`, and `evidence` use deterministic ordering. +`detectedAt` is observational metadata and is expected to differ between runs. Paths +may be absolute for local CLI output; retained examples and telemetry MUST sanitize +user-specific roots. + diff --git a/docs/specifications/VERIFICATION_RESULT.md b/docs/specifications/VERIFICATION_RESULT.md new file mode 100644 index 0000000..93766de --- /dev/null +++ b/docs/specifications/VERIFICATION_RESULT.md @@ -0,0 +1,32 @@ +# Verification result v1 design + +Status: planned after structural validation MVP. + +A verification result will identify the declared subject, check method, outcome, +evidence, limitations, and time. Outcomes are: + +- `pass`: the bounded check observed the required condition; +- `fail`: the bounded check observed a contradiction; +- `unknown`: evidence was insufficient or inspection failed; +- `not-applicable`: the criterion does not apply in this context. + +```json +{ + "schemaVersion": 1, + "kind": "map.verification-result", + "subject": "retrieval/chunking", + "verifiedAt": "2026-09-13T00:00:00.000Z", + "checks": [{ + "id": "metadata-valid", + "method": "json-schema", + "outcome": "pass", + "evidence": ["library/patterns/retrieval/chunking/pattern.yaml"] + }], + "summary": { "pass": 1, "fail": 0, "unknown": 0, "notApplicable": 0 } +} +``` + +The MVP `map validate` command may report structural validation in human-readable +form before this wider verification contract becomes normative. It must not label +schema validity as implementation verification. + From f716d405dd5fadf851d81e48df78dd672414e937 Mon Sep 17 00:00:00 2001 From: 1norahc Date: Sun, 13 Sep 2026 14:55:45 +0200 Subject: [PATCH 2/2] fix: align MCP ADR priority with schema (#103) --- .map/decisions/0006-mcp-as-a-separate-adapter.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.map/decisions/0006-mcp-as-a-separate-adapter.md b/.map/decisions/0006-mcp-as-a-separate-adapter.md index a70bf33..4d3ac1a 100644 --- a/.map/decisions/0006-mcp-as-a-separate-adapter.md +++ b/.map/decisions/0006-mcp-as-a-separate-adapter.md @@ -6,7 +6,7 @@ status: accepted date: 2026-09-13 owners: [rajanbor] tags: [mcp, adapters, security] -priority: medium +priority: normal targets: [agents, claude, gemini, cursor, copilot] --- @@ -38,4 +38,3 @@ threat model, path boundary, preview, and human approval policy. - No MCP dependency exists in core packages. - Future MCP results validate against the same public contracts as CLI JSON. - Security review precedes any write-capable MCP tool. -