@adammcarter/use-cases 0.1.0

package/use-cases/mcp/surface.yml

@@ -0,0 +1,257 @@
+schema_version: 1
+feature:
+  id: mcp.surface
+  name: MCP wrapper
+  summary: Agent tool access that wraps the CLI contract without weakening write gates or approval boundaries.
+use_cases:
+  - id: mcp.surface.cli_contract_transport
+    title: MCP mirrors CLI contract
+    lifecycle: active
+    value_tier: critical
+    journey_role: golden
+    usage_frequency: common
+    tags:
+      - mcp
+      - cli-parity
+      - contract
+    source_refs:
+      - kind: file
+        path: docs/mcp.md
+      - kind: file
+        path: packages/mcp/src/tools.ts
+    actor: agent
+    intent: Return the same semantic envelopes as the CLI without reimplementing product logic.
+    preconditions:
+      - The CLI command exists and returns a structured envelope.
+    trigger: An agent calls the MCP tool equivalent of a CLI command.
+    scenarios:
+      - id: mcp.surface.cli_contract_transport.parity
+        kind: steps
+        steps:
+          - Run a CLI command.
+          - Run the equivalent MCP tool.
+          - Compare semantic result fields rather than transport details.
+    observable_outcomes:
+      - MCP output preserves command semantics.
+      - Core product logic remains in the CLI/core layer.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+      - host_surface: claude.cli
+        supported: true
+      - host_surface: copilot.cli
+        supported: true
+      - host_surface: opencode.cli
+        supported: true
+    verification_policy:
+      mode: requirements
+      requirements:
+        - evidence_kind: test_result
+          required_verifiers:
+            - script
+          minimum_count: 1
+    approval_policy:
+      mode: none
+  - id: mcp.surface.write_gating
+    title: MCP read-only default and explicit writes
+    lifecycle: active
+    value_tier: critical
+    journey_role: negative
+    usage_frequency: common
+    tags:
+      - mcp
+      - write-gate
+      - safety
+    source_refs:
+      - kind: file
+        path: docs/mcp.md
+      - kind: file
+        path: packages/mcp/src/index.ts
+    actor: agent
+    intent: Require explicit write permission and workspace roots for mutating MCP tools.
+    preconditions:
+      - MCP server is running in read-only or write-enabled mode.
+    trigger: An agent calls a mutating MCP tool.
+    scenarios:
+      - id: mcp.surface.write_gating.block
+        kind: steps
+        steps:
+          - Call a mutating MCP tool without write permission.
+          - Confirm the tool returns a structured refusal.
+          - Enable writes explicitly and repeat only inside the workspace root.
+    observable_outcomes:
+      - Read-only MCP sessions cannot mutate workspace records.
+      - Mutations are constrained to configured roots.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+      - host_surface: claude.cli
+        supported: true
+      - host_surface: copilot.cli
+        supported: true
+      - host_surface: opencode.cli
+        supported: true
+    verification_policy:
+      mode: requirements
+      requirements:
+        - evidence_kind: test_result
+          required_verifiers:
+            - script
+          minimum_count: 1
+    approval_policy:
+      mode: none
+  - id: mcp.surface.approval_request_only
+    title: MCP approval request only
+    lifecycle: active
+    value_tier: critical
+    journey_role: negative
+    usage_frequency: common
+    tags:
+      - mcp
+      - approval
+      - trust-boundary
+    source_refs:
+      - kind: file
+        path: docs/mcp.md
+      - kind: file
+        path: packages/mcp/src/tools.ts
+      - kind: file
+        path: packages/core/src/showcase/approvalAuthority.ts
+    actor: agent
+    intent: Let MCP request approval and suggest the trusted CLI path, but never write user approval.
+    preconditions:
+      - A showcase run has finished and user approval may be needed.
+    trigger: An agent calls the MCP approval request tool.
+    scenarios:
+      - id: mcp.surface.approval_request_only.boundary
+        kind: steps
+        steps:
+          - Call the approval request MCP tool.
+          - Confirm the tool returns a trusted CLI-mediated approval command.
+          - Confirm no user approval event is appended by MCP.
+    observable_outcomes:
+      - MCP cannot approve or reject on behalf of the user.
+      - The user-facing trusted path remains explicit.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+      - host_surface: claude.cli
+        supported: true
+      - host_surface: copilot.cli
+        supported: true
+      - host_surface: opencode.cli
+        supported: true
+    verification_policy:
+      mode: requirements
+      requirements:
+        - evidence_kind: test_result
+          required_verifiers:
+            - script
+          minimum_count: 1
+    approval_policy:
+      mode: none
+  - id: mcp.surface.domain_results_not_transport_failures
+    title: Domain-negative results stay structured
+    lifecycle: active
+    value_tier: supporting
+    journey_role: edge
+    usage_frequency: occasional
+    tags:
+      - mcp
+      - diagnostics
+      - envelope
+    source_refs:
+      - kind: file
+        path: docs/mcp.md
+      - kind: file
+        path: docs/adr/0005-p4-cli-contract.md
+      - kind: file
+        path: packages/mcp/src/tools.ts
+    actor: agent
+    intent: Return validation failures, warnings, and integrity gaps as structured command results.
+    preconditions:
+      - A domain command detects invalid matrix, partial evidence, or missing preconditions.
+    trigger: An MCP caller invokes a command that has domain-level diagnostics.
+    scenarios:
+      - id: mcp.surface.domain_results_not_transport_failures.envelope
+        kind: steps
+        steps:
+          - Call an MCP tool against damaged or incomplete input.
+          - Confirm transport remains successful when the tool can report diagnostics.
+          - Inspect the structured command envelope for domain outcome and diagnostics.
+    observable_outcomes:
+      - Agents receive actionable diagnostics instead of opaque transport failure.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+      - host_surface: claude.cli
+        supported: true
+      - host_surface: copilot.cli
+        supported: true
+      - host_surface: opencode.cli
+        supported: true
+    verification_policy:
+      mode: requirements
+      requirements:
+        - evidence_kind: test_result
+          required_verifiers:
+            - script
+          minimum_count: 1
+    approval_policy:
+      mode: none
+  - id: mcp.surface.declared_tool_schemas
+    title: MCP tools declare their real input parameters
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: common
+    tags:
+      - mcp
+      - schema
+      - discoverability
+    source_refs:
+      - kind: file
+        path: packages/mcp/src/tools.ts
+      - kind: file
+        path: tests/conformance/mcp/tool-input-schemas.test.ts
+    actor: agent
+    intent: Expose each MCP tool's real parameters in its input schema so an agent can discover them from the tool definition instead of reverse-engineering them from the CLI or tests.
+    preconditions:
+      - The MCP server is registered and its tools are listed by the host.
+    trigger: An agent inspects an MCP tool's input schema before calling it.
+    scenarios:
+      - id: mcp.surface.declared_tool_schemas.declared
+        kind: steps
+        steps:
+          - List the MCP tools and read a high-value tool's input schema.
+          - Confirm named parameters with descriptions are present.
+          - Call the tool and confirm the CLI-parity result is unchanged.
+    observable_outcomes:
+      - High-value tool input schemas declare their real named parameters with descriptions rather than only an open passthrough.
+      - repo stays required for workspace-scoped tools, and CLI-parity forwarding behaviour is unchanged.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+      - host_surface: claude.cli
+        supported: true
+    verification_policy:
+      mode: requirements
+      verifiers:
+        script:
+          kind: script
+          evidence_kind: test_result
+          command:
+            - pnpm
+            - -s
+            - vitest
+            - run
+            - tests/conformance/mcp/tool-input-schemas.test.ts
+          inputs:
+            - tests/conformance/mcp/tool-input-schemas.test.ts
+      requirements:
+        - evidence_kind: test_result
+          required_verifiers:
+            - script
+          minimum_count: 1
+    approval_policy:
+      mode: none

