@adammcarter/use-cases 0.1.0

package/use-cases/planning/cards.yml

@@ -0,0 +1,215 @@
+schema_version: 1
+feature:
+  id: planning.cards
+  name: Presentation planning
+  summary: Deterministic showcase and walkthrough selection from matrix value, journey, evidence, and user context.
+use_cases:
+  - id: planning.cards.showcase_selection
+    title: High-value showcase selection
+    lifecycle: active
+    value_tier: critical
+    journey_role: golden
+    usage_frequency: common
+    tags:
+      - planning
+      - showcase
+      - selection
+    source_refs:
+      - kind: file
+        path: packages/core/src/presentation/selectShowcasePlan.ts
+      - kind: file
+        path: packages/core/src/presentation/scoring.ts
+    actor: agent
+    intent: Select a short demo from high-value, live-verifiable rows with reasons and exclusions.
+    preconditions:
+      - The matrix contains active rows with value and journey metadata.
+    trigger: User or agent asks what to show in a focused live demo.
+    scenarios:
+      - id: planning.cards.showcase_selection.cli
+        kind: steps
+        steps:
+          - Run plan showcase with a max item limit.
+          - Confirm selected rows prioritize critical or core golden paths.
+          - Review reasons, exclusions, evidence gaps, and prepared-not-performed status.
+    observable_outcomes:
+      - The plan is concise and reasoned.
+      - It remains prepared material until a showcase run records 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: ask
+  - id: planning.cards.walkthrough_coverage
+    title: Broader walkthrough coverage
+    lifecycle: active
+    value_tier: core
+    journey_role: alternate
+    usage_frequency: occasional
+    tags:
+      - planning
+      - walkthrough
+      - caveats
+    source_refs:
+      - kind: file
+        path: packages/core/src/presentation/selectWalkthroughPlan.ts
+      - kind: file
+        path: .agents/skills/walkthrough/SKILL.md
+    actor: agent
+    intent: Select alternate, edge, negative, and failure cases for a deeper evidence-backed walkthrough.
+    preconditions:
+      - The user wants broad explanation rather than a short sign-off demo.
+    trigger: User asks for an extensive walkthrough, caveats, gaps, or provenance.
+    scenarios:
+      - id: planning.cards.walkthrough_coverage.cli
+        kind: steps
+        steps:
+          - Run plan walkthrough.
+          - Confirm selection includes more than golden paths.
+          - Include caveats, evidence state, and exclusions in the explanation.
+    observable_outcomes:
+      - The walkthrough covers product breadth without pretending to be sign-off.
+      - Edge, negative, and failure rows are visible when useful.
+    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: planning.cards.prepared_not_performed
+    title: Generated plans are not proof
+    lifecycle: active
+    value_tier: critical
+    journey_role: negative
+    usage_frequency: common
+    tags:
+      - planning
+      - proof-boundary
+      - safety
+    source_refs:
+      - kind: file
+        path: docs/showcase.md
+      - kind: file
+        path: packages/core/src/presentation/selectPlan.ts
+    actor: agent
+    intent: Keep generated plans in prepared_not_performed state until a run records performed events.
+    preconditions:
+      - A plan, capsule plan, or walkthrough has been generated.
+    trigger: Agent reports plan status or prepares a showcase from generated material.
+    scenarios:
+      - id: planning.cards.prepared_not_performed.guard
+        kind: steps
+        steps:
+          - Generate a plan.
+          - Confirm `prepared_not_performed` is true.
+          - Avoid claiming proof until showcase run events exist.
+    observable_outcomes:
+      - Generated plans do not become evidence or approval by themselves.
+      - A run must bind to the plan hash before performed proof exists.
+    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: planning.cards.audience_timebox_fit
+    title: Audience and timebox fit
+    lifecycle: active
+    value_tier: supporting
+    journey_role: alternate
+    usage_frequency: occasional
+    tags:
+      - planning
+      - audience
+      - timebox
+    source_refs:
+      - kind: file
+        path: docs/showcase.md
+      - kind: file
+        path: packages/core/src/presentation/selectPlan.ts
+    actor: agent
+    intent: Adapt selected items and exclusions to the user's audience, available time, and review goal.
+    preconditions:
+      - The user has an audience, timebox, or review intent.
+    trigger: User asks for a demo, review, walkthrough, or sign-off run with practical constraints.
+    scenarios:
+      - id: planning.cards.audience_timebox_fit.adjust
+        kind: steps
+        steps:
+          - Capture audience and timebox.
+          - Generate a plan within the limit.
+          - Explain excluded rows that were lower priority or out of scope.
+    observable_outcomes:
+      - The plan fits the user's review context.
+      - Important exclusions are explicit instead of hidden.
+    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: planning.cards.partial_matrix_warning
+    title: Partial matrix warning in plans
+    lifecycle: active
+    value_tier: core
+    journey_role: edge
+    usage_frequency: occasional
+    tags:
+      - planning
+      - partial
+      - diagnostics
+    source_refs:
+      - kind: file
+        path: packages/core/src/presentation/selectPlan.ts
+      - kind: file
+        path: tests/fixtures/workspaces/presentation-partial/use-cases/damaged.yml
+    actor: agent
+    intent: Make damaged or incomplete matrix state visible before a plan is used for a demo.
+    preconditions:
+      - The matrix or evidence snapshot is partial.
+    trigger: Agent generates a plan while integrity is not clean.
+    scenarios:
+      - id: planning.cards.partial_matrix_warning.strict
+        kind: steps
+        steps:
+          - Generate a plan against partial matrix input.
+          - Confirm the plan requires integrity acknowledgement or blocks in strict mode.
+          - Report diagnostics before any live run.
+    observable_outcomes:
+      - Partial input cannot masquerade as ordinary full readiness.
+    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

package/use-cases/release/package.yml

@@ -0,0 +1,80 @@
+schema_version: 1
+feature:
+  id: release.package
+  name: Installable package
+  summary: Release checks inspect real tarballs and installed package roots.
+use_cases:
+  - id: release.package.installable_artifact
+    title: Verify the root package tarball and installed runtime
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: occasional
+    tags:
+      - release
+      - package
+      - doctor
+    source_refs:
+      - kind: file
+        path: packages/core/src/package/inspectPackage.ts
+    actor: agent
+    intent: Prove the distributable artifact is installable and free of local state.
+    preconditions:
+      - The workspace has been built.
+    trigger: Agent prepares release or merge evidence.
+    scenarios:
+      - id: release.package.installable_artifact.cli
+        kind: steps
+        steps:
+          - Pack the root package to a tarball.
+          - Inspect tarball entries for required assets and forbidden state.
+          - Install the tarball into a clean project.
+          - Run installed CLI and MCP smoke checks.
+    observable_outcomes:
+      - Package doctor reports a complete tarball or installed-root inspection with no diagnostics.
+      - The release claim points at the artifact users will install, and package contents match documented and manifest claims.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+    verification_policy:
+      mode: none
+    approval_policy:
+      mode: none
+  - id: release.ci_gate.sequential
+    title: Run the sequential production release gate
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: occasional
+    tags:
+      - release
+      - ci
+      - gate
+      - package
+    source_refs:
+      - kind: file
+        path: scripts/release-gate.mjs
+      - kind: file
+        path: .github/workflows/ci.yml
+    actor: agent
+    intent: Use one sequential command as the production release gate so build artifacts cannot race tests.
+    preconditions:
+      - Dependencies are installed from the lockfile and Node 22 or newer is available.
+    trigger: Agent prepares a v1 release, PR, or merge gate.
+    scenarios:
+      - id: release.ci_gate.sequential.local
+        kind: steps
+        steps:
+          - Run node scripts/release-gate.mjs from the repository root.
+          - Confirm install, typecheck, build, test, package doctor, matrix validation, matrix list, and pack run in order.
+          - Stop on the first failing command.
+    observable_outcomes:
+      - The command prints release gate passed only after all sequential checks exit zero.
+      - The gate proves frozen install, typecheck, build, full tests, package doctor, and matrix checks in one deterministic sequence.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+    verification_policy:
+      mode: none
+    approval_policy:
+      mode: none

package/use-cases/release/proof.yml

@@ -0,0 +1,180 @@
+schema_version: 1
+feature:
+  id: release.proof
+  name: Release proof
+  summary: Production release gates that bind claims to installable artifacts, evidence, host caveats, and self-dogfood demos.
+use_cases:
+  - id: release.proof.self_dogfood_evidence_bundle
+    title: Self-dogfood release evidence bundle
+    lifecycle: active
+    value_tier: critical
+    journey_role: golden
+    usage_frequency: common
+    tags:
+      - release
+      - dogfood
+      - evidence
+    source_refs:
+      - kind: file
+        path: docs/acceptance.md
+      - kind: file
+        path: docs/release.md
+      - kind: file
+        path: use-cases/matrix/core.yml
+    actor: agent
+    intent: Use this repo's own matrix, evidence, and showcase run as release proof for the demonstrated scope.
+    preconditions:
+      - Product-level use cases, safe evidence, and a showcase run exist for the release scope.
+    trigger: Agent prepares final release or merge readiness summary.
+    scenarios:
+      - id: release.proof.self_dogfood_evidence_bundle.bundle
+        kind: steps
+        steps:
+          - Validate the repo's own matrix.
+          - Inspect evidence status for selected product rows.
+          - Run or inspect a self-showcase that demonstrates the release scope.
+          - State residual gaps and user sign-off status.
+    observable_outcomes:
+      - The product demonstrates its own lifecycle rather than only unit tests.
+      - The bundle distinguishes demonstrated scope from untested or future rows.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+    verification_policy:
+      mode: requirements
+      requirements:
+        - evidence_kind: live_demo
+          required_verifiers:
+            - user
+          minimum_count: 1
+    approval_policy:
+      mode: ask
+  - id: release.proof.documentation_claim_precision
+    title: Documentation claim precision
+    lifecycle: active
+    value_tier: critical
+    journey_role: negative
+    usage_frequency: common
+    tags:
+      - release
+      - docs
+      - claims
+    source_refs:
+      - kind: file
+        path: README.md
+      - kind: file
+        path: docs/hosts.md
+      - kind: file
+        path: docs/mcp.md
+      - kind: file
+        path: docs/showcase.md
+    actor: agent
+    intent: Keep README, host, MCP, showcase, and release claims aligned with recorded evidence.
+    preconditions:
+      - Documentation describes support, proof, approval, host status, or release readiness.
+    trigger: Agent updates docs or summarizes release claims.
+    scenarios:
+      - id: release.proof.documentation_claim_precision.review
+        kind: steps
+        steps:
+          - Compare docs against matrix and evidence status.
+          - Identify claims that are not backed by proof.
+          - Caveat or remove unsupported claims before merge.
+    observable_outcomes:
+      - Docs do not overstate host support, MCP authority, approval, or release readiness.
+    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: release.proof.version_manifest_alignment
+    title: Version and manifest alignment
+    lifecycle: active
+    value_tier: core
+    journey_role: alternate
+    usage_frequency: occasional
+    tags:
+      - release
+      - version
+      - manifests
+    source_refs:
+      - kind: file
+        path: package.json
+      - kind: file
+        path: plugin.json
+      - kind: file
+        path: packages/core/src/version.ts
+    actor: script
+    intent: Keep package, manifests, CLI/MCP version output, and projection plugin_version consistent.
+    preconditions:
+      - Release metadata or generated host projections exist.
+    trigger: Agent prepares a release candidate or package artifact.
+    scenarios:
+      - id: release.proof.version_manifest_alignment.check
+        kind: steps
+        steps:
+          - Inspect package and plugin manifests.
+          - Inspect CLI and MCP version surfaces.
+          - Report mismatches before release.
+    observable_outcomes:
+      - Version and manifest claims point at the same release identity.
+    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: release.proof.clean_snapshot
+    title: Clean release snapshot
+    lifecycle: active
+    value_tier: core
+    journey_role: alternate
+    usage_frequency: occasional
+    tags:
+      - release
+      - git
+      - provenance
+    source_refs:
+      - kind: file
+        path: docs/release.md
+      - kind: file
+        path: scripts/release-gate.mjs
+    actor: script
+    intent: Record clean git status, commit, branch, matrix status, and release-gate evidence IDs.
+    preconditions:
+      - Release checks have run or are about to run.
+    trigger: Agent reports final merge or release readiness.
+    scenarios:
+      - id: release.proof.clean_snapshot.status
+        kind: steps
+        steps:
+          - Capture branch, commit, and git status.
+          - Capture matrix status and release-gate result.
+          - Report any dirty state or missing evidence before final claim.
+    observable_outcomes:
+      - Final readiness is tied to a concrete source snapshot.
+    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

package/use-cases/roadmap/deferred.yml

@@ -0,0 +1,184 @@
+schema_version: 1
+feature:
+  id: roadmap.deferred
+  name: Deferred product ideas
+  summary: Valuable future rows kept planned so they are visible but not active v1 acceptance.
+use_cases:
+  - id: roadmap.deferred.behavioral_host_evals
+    title: Behavioral host evals
+    lifecycle: planned
+    value_tier: supporting
+    journey_role: alternate
+    usage_frequency: rare
+    tags:
+      - hosts
+      - evals
+      - future
+    source_refs:
+      - kind: file
+        path: docs/hosts.md
+    actor: script
+    intent: Run model-triggering behavioral checks across hosts.
+  - id: roadmap.deferred.trusted_host_confirmation_path
+    title: Trusted host-native confirmation
+    lifecycle: planned
+    value_tier: core
+    journey_role: alternate
+    usage_frequency: rare
+    tags:
+      - hosts
+      - approval
+      - future
+      - security
+    source_refs:
+      - kind: file
+        path: docs/adr/0006-trusted-user-approval-path.md
+      - kind: file
+        path: packages/core/src/showcase/approvalAuthority.ts
+      - kind: file
+        path: docs/security.md
+    actor: user
+    intent: Let a real human grant a showcase sign-off through a trusted issuer that signs an approval token bound to the exact run, while an autonomous agent driving the same CLI/MCP cannot mint one. The verifier computes trust from the signature against the protected keyring; it never accepts a caller-supplied verified/confirmed flag. TTY confirmation is a weak, agent-spoofable fallback, not the trust root.
+    preconditions:
+      - A showcase run requires user approval (approval_policy approver_type user).
+      - A trusted approval issuer (host dialog, OS auth, WebAuthn, or out-of-band broker) is configured with a signing key outside the workspace.
+    trigger: A user-required showcase run is finished and awaits sign-off.
+    observable_outcomes:
+      - A real human can grant approval via a signed, nonce-bound, single-use token the plugin verifies against the keyring.
+      - An agent driving the CLI/MCP/terminal cannot produce a trusted approval; the run stays pending rather than being self-approved.
+      - Approval assurance is recorded by tier (host token / WebAuthn / weak TTY), and the weak tier is excluded from non-spoofable-required policies.
+  - id: roadmap.deferred.signed_audit_log
+    title: Cryptographically signed evidence ledger
+    lifecycle: planned
+    value_tier: supporting
+    journey_role: alternate
+    usage_frequency: rare
+    tags:
+      - evidence
+      - signing
+      - audit
+    source_refs:
+      - kind: file
+        path: docs/data-model.md
+    actor: script
+    intent: Add signing and tamper-evidence to JSONL events.
+  - id: roadmap.deferred.destructive_secret_purge
+    title: Destructive secret or legal purge
+    lifecycle: planned
+    value_tier: supporting
+    journey_role: failure
+    usage_frequency: rare
+    tags:
+      - evidence
+      - purge
+      - security
+    source_refs:
+      - kind: file
+        path: docs/security.md
+    actor: agent
+    intent: Physically purge sensitive accidental data with audit output.
+  - id: roadmap.deferred.git_diff_auto_mapping
+    title: Automatic diff-to-use-case mapping
+    lifecycle: planned
+    value_tier: supporting
+    journey_role: alternate
+    usage_frequency: rare
+    tags:
+      - matrix
+      - git
+      - automation
+    source_refs:
+      - kind: file
+        path: docs/data-model.md
+    actor: agent
+    intent: Infer impacted use cases from changed source files.
+  - id: roadmap.deferred.advanced_monorepo_scoping
+    title: Advanced monorepo component scoping
+    lifecycle: planned
+    value_tier: supporting
+    journey_role: edge
+    usage_frequency: rare
+    tags:
+      - matrix
+      - monorepo
+      - future
+    source_refs:
+      - kind: file
+        path: docs/data-model.md
+    actor: agent
+    intent: Manage multiple independent matrices inside one workspace.
+  - id: roadmap.deferred.direct_user_approval_write
+    title: Direct MCP user approval write
+    lifecycle: planned
+    value_tier: critical
+    journey_role: negative
+    usage_frequency: rare
+    tags:
+      - mcp
+      - approval
+      - future
+    source_refs:
+      - kind: file
+        path: docs/mcp.md
+    actor: user
+    intent: Allow MCP approval only with a trusted non-model confirmation token.
+  - id: roadmap.deferred.host_projection_conformance_tools
+    title: MCP host projection and conformance tools
+    lifecycle: planned
+    value_tier: supporting
+    journey_role: alternate
+    usage_frequency: rare
+    tags:
+      - mcp
+      - hosts
+      - future
+    source_refs:
+      - kind: file
+        path: docs/mcp.md
+    actor: agent
+    intent: Expose host project and conformance through MCP.
+  - id: roadmap.deferred.freshness_hard_gate_auto_selection
+    title: Automated freshness hard gates
+    lifecycle: planned
+    value_tier: supporting
+    journey_role: edge
+    usage_frequency: rare
+    tags:
+      - planning
+      - freshness
+      - future
+    source_refs:
+      - kind: file
+        path: docs/showcase.md
+    actor: agent
+    intent: Automatically block stale evidence from selected release or demo plans.
+  - id: roadmap.deferred.multi_machine_runner
+    title: Multi-machine scripted capsule runner
+    lifecycle: planned
+    value_tier: long_tail
+    journey_role: edge
+    usage_frequency: rare
+    tags:
+      - capsules
+      - runner
+      - future
+    source_refs:
+      - kind: file
+        path: docs/showcase.md
+    actor: script
+    intent: Run capsule scripts across multiple machines or environments.
+  - id: roadmap.deferred.registry_publish_channel
+    title: Public registry publication channel
+    lifecycle: planned
+    value_tier: supporting
+    journey_role: alternate
+    usage_frequency: rare
+    tags:
+      - release
+      - npm
+      - future
+    source_refs:
+      - kind: file
+        path: docs/release.md
+    actor: agent
+    intent: Prove public registry publishing metadata and install path.