@adammcarter/use-cases 0.1.0

package/use-cases/hosts/projections.yml

@@ -0,0 +1,96 @@
+schema_version: 1
+feature:
+  id: hosts.projections
+  name: Host projections
+  summary: Claude, Codex, Copilot, and OpenCode receive thin activation stubs.
+use_cases:
+  - id: hosts.projections.all
+    title: Check all first-class host projections
+    lifecycle: active
+    value_tier: core
+    journey_role: alternate
+    usage_frequency: common
+    tags:
+      - hosts
+      - projections
+    source_refs:
+      - kind: file
+        path: packages/core/src/hosts/projectHostFiles.ts
+    actor: agent
+    intent: Confirm host files are projected without claiming unsupported proof.
+    preconditions:
+      - Host profiles are available.
+    trigger: Agent installs or verifies host support.
+    scenarios:
+      - id: hosts.projections.all.cli
+        kind: steps
+        steps:
+          - Run host conformance with a passing executable smoke.
+          - Run host conformance with a missing or unavailable executable.
+          - Run host conformance with a resolved executable that fails.
+    observable_outcomes:
+      - Hosts report passed
+      - warning-backed not_run
+      - or failed smoke semantics without claiming verified support.
+    extensions:
+      use-cases.dev/status_fields:
+        required:
+          - profile_available
+          - projected
+          - static_conformant
+          - executable_smoke
+          - verified_with_evidence
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+    verification_policy:
+      mode: none
+    approval_policy:
+      mode: none
+  - id: hosts.projections.static_conformance
+    title: Report host production support without overstating evidence
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: common
+    tags:
+      - hosts
+      - projections
+      - conformance
+      - support-status
+    source_refs:
+      - kind: file
+        path: packages/core/src/hosts/projectHostFiles.ts
+      - kind: file
+        path: docs/hosts.md
+    actor: agent
+    intent: Show Claude, Codex, Copilot, and OpenCode projection health as production status while keeping real evidence separate.
+    preconditions:
+      - Host profiles are available and projection targets are writable in a workspace.
+    trigger: Agent verifies host support before release or install handoff.
+    scenarios:
+      - id: hosts.projections.static_conformance.cli
+        kind: steps
+        steps:
+          - Project all first-class host activation stubs.
+          - Run host conformance for all hosts.
+          - Check support fields for profile availability, projection match, static conformance, executable smoke, and evidence ids.
+          - Revert the projected files.
+    observable_outcomes:
+      - Each host row reports static conformance and executable smoke state.
+      - verified_with_evidence remains false until evidence_event_ids exist.
+      - Unavailable executables produce warning-backed not_run status instead of a verified support claim.
+      - Missing Copilot or OpenCode executables are reported as not_run rather than passed.
+    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/lifecycle/loop.yml

@@ -0,0 +1,229 @@
+schema_version: 1
+feature:
+  id: lifecycle.loop
+  name: Use Cases lifecycle
+  summary: Recommended but optional workflows for keeping use cases, evidence, and showcases current.
+use_cases:
+  - id: lifecycle.loop.continuous_loop
+    title: Continuous product-proof-demo loop
+    lifecycle: active
+    value_tier: critical
+    journey_role: golden
+    usage_frequency: common
+    tags:
+      - lifecycle
+      - dogfood
+      - planning
+      - evidence
+      - showcase
+    source_refs:
+      - kind: file
+        path: docs/activation.md
+      - kind: file
+        path: bootstrap/use-cases.md
+    actor: agent
+    intent: Keep behavior rows, proof, and showcase readiness connected during normal work.
+    preconditions:
+      - A repo has behavior worth tracking beyond a trivial edit.
+    trigger: Agent plans, implements, verifies, or prepares to show product work.
+    scenarios:
+      - id: lifecycle.loop.continuous_loop.default
+        kind: steps
+        steps:
+          - Add or update use-case rows during planning or implementation.
+          - Record safe evidence when behavior is proved.
+          - Select a focused showcase from high-value rows near completion.
+    observable_outcomes:
+      - The matrix, evidence, and showcase plan describe the same demonstrated scope.
+      - The workflow is recommended without being mandatory for every edit.
+    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: agent_observation
+          required_verifiers:
+            - agent
+          minimum_count: 1
+    approval_policy:
+      mode: none
+  - id: lifecycle.loop.workflow_modes
+    title: First-class non-continuous workflows
+    lifecycle: active
+    value_tier: core
+    journey_role: alternate
+    usage_frequency: occasional
+    tags:
+      - lifecycle
+      - workflow
+      - adoption
+    source_refs:
+      - kind: file
+        path: docs/activation.md
+      - kind: file
+        path: schemas/v1/workflow-mode.schema.json
+    actor: agent
+    intent: Support backfill, showcase-only, audit-only, and migration workflows without weakening integrity gates.
+    preconditions:
+      - The user prefers a lifecycle other than continuous upkeep.
+    trigger: User asks to backfill, audit, migrate, or demo work outside the recommended default loop.
+    scenarios:
+      - id: lifecycle.loop.workflow_modes.alternates
+        kind: steps
+        steps:
+          - Identify the requested workflow mode.
+          - Use matrix, evidence, plan, or showcase commands that fit that mode.
+          - Preserve normal validation, evidence safety, and approval boundaries.
+    observable_outcomes:
+      - The tool supports the chosen workflow without treating it as lower quality.
+      - Advisory workflow configuration never bypasses schema or trust checks.
+    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: lifecycle.loop.agent_matrix_stewardship
+    title: Agent owns matrix upkeep
+    lifecycle: active
+    value_tier: critical
+    journey_role: golden
+    usage_frequency: common
+    tags:
+      - lifecycle
+      - ownership
+      - agent-boundary
+    source_refs:
+      - kind: file
+        path: .agents/skills/use-cases/SKILL.md
+      - kind: file
+        path: docs/activation.md
+    actor: agent
+    intent: Agent creates and maintains rows while escalating subjective judgment to the user.
+    preconditions:
+      - The agent has enough context to identify behavior rows.
+    trigger: Product behavior is added, changed, migrated, or reviewed.
+    scenarios:
+      - id: lifecycle.loop.agent_matrix_stewardship.default
+        kind: steps
+        steps:
+          - Infer candidate behavior rows from product work.
+          - Add or update rows with value, journey, frequency, and host applicability.
+          - Ask the user only for subjective scope, audience, or approval decisions.
+    observable_outcomes:
+      - The user does not have to manually author mechanical matrix rows.
+      - The agent does not fabricate user judgment or sign-off.
+    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: agent_observation
+          required_verifiers:
+            - agent
+          minimum_count: 1
+    approval_policy:
+      mode: none
+  - id: lifecycle.loop.user_feature_printout
+    title: User-facing feature printout
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: common
+    tags:
+      - lifecycle
+      - user-visible
+      - summary
+    source_refs:
+      - kind: file
+        path: docs/activation.md
+      - kind: file
+        path: packages/core/src/presentation/selectPlan.ts
+    actor: agent
+    intent: Show the user high-level feature status and gaps without exposing YAML mechanics by default.
+    preconditions:
+      - The matrix contains product-level rows with meaningful titles and tags.
+    trigger: User asks what the product can show, accept, or prove.
+    scenarios:
+      - id: lifecycle.loop.user_feature_printout.default
+        kind: steps
+        steps:
+          - Summarize high-value active rows by feature area.
+          - Distinguish ready, evidence-missing, planned, and user-sign-off cases.
+          - Link the summary back to row IDs for mechanical follow-up.
+    observable_outcomes:
+      - The user can scan the important product behaviors without reading every YAML file.
+      - Planned or unproved items are clearly separated from accepted scope.
+    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
+  - id: lifecycle.loop.opt_out_or_tiny_change
+    title: Respect opt-out and tiny-scope work
+    lifecycle: active
+    value_tier: supporting
+    journey_role: negative
+    usage_frequency: rare
+    tags:
+      - lifecycle
+      - opt-out
+      - scope-control
+    source_refs:
+      - kind: file
+        path: .agents/skills/use-cases/SKILL.md
+      - kind: file
+        path: docs/activation.md
+    actor: agent
+    intent: Avoid invoking the workflow for trivial non-behavior edits or when the user opts out.
+    preconditions:
+      - Work is trivial, non-behavioral, or explicitly outside the plugin lifecycle.
+    trigger: User opts out or the agent detects that matrix upkeep would add noise.
+    scenarios:
+      - id: lifecycle.loop.opt_out_or_tiny_change.skip
+        kind: steps
+        steps:
+          - Identify the reason the lifecycle should not run.
+          - Avoid adding rows, evidence, or showcase artifacts.
+          - Continue ordinary repo work and report that no matrix update was needed.
+    observable_outcomes:
+      - The workflow remains useful because it is not forced onto tiny changes.
+    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

package/use-cases/matrix/core.yml

@@ -0,0 +1,92 @@
+schema_version: 1
+feature:
+  id: matrix.core
+  name: Use cases
+  summary: Use-case files load as the living acceptance matrix.
+use_cases:
+  - id: matrix.core.validate
+    title: Validate the use-case matrix without summaries
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: common
+    tags:
+      - matrix
+      - acceptance
+    source_refs:
+      - kind: file
+        path: packages/core/src/useCases/loadUseCaseMatrix.ts
+    actor: agent
+    intent: Confirm the matrix is current and structurally clean.
+    preconditions:
+      - Use cases are stored under use-cases.
+    trigger: Agent plans or verifies work.
+    scenarios:
+      - id: matrix.core.validate.cli
+        kind: steps
+        steps:
+          - Run matrix validate.
+    observable_outcomes:
+      - The matrix reports clean integrity.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+    verification_policy:
+      mode: none
+    approval_policy:
+      mode: none
+  - id: matrix.core.mutate
+    title: Add, update, or retire use-case rows safely
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: common
+    tags:
+      - matrix
+      - mutation
+      - cli
+      - lifecycle
+    source_refs:
+      - kind: file
+        path: packages/core/src/useCases/mutateUseCaseMatrix.ts
+      - kind: file
+        path: packages/cli/src/index.ts
+    actor: agent
+    intent: Keep the living use-case matrix current during planning, implementation, and review without bypassing validation.
+    preconditions:
+      - The current use-case matrix is complete enough to mutate safely.
+      - The target YAML file stays under use-cases.
+    trigger: Agent or user adds, updates, or retires an acceptance row.
+    scenarios:
+      - id: matrix.core.mutate.upsert
+        kind: steps
+        steps:
+          - Run matrix upsert with a target use-cases YAML file and one use_case object.
+          - Validate that the matrix remains complete after the write.
+      - id: matrix.core.mutate.remove
+        kind: steps
+        steps:
+          - Run matrix remove with a use-case id and reason.
+          - Confirm the row is marked lifecycle removed rather than physically deleted.
+      - id: matrix.core.mutate.safety
+        kind: steps
+        steps:
+          - Try a path escape, damaged matrix, or stale expected hash.
+          - Confirm the mutation is blocked and no unsafe write is committed.
+    observable_outcomes:
+      - Mutation commands return matrix.upsert or matrix.remove envelopes with before and after hashes.
+      - The matrix remains structurally clean after accepted writes.
+      - Removal preserves accidental history as a lifecycle transition.
+    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/matrix/product.yml

@@ -0,0 +1,289 @@
+schema_version: 1
+feature:
+  id: matrix.product
+  name: Product use-case matrix
+  summary: Human-readable behavior inventory for product planning, acceptance, and showcase selection.
+use_cases:
+  - id: matrix.product.product_inventory
+    title: Living product behavior inventory
+    lifecycle: active
+    value_tier: critical
+    journey_role: golden
+    usage_frequency: common
+    tags:
+      - matrix
+      - product-behavior
+      - dogfood
+    source_refs:
+      - kind: file
+        path: docs/data-model.md
+      - kind: file
+        path: packages/core/src/useCases/loadUseCaseMatrix.ts
+    actor: agent
+    intent: Represent Use Cases product behavior as stable, addressable use-case rows.
+    preconditions:
+      - Product behavior has been identified at feature level.
+    trigger: Agent or user needs acceptance, proof, or demo coverage for the product.
+    scenarios:
+      - id: matrix.product.product_inventory.cli
+        kind: steps
+        steps:
+          - Run matrix list.
+          - Confirm product-level use-cases rows exist alongside primitive support rows.
+          - Confirm each row has value, journey, usage, and scenario data.
+    observable_outcomes:
+      - Product behavior can be selected by row ID without reading implementation code.
+      - Primitive rows remain available as supporting proof rather than the whole product map.
+    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: none
+  - id: matrix.product.sharded_human_readable_files
+    title: Sharded readable feature files
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: common
+    tags:
+      - matrix
+      - yaml
+      - maintainability
+    source_refs:
+      - kind: file
+        path: docs/data-model.md
+      - kind: file
+        path: schemas/v1/use-case-file.schema.json
+    actor: agent
+    intent: Keep rows in readable feature-area YAML files under use-cases.
+    preconditions:
+      - A workspace has a `use-cases/` directory.
+    trigger: Agent adds, updates, reviews, or repairs use-case rows.
+    scenarios:
+      - id: matrix.product.sharded_human_readable_files.layout
+        kind: steps
+        steps:
+          - Place related rows in a feature shard.
+          - Keep one feature summary per file.
+          - Validate all shards as one matrix.
+    observable_outcomes:
+      - Users can inspect or edit a feature shard without opening one large matrix file.
+      - Validation reports each loaded or damaged file separately.
+    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: none
+  - id: matrix.product.integrity_degraded_nonfatal
+    title: Degraded-but-nonfatal diagnostics
+    lifecycle: active
+    value_tier: critical
+    journey_role: edge
+    usage_frequency: occasional
+    tags:
+      - matrix
+      - diagnostics
+      - partial
+    source_refs:
+      - kind: file
+        path: packages/core/src/useCases/loadUseCaseMatrix.ts
+      - kind: file
+        path: packages/core/src/useCases/integrity.ts
+    actor: agent
+    intent: Load valid rows despite damaged files while clearly blocking full coverage or sign-off when relevant.
+    preconditions:
+      - At least one use-case YAML file is damaged, duplicated, or partially invalid.
+    trigger: Validation, planning, or status reads a partially damaged matrix.
+    scenarios:
+      - id: matrix.product.integrity_degraded_nonfatal.partial
+        kind: steps
+        steps:
+          - Validate a workspace with one valid shard and one damaged shard.
+          - Confirm valid rows are still addressable.
+          - Confirm integrity is partial and diagnostics identify the damaged file.
+    observable_outcomes:
+      - Damaged YAML does not bring down the whole system.
+      - Plans and status outputs surface partial integrity before any final claim.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+    verification_policy:
+      mode: requirements
+      verifiers:
+        script:
+          kind: script
+          evidence_kind: test_result
+          command:
+            - pnpm
+            - -s
+            - vitest
+            - run
+            - tests/use-cases/integrity_degraded_nonfatal.test.ts
+          inputs:
+            - tests/use-cases/integrity_degraded_nonfatal.test.ts
+      requirements:
+        - evidence_kind: test_result
+          required_verifiers:
+            - script
+          minimum_count: 1
+    approval_policy:
+      mode: none
+      required_for_release: true
+  - id: matrix.product.coverage_by_value_and_journey
+    title: Coverage by value and journey role
+    lifecycle: active
+    value_tier: core
+    journey_role: alternate
+    usage_frequency: occasional
+    tags:
+      - matrix
+      - coverage
+      - prioritization
+    source_refs:
+      - kind: file
+        path: packages/core/src/useCases/query.ts
+      - kind: file
+        path: packages/core/src/presentation/scoring.ts
+    actor: agent
+    intent: Let agents select and report rows by value tier, journey role, lifecycle, tags, and host relevance.
+    preconditions:
+      - Rows are tagged with value, journey, usage, lifecycle, and host applicability.
+    trigger: Agent prepares a showcase, walkthrough, acceptance pass, or gap report.
+    scenarios:
+      - id: matrix.product.coverage_by_value_and_journey.selection
+        kind: steps
+        steps:
+          - List rows by value and journey metadata.
+          - Select critical golden rows for a short showcase.
+          - Include alternate, edge, negative, and failure rows for deeper walkthrough coverage.
+    observable_outcomes:
+      - High-value rows are easy to separate from long-tail or future rows.
+      - Showcase and walkthrough cuts can explain why rows were included or excluded.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+    verification_policy:
+      mode: requirements
+      verifiers:
+        script:
+          kind: script
+          evidence_kind: test_result
+          command:
+            - pnpm
+            - -s
+            - vitest
+            - run
+            - tests/use-cases/coverage_by_value_and_journey.test.ts
+          inputs:
+            - tests/use-cases/coverage_by_value_and_journey.test.ts
+      requirements:
+        - evidence_kind: test_result
+          required_verifiers:
+            - script
+          minimum_count: 1
+    approval_policy:
+      mode: none
+  - id: matrix.product.claim_guardrails
+    title: Unsupported-claim guardrails
+    lifecycle: active
+    value_tier: critical
+    journey_role: negative
+    usage_frequency: common
+    tags:
+      - matrix
+      - claims
+      - safety
+    source_refs:
+      - kind: file
+        path: docs/security.md
+      - kind: file
+        path: .agents/skills/showcase/SKILL.md
+    actor: agent
+    intent: Prevent verified, supported, signed-off, or release-ready claims when evidence or approval is missing.
+    preconditions:
+      - A row, plan, host profile, capsule, or generated output could be mistaken for proof.
+    trigger: Agent summarizes readiness, support, approval, or release status.
+    scenarios:
+      - id: matrix.product.claim_guardrails.negative
+        kind: steps
+        steps:
+          - Inspect the matrix and related evidence status.
+          - Identify rows with missing proof or approval.
+          - State the exact gap instead of claiming acceptance.
+    observable_outcomes:
+      - Prepared material is not described as performed proof.
+      - Host support and user sign-off claims require recorded evidence.
+    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: agent_observation
+          required_verifiers:
+            - agent
+          minimum_count: 1
+    approval_policy:
+      mode: none
+  - id: matrix.product.status_summary
+    title: One-shot matrix and evidence health summary
+    lifecycle: active
+    value_tier: supporting
+    journey_role: alternate
+    usage_frequency: occasional
+    tags:
+      - matrix
+      - status
+      - summary
+    source_refs:
+      - kind: file
+        path: packages/core/src/useCases/query.ts
+      - kind: file
+        path: docs/cli.md
+    actor: agent
+    intent: Summarize matrix population, integrity state, and linked evidence status in a single read-only command for a quick health check.
+    preconditions:
+      - A use-case matrix exists, possibly with partial or missing evidence.
+    trigger: Agent wants a fast readiness read before planning, release, or showcase.
+    scenarios:
+      - id: matrix.product.status_summary.report
+        kind: steps
+        steps:
+          - Run matrix status.
+          - Inspect row counts, integrity state, and evidence coverage.
+          - Confirm the summary is derived from current files, not a cached claim.
+    observable_outcomes:
+      - Matrix and evidence health are readable in one command.
+      - Integrity or evidence gaps are visible without a full plan run.
+    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: none