package/use-cases/mcp/wrapper.yml

@@ -0,0 +1,100 @@
+schema_version: 1
+feature:
+  id: mcp.wrapper
+  name: MCP wrapper
+  summary: MCP tools preserve the CLI envelope contract.
+use_cases:
+  - id: mcp.wrapper.parity
+    title: Compiled MCP stdio preserves generated-plan showcase parity
+    lifecycle: active
+    value_tier: core
+    journey_role: alternate
+    usage_frequency: common
+    tags:
+      - mcp
+      - cli
+    source_refs:
+      - kind: file
+        path: packages/mcp/src/tools.ts
+    actor: agent
+    intent: Use MCP without inventing separate showcase or approval behavior.
+    preconditions:
+      - The compiled MCP server can load the packaged core.
+    trigger: Agent runs a showcase through MCP stdio.
+    scenarios:
+      - id: mcp.wrapper.parity.cli
+        kind: steps
+        steps:
+          - Generate a showcase plan through MCP.
+          - Start from the generated plan file through compiled stdio MCP.
+          - Record observation, verdict, and finish through MCP.
+          - Request approval through MCP without appending approval.
+    observable_outcomes:
+      - MCP returns CLI envelopes
+      - records the same lifecycle events
+      - and keeps approval pending.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+    verification_policy:
+      mode: none
+    approval_policy:
+      mode: none
+  - id: mcp.use_case_mutation.safe
+    title: MCP safely mutates use-case rows through core policy
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: common
+    tags:
+      - mcp
+      - matrix
+      - mutation
+      - safety
+    source_refs:
+      - kind: file
+        path: packages/mcp/src/tools.ts
+      - kind: file
+        path: packages/core/src/useCases/mutateUseCaseMatrix.ts
+    actor: agent
+    intent: Add, update, or retire use-case rows from an MCP host without bypassing CLI-equivalent validation.
+    preconditions:
+      - The caller passes an explicit repo root.
+      - Write tools are called with allow_write true.
+      - The current use-case matrix is complete enough to mutate safely.
+    trigger: Agent calls use_case_upsert or use_case_remove through MCP.
+    scenarios:
+      - id: mcp.use_case_mutation.safe.upsert
+        kind: steps
+        steps:
+          - Call use_case_upsert with a target use-cases YAML file and one use_case object.
+          - Validate that the matrix remains complete after the write.
+      - id: mcp.use_case_mutation.safe.remove
+        kind: steps
+        steps:
+          - Call use_case_remove with a use-case id and removal reason.
+          - Confirm the row is marked lifecycle removed rather than physically deleted.
+      - id: mcp.use_case_mutation.safe.boundary
+        kind: steps
+        steps:
+          - Try a path escape, damaged matrix, or actor_type user claim.
+          - Confirm MCP returns a blocked CLI envelope and does not write.
+    observable_outcomes:
+      - MCP returns matrix.upsert or matrix.remove envelopes.
+      - Write mode is required before any mutation.
+      - User approval or user actor claims are rejected without trusted host confirmation.
+      - Delete is lifecycle removal, not physical deletion.
+      - Damaged input or a path escape prevents mutation.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+      - host_surface: claude.cli
+        supported: true
+      - host_surface: copilot.cli
+        supported: true
+      - host_surface: opencode.cli
+        supported: true
+    verification_policy:
+      mode: none
+    approval_policy:
+      mode: none

package/use-cases/migration/importer.yml

@@ -0,0 +1,171 @@
+schema_version: 1
+feature:
+  id: migration.importer
+  name: TEST-MATRIX migration
+  summary: Reviewable migration from legacy test matrices into use-case rows without laundering old proof.
+use_cases:
+  - id: migration.importer.reviewable_draft_import
+    title: Reviewable TEST-MATRIX draft import
+    lifecycle: active
+    value_tier: core
+    journey_role: alternate
+    usage_frequency: occasional
+    tags:
+      - migration
+      - test-matrix
+      - backfill
+    source_refs:
+      - kind: file
+        path: docs/migration.md
+      - kind: file
+        path: packages/core/src/migration/testMatrix.ts
+    actor: agent
+    intent: Convert legacy TEST-MATRIX rows into draft use-case YAML with review warnings.
+    preconditions:
+      - A legacy TEST-MATRIX.md file exists.
+    trigger: User or agent backfills an existing project into Use Cases.
+    scenarios:
+      - id: migration.importer.reviewable_draft_import.dry_run
+        kind: steps
+        steps:
+          - Run migrate test-matrix in dry-run mode.
+          - Inspect generated draft rows and diagnostics.
+          - Write drafts only when the output is reviewable.
+    observable_outcomes:
+      - Legacy rows become draft use cases, not silent active acceptance.
+      - Review warnings identify ambiguous titles, old statuses, and missing detail.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+    verification_policy:
+      mode: requirements
+      requirements:
+        - evidence_kind: command_result
+          required_verifiers:
+            - script
+          minimum_count: 1
+    approval_policy:
+      mode: ask
+  - id: migration.importer.no_legacy_pass_as_proof
+    title: Legacy pass marks are not evidence
+    lifecycle: active
+    value_tier: critical
+    journey_role: negative
+    usage_frequency: common
+    tags:
+      - migration
+      - evidence
+      - proof-boundary
+    source_refs:
+      - kind: file
+        path: docs/migration.md
+      - kind: file
+        path: packages/core/src/migration/testMatrix.ts
+    actor: agent
+    intent: Prevent old pass or status cells from becoming current evidence or approval.
+    preconditions:
+      - Legacy matrix rows include status text such as pass, fail, done, or accepted.
+    trigger: Agent migrates legacy matrix content.
+    scenarios:
+      - id: migration.importer.no_legacy_pass_as_proof.guard
+        kind: steps
+        steps:
+          - Parse legacy rows with old status marks.
+          - Generate use-case rows without evidence IDs.
+          - Preserve old status only as review context when safe.
+    observable_outcomes:
+      - Current evidence must be recorded separately through the evidence ledger.
+      - Migration cannot invent modern proof or user approval.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+    verification_policy:
+      mode: requirements
+      requirements:
+        - evidence_kind: test_result
+          required_verifiers:
+            - script
+          minimum_count: 1
+    approval_policy:
+      mode: none
+  - id: migration.importer.source_traceability
+    title: Migration source traceability
+    lifecycle: active
+    value_tier: supporting
+    journey_role: alternate
+    usage_frequency: rare
+    tags:
+      - migration
+      - traceability
+    source_refs:
+      - kind: file
+        path: docs/migration.md
+      - kind: file
+        path: tests/fixtures/workspaces/test-matrix-source/TEST-MATRIX.md
+    actor: agent
+    intent: Preserve original markdown row references so reviewers can audit generated draft rows.
+    preconditions:
+      - A migration source file has identifiable source rows.
+    trigger: Agent writes or reviews migrated draft use-case YAML.
+    scenarios:
+      - id: migration.importer.source_traceability.refs
+        kind: steps
+        steps:
+          - Generate draft rows from a TEST-MATRIX source.
+          - Include source references or diagnostics for the original rows.
+          - Let reviewers compare generated rows to source intent.
+    observable_outcomes:
+      - Migration output can be audited against its source.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+    verification_policy:
+      mode: requirements
+      requirements:
+        - evidence_kind: agent_observation
+          required_verifiers:
+            - agent
+          minimum_count: 1
+    approval_policy:
+      mode: none
+  - id: migration.importer.human_review_activation
+    title: Human review before activation
+    lifecycle: active
+    value_tier: core
+    journey_role: alternate
+    usage_frequency: occasional
+    tags:
+      - migration
+      - review
+      - activation
+    source_refs:
+      - kind: file
+        path: docs/migration.md
+      - kind: file
+        path: .agents/skills/use-cases/SKILL.md
+    actor: agent
+    intent: Keep migrated rows draft or planned until a human reviews the high-level feature printout.
+    preconditions:
+      - Migration output contains draft or uncertain rows.
+    trigger: Agent considers activating migrated rows.
+    scenarios:
+      - id: migration.importer.human_review_activation.review
+        kind: steps
+        steps:
+          - Present a concise feature printout of migrated rows.
+          - Ask the user to confirm high-value behavior and scope.
+          - Activate only rows that are reviewed and structurally usable.
+    observable_outcomes:
+      - Migration review separates mechanical parsing from product acceptance.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+    verification_policy:
+      mode: requirements
+      requirements:
+        - evidence_kind: manual_observation
+          required_verifiers:
+            - user
+          minimum_count: 1
+    approval_policy:
+      mode: ask

package/use-cases/migration/test-matrix.yml

@@ -0,0 +1,32 @@
+schema_version: 1
+feature:
+  id: migration.test_matrix
+  name: TEST-MATRIX migration
+  summary: Legacy TEST-MATRIX.md files become draft intended behavior.
+use_cases:
+  - id: migration.test_matrix.draft
+    title: Migrate TEST-MATRIX without laundering proof
+    lifecycle: active
+    value_tier: core
+    journey_role: alternate
+    usage_frequency: occasional
+    tags: [migration, test-matrix]
+    source_refs:
+      - kind: file
+        path: packages/core/src/migration/testMatrix.ts
+    actor: agent
+    intent: Backfill use-case drafts from a legacy matrix safely.
+    preconditions: [A legacy TEST-MATRIX.md file exists.]
+    trigger: User wants to replace a legacy matrix.
+    scenarios:
+      - id: migration.test_matrix.draft.cli
+        kind: steps
+        steps: [Run migrate test-matrix in dry-run or write mode.]
+    observable_outcomes: [Generated YAML is draft behavior and old status is review context only.]
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+    verification_policy:
+      mode: none
+    approval_policy:
+      mode: none