@adammcarter/use-cases 0.1.0

package/use-cases/capsule/demos.yml

@@ -0,0 +1,212 @@
+schema_version: 1
+feature:
+  id: capsule.demos
+  name: Demo capsules
+  summary: Optional persisted smoke and golden-path runbooks that become proof only when performed as showcase runs.
+use_cases:
+  - id: capsule.demos.persisted_smoke_runbook
+    title: Persisted smoke demo runbook
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: common
+    tags:
+      - capsules
+      - smoke
+      - runbook
+    source_refs:
+      - kind: file
+        path: docs/showcase.md
+      - kind: file
+        path: packages/core/src/capsules/loadCapsule.ts
+    actor: agent
+    intent: Provide a reusable capsule that references use-case IDs and supports repeatable demos.
+    preconditions:
+      - A common smoke or golden path deserves a persisted runbook.
+    trigger: Agent or user wants a repeatable demonstration without reselecting rows manually.
+    scenarios:
+      - id: capsule.demos.persisted_smoke_runbook.plan
+        kind: steps
+        steps:
+          - Validate a capsule file.
+          - Generate a capsule plan.
+          - Confirm referenced use-case and scenario IDs resolve.
+    observable_outcomes:
+      - The capsule is reusable prepared material.
+      - It is not proof until a run records performed events.
+    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: capsule.demos.adhoc_release_demo
+    title: Ad hoc release demo plan
+    lifecycle: active
+    value_tier: core
+    journey_role: alternate
+    usage_frequency: occasional
+    tags:
+      - capsules
+      - adhoc
+      - release
+    source_refs:
+      - kind: file
+        path: docs/showcase.md
+      - kind: file
+        path: packages/core/src/showcase/startRun.ts
+    actor: agent
+    intent: Generate a one-run plan for release proof without saving it as a reusable recipe.
+    preconditions:
+      - The demo is specific to a release, PR, or changed scope.
+    trigger: Agent prepares a one-off live run.
+    scenarios:
+      - id: capsule.demos.adhoc_release_demo.start
+        kind: steps
+        steps:
+          - Select ad hoc use-case IDs.
+          - Start a showcase run from that selection.
+          - Record the normalized plan in run_started.
+    observable_outcomes:
+      - One-off demos are supported without accumulating unnecessary capsule files.
+    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: ask
+  - id: capsule.demos.runner_command_safety
+    title: Hardened scripted capsule execution
+    lifecycle: active
+    value_tier: critical
+    journey_role: negative
+    usage_frequency: common
+    tags:
+      - capsules
+      - command-runner
+      - security
+    source_refs:
+      - kind: file
+        path: packages/core/src/capsules/runCapsule.ts
+      - kind: file
+        path: docs/security.md
+    actor: script
+    intent: Run scripted capsule commands with explicit controls and no committed local-path leakage.
+    preconditions:
+      - A capsule contains command steps.
+    trigger: Agent runs a capsule with command execution enabled.
+    scenarios:
+      - id: capsule.demos.runner_command_safety.command
+        kind: steps
+        steps:
+          - Require command execution permission at the capsule and caller level.
+          - Resolve working directory inside the repo.
+          - Execute without a shell and record bounded output.
+    observable_outcomes:
+      - Unsafe commands do not run by default.
+      - Command results are recorded as observations and verdicts without leaking uncontrolled local state.
+    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: capsule.demos.stale_reference_warning
+    title: Stale or missing capsule references
+    lifecycle: active
+    value_tier: supporting
+    journey_role: edge
+    usage_frequency: rare
+    tags:
+      - capsules
+      - stale
+      - diagnostics
+    source_refs:
+      - kind: file
+        path: packages/core/src/capsules/loadCapsule.ts
+      - kind: file
+        path: packages/core/src/capsules/index.ts
+    actor: agent
+    intent: Warn when a persisted capsule points at missing, removed, or semantically changed rows.
+    preconditions:
+      - A capsule references use-case or scenario IDs.
+    trigger: Agent validates or plans a capsule after matrix changes.
+    scenarios:
+      - id: capsule.demos.stale_reference_warning.validate
+        kind: steps
+        steps:
+          - Validate a capsule after related rows changed.
+          - Detect missing or stale row references.
+          - Report diagnostics before running the capsule.
+    observable_outcomes:
+      - Persisted runbooks do not silently drift away from the matrix.
+    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: capsule.demos.runbook_not_proof
+    title: Capsule is runbook, not proof
+    lifecycle: active
+    value_tier: critical
+    journey_role: negative
+    usage_frequency: common
+    tags:
+      - capsules
+      - proof-boundary
+    source_refs:
+      - kind: file
+        path: docs/showcase.md
+      - kind: file
+        path: packages/core/src/capsules/runCapsule.ts
+    actor: agent
+    intent: Never treat a persisted or generated capsule as evidence until a live run records events.
+    preconditions:
+      - A capsule exists or a capsule plan has been generated.
+    trigger: Agent summarizes proof, readiness, or release state.
+    scenarios:
+      - id: capsule.demos.runbook_not_proof.guard
+        kind: steps
+        steps:
+          - Inspect a capsule or capsule plan.
+          - Confirm it is prepared material.
+          - Require showcase run events before claiming proof.
+    observable_outcomes:
+      - Capsule files are not confused with performed demonstrations.
+    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/capsule/runner.yml

@@ -0,0 +1,49 @@
+schema_version: 1
+feature:
+  id: capsule.live_runner
+  name: Demo capsule runner
+  summary: Persisted capsules can be performed as script-led or agent-led live demos.
+use_cases:
+  - id: capsule.live_runner.scripted
+    title: Run a command-backed demo capsule as a real showcase gate
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: common
+    tags: [capsule, showcase, live-demo, command]
+    source_refs:
+      - kind: file
+        path: packages/core/src/capsules/runCapsule.ts
+      - kind: file
+        path: packages/core/src/showcase/appendShowcaseEvent.ts
+    actor: agent
+    intent: Perform a persisted demo capsule in front of the user or reviewer and record command-backed proof in the showcase ledger.
+    preconditions:
+      - The capsule resolves to active use-case rows.
+      - Command execution is explicitly requested.
+      - The capsule permits command execution.
+    trigger: Agent reaches a final release or feature gate that needs a live, repeatable demo.
+    scenarios:
+      - id: capsule.live_runner.scripted.cli
+        kind: steps
+        steps:
+          - Run capsule run with --execute-commands and a stable idempotency key.
+          - Confirm the runner starts a showcase run from the capsule plan.
+          - Confirm command stdout, stderr, exit code, and verdict are recorded.
+          - Confirm the run finishes only when all command-backed items pass and no runtime observations remain pending.
+    observable_outcomes:
+      - A showcase JSONL ledger contains run_started, action_recorded, observation_recorded, verdict_recorded, and run_finished events.
+      - The run status is completed and passed without recording user approval unless the selected row requires it.
+    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/diagnostics/contracts.yml

@@ -0,0 +1,239 @@
+schema_version: 1
+feature:
+  id: diagnostics.contracts
+  name: Diagnostics and contracts
+  summary: Resolve roots deterministically and publish a versioned, validatable schema contract so the tool can be pointed anywhere and integrated against safely.
+use_cases:
+  - id: diagnostics.contracts.root_resolution
+    title: Workspace and data roots resolve safely
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: occasional
+    tags:
+      - diagnostics
+      - roots
+      - configuration
+    source_refs:
+      - kind: file
+        path: packages/core/src/roots.ts
+      - kind: file
+        path: docs/data-model.md
+    actor: agent
+    intent: Resolve the workspace root and data root deterministically, allowing the data root to differ from the workspace root for monorepo or CI layouts.
+    preconditions:
+      - A workspace config declares a data root that may differ from the repository root.
+    trigger: Agent points the CLI or MCP server at a repository and inspects resolved roots.
+    scenarios:
+      - id: diagnostics.contracts.root_resolution.doctor
+        kind: steps
+        steps:
+          - Run doctor roots against the repository.
+          - Confirm workspace root and data root are reported distinctly.
+          - Confirm a separated data root resolves and unsafe or symlinked roots are rejected.
+    observable_outcomes:
+      - The data root can be relocated without breaking matrix, evidence, or showcase paths.
+      - Unsafe roots are refused rather than silently followed.
+    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: diagnostics.contracts.schema_contract_surface
+    title: Versioned schema contract is published and validated
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: occasional
+    tags:
+      - diagnostics
+      - schema
+      - contract
+    source_refs:
+      - kind: file
+        path: packages/core/src/schema/index.ts
+      - kind: file
+        path: schemas/v1/cli-result.schema.json
+      - kind: file
+        path: docs/cli.md
+    actor: script
+    intent: Expose every result envelope as a listable, versioned JSON schema and validate fixtures against it so integrators can depend on the contract.
+    preconditions:
+      - The package ships versioned v1 result and entity schemas.
+    trigger: Integrator or release gate enumerates the contract and validates fixtures.
+    scenarios:
+      - id: diagnostics.contracts.schema_contract_surface.validate
+        kind: steps
+        steps:
+          - Run schema list to enumerate published v1 schemas.
+          - Run schema validate-fixtures against the bundled fixtures.
+          - Confirm CLI and MCP results validate against their declared schema IDs.
+    observable_outcomes:
+      - Every command result is backed by a published, versioned schema.
+      - A drifted result or fixture fails validation rather than passing silently.
+    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: diagnostics.contracts.identity_consistency
+    title: Product identity is consistent across every envelope
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: common
+    tags:
+      - diagnostics
+      - identity
+      - contract
+    source_refs:
+      - kind: file
+        path: packages/core/src/version.ts
+      - kind: file
+        path: use-cases.yml
+    actor: agent
+    intent: Emit the configured component identity (use-cases) in every CLI and MCP result envelope, falling back to the same default when no workspace config is present, so a published build never leaks a stale product name.
+    preconditions:
+      - The workspace config declares a component id, or none is set and the default applies.
+    trigger: Any CLI or MCP command runs and returns a result envelope.
+    scenarios:
+      - id: diagnostics.contracts.identity_consistency.envelope
+        kind: steps
+        steps:
+          - Run any command with --json and read context.component_id.
+          - Confirm it equals the configured component id, or the use-cases default when unconfigured.
+          - Confirm no envelope, schema default, or version surface reports the pre-rename name.
+    observable_outcomes:
+      - Every envelope reports component_id use-cases for this repository.
+      - An unconfigured workspace still defaults to use-cases rather than a stale name.
+    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: diagnostics.contracts.cli_self_documents
+    title: CLI is self-documenting via help and usage
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: common
+    tags:
+      - diagnostics
+      - cli
+      - discoverability
+    source_refs:
+      - kind: file
+        path: packages/cli/src/index.ts
+      - kind: file
+        path: docs/cli.md
+    actor: agent
+    intent: Let an agent discover the available commands and their flags from the CLI itself, without reading the source or the test suite.
+    preconditions:
+      - The CLI is built and on PATH (or invoked via node).
+    trigger: An agent reaches for help before it knows a command's exact arguments.
+    scenarios:
+      - id: diagnostics.contracts.cli_self_documents.usage
+        kind: steps
+        steps:
+          - Run the CLI with no command, with --help, or with -h.
+          - Run a known command with --help.
+          - Run an unrecognized command.
+    observable_outcomes:
+      - A bare invocation, --help, or -h prints a usage envelope listing the available commands and their flags.
+      - An unrecognized command prints usage scoped to its group instead of a bare command.unknown response.
+    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/conformance/cli/cli-ergonomics.test.ts
+          inputs:
+            - tests/conformance/cli/cli-ergonomics.test.ts
+      requirements:
+        - evidence_kind: test_result
+          required_verifiers:
+            - script
+          minimum_count: 1
+    approval_policy:
+      mode: none
+  - id: diagnostics.contracts.missing_build_hint
+    title: Missing build surfaces an actionable hint
+    lifecycle: active
+    value_tier: supporting
+    journey_role: edge
+    usage_frequency: occasional
+    tags:
+      - diagnostics
+      - cli
+      - onboarding
+    source_refs:
+      - kind: file
+        path: packages/cli/src/index.ts
+    actor: agent
+    intent: On a fresh clone where the compiled core has not been built, tell the user to run the build instead of surfacing a raw module-resolution error.
+    preconditions:
+      - The compiled core dist has not been built yet.
+    trigger: An agent invokes the CLI before running the build.
+    scenarios:
+      - id: diagnostics.contracts.missing_build_hint.hint
+        kind: steps
+        steps:
+          - Invoke the CLI with the compiled core absent.
+          - Read the message and exit code.
+    observable_outcomes:
+      - The CLI prints an actionable message naming the build command rather than a raw module-not-found stack.
+      - The process exits non-zero so the missing build is not mistaken for success.
+    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/conformance/cli/cli-ergonomics.test.ts
+          inputs:
+            - tests/conformance/cli/cli-ergonomics.test.ts
+      requirements:
+        - evidence_kind: test_result
+          required_verifiers:
+            - script
+          minimum_count: 1
+    approval_policy:
+      mode: none

package/use-cases/evidence/core.yml

@@ -0,0 +1,32 @@
+schema_version: 1
+feature:
+  id: evidence.core
+  name: Evidence ledger
+  summary: Evidence is recorded as append-only JSONL history.
+use_cases:
+  - id: evidence.core.record
+    title: Record evidence for a use case
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: common
+    tags: [evidence, ledger]
+    source_refs:
+      - kind: file
+        path: packages/core/src/evidence/appendEvidenceEvent.ts
+    actor: agent
+    intent: Persist proof without creating summary state.
+    preconditions: [A target use case resolves.]
+    trigger: Agent records test, demo, or observation proof.
+    scenarios:
+      - id: evidence.core.record.cli
+        kind: steps
+        steps: [Run evidence record.]
+    observable_outcomes: [A JSONL event is appended under evidence.]
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+    verification_policy:
+      mode: none
+    approval_policy:
+      mode: none