@adammcarter/use-cases 0.1.0

package/use-cases/showcase/flow.yml

@@ -0,0 +1,269 @@
+schema_version: 1
+feature:
+  id: showcase.flow
+  name: Live showcase runner
+  summary: Performed demo runs that record observations, verdicts, decisions, finish state, and approval boundaries.
+use_cases:
+  - id: showcase.flow.live_acceptance_flow
+    title: Performed live acceptance flow
+    lifecycle: active
+    value_tier: critical
+    journey_role: golden
+    usage_frequency: common
+    tags:
+      - showcase
+      - live-demo
+      - acceptance
+    source_refs:
+      - kind: file
+        path: docs/showcase.md
+      - kind: file
+        path: packages/core/src/showcase/startRun.ts
+      - kind: file
+        path: packages/core/src/showcase/appendShowcaseEvent.ts
+    actor: agent
+    intent: Start a run, perform items, record observations and verdicts, finish, and derive status from events.
+    preconditions:
+      - A selected plan or ad hoc use-case set exists.
+    trigger: Agent is ready to prove work in front of the user or reviewer.
+    scenarios:
+      - id: showcase.flow.live_acceptance_flow.cli
+        kind: steps
+        steps:
+          - Start a showcase run from a selected plan or ad hoc item list.
+          - Record observation events for each item.
+          - Record pass, partial, fail, blocked, or waived verdicts.
+          - Finish the run and inspect status.
+    observable_outcomes:
+      - Run status is derived from events in the JSONL ledger.
+      - User approval is absent until a trusted approval event exists.
+    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: predefined
+      requirements:
+        - approver_type: user
+          minimum_count: 1
+      statement: User accepts the demonstrated showcase scope.
+  - id: showcase.flow.control_modes
+    title: Agent, user, script, and mixed control
+    lifecycle: active
+    value_tier: core
+    journey_role: alternate
+    usage_frequency: occasional
+    tags:
+      - showcase
+      - control-mode
+      - collaboration
+    source_refs:
+      - kind: file
+        path: docs/showcase.md
+      - kind: file
+        path: packages/core/src/showcase/types.ts
+    actor: agent
+    intent: Support agent-led, user-led, script-led, and mixed demonstrations without changing proof semantics.
+    preconditions:
+      - A showcase item can be driven by an agent, user, script, or combination.
+    trigger: User preference or feature mechanics determine who should run the demo.
+    scenarios:
+      - id: showcase.flow.control_modes.mixed
+        kind: steps
+        steps:
+          - Choose the control mode for each item.
+          - Record the actor for observations and verdicts.
+          - Preserve the same status and approval rules across modes.
+    observable_outcomes:
+      - Agent-led and script-led runs cannot claim user approval.
+      - Mixed runs still replay from the same JSONL event model.
+    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: showcase.flow.failure_decisions
+    title: Failure decision path
+    lifecycle: active
+    value_tier: core
+    journey_role: failure
+    usage_frequency: occasional
+    tags:
+      - showcase
+      - failure
+      - waiver
+      - pause
+    source_refs:
+      - kind: file
+        path: docs/showcase.md
+      - kind: file
+        path: packages/core/src/showcase/replayRun.ts
+    actor: agent
+    intent: When an item fails, require continue, pause_to_fix, waive_with_reason, or abort.
+    preconditions:
+      - A showcase item has failed, blocked, or partially satisfied its expected outcome.
+    trigger: Agent records a non-pass verdict during a live run.
+    scenarios:
+      - id: showcase.flow.failure_decisions.branch
+        kind: steps
+        steps:
+          - Record a failed or blocked verdict.
+          - Ask for or record a decision to continue, pause, waive, or abort.
+          - Keep final status honest about the decision path.
+    observable_outcomes:
+      - Failed items are not silently skipped.
+      - Waivers and pauses are visible in replayed status.
+    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: showcase.flow.revision_epoch_staleness
+    title: Revision epoch and stale verdicts
+    lifecycle: active
+    value_tier: core
+    journey_role: edge
+    usage_frequency: occasional
+    tags:
+      - showcase
+      - revision
+      - freshness
+    source_refs:
+      - kind: file
+        path: packages/core/src/showcase/revisionEpochs.ts
+      - kind: file
+        path: packages/core/src/showcase/replayRun.ts
+    actor: agent
+    intent: Mark affected verdicts stale when relevant code or data changes during a paused or resumed run.
+    preconditions:
+      - A paused or resumed showcase run crosses a relevant revision change.
+    trigger: Agent resumes a run after source, matrix, or plan inputs changed.
+    scenarios:
+      - id: showcase.flow.revision_epoch_staleness.resume
+        kind: steps
+        steps:
+          - Start or resume a run with a revision snapshot.
+          - Detect changed relevant inputs.
+          - Mark affected verdicts stale until re-performed.
+    observable_outcomes:
+      - Old verdicts do not silently remain current after relevant changes.
+    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: showcase.flow.approval_authority_boundary
+    title: Trusted approval boundary
+    lifecycle: active
+    value_tier: critical
+    journey_role: negative
+    usage_frequency: common
+    tags:
+      - showcase
+      - approval
+      - trust-boundary
+      - mcp
+    source_refs:
+      - kind: file
+        path: docs/security.md
+      - kind: file
+        path: packages/core/src/showcase/approvalAuthority.ts
+      - kind: file
+        path: packages/core/src/showcase/approval.ts
+    actor: agent
+    intent: Ensure agents, scripts, and MCP cannot fabricate user approval or rejection.
+    preconditions:
+      - A showcase run has reached a state where approval might be requested.
+    trigger: Agent or MCP attempts to record or request user approval.
+    scenarios:
+      - id: showcase.flow.approval_authority_boundary.negative
+        kind: steps
+        steps:
+          - Attempt noninteractive user approval.
+          - Confirm it is rejected or converted to a trusted confirmation requirement.
+          - Confirm no user approval event is appended by an untrusted path.
+    observable_outcomes:
+      - User approval requires the trusted interactive confirmation path.
+      - MCP can request approval but cannot write it directly.
+    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: showcase.flow.status_separation
+    title: Verdict, verification, run, and approval separated
+    lifecycle: active
+    value_tier: critical
+    journey_role: golden
+    usage_frequency: common
+    tags:
+      - showcase
+      - status
+      - approval
+    source_refs:
+      - kind: file
+        path: docs/showcase.md
+      - kind: file
+        path: packages/core/src/showcase/results.ts
+      - kind: file
+        path: packages/core/src/showcase/replayRun.ts
+    actor: agent
+    intent: Keep item verdict, verification state, run completion, and approval state distinct.
+    preconditions:
+      - A run has observations, verdicts, finish state, or approval state.
+    trigger: Agent inspects or reports showcase status.
+    scenarios:
+      - id: showcase.flow.status_separation.status
+        kind: steps
+        steps:
+          - Replay a showcase run.
+          - Report item verdicts, verification gaps, run completion, and approval separately.
+          - Avoid collapsing those states into one pass/fail label.
+    observable_outcomes:
+      - A run can be performed but unapproved, passed but missing user sign-off, or blocked with a clear reason.
+    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/showcase/live.yml

@@ -0,0 +1,44 @@
+schema_version: 1
+feature:
+  id: showcase.live
+  name: Live showcase
+  summary: Agents perform live demos and record user-visible outcomes.
+use_cases:
+  - id: showcase.live.user_signoff
+    title: Run a live showcase through user sign-off
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: common
+    tags: [showcase, signoff]
+    source_refs:
+      - kind: file
+        path: packages/core/src/showcase/appendShowcaseEvent.ts
+    actor: agent
+    intent: Prove finished work in front of the user.
+    preconditions: [A showcase item is selected.]
+    trigger: Agent finishes feature work.
+    scenarios:
+      - id: showcase.live.user_signoff.cli
+        kind: steps
+        steps:
+          - Generate a showcase plan and start the run from the saved plan file.
+          - Record observation and verdict.
+          - Finish the run.
+          - Request approval through MCP if needed, then record user approval through trusted interactive CLI confirmation.
+    observable_outcomes: [The run status shows passed with approval bound to the generated plan hash and finish event.]
+    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: predefined
+      requirements:
+        - approver_type: user
+          minimum_count: 1
+      statement: User sign-off is required for this showcase acceptance row.

package/use-cases/skills/assets.yml

@@ -0,0 +1,92 @@
+schema_version: 1
+feature:
+  id: skills.assets
+  name: Skill assets
+  summary: Ship and validate the agent skill assets (showcase, walkthrough, use-case matrix) so hosts can discover and run them without silent breakage.
+use_cases:
+  - id: skills.assets.asset_validation
+    title: Shipped skill assets validate
+    lifecycle: active
+    value_tier: core
+    journey_role: golden
+    usage_frequency: occasional
+    tags:
+      - skills
+      - doctor
+      - assets
+    source_refs:
+      - kind: file
+        path: packages/core/src/skills/validateSkillAssets.ts
+      - kind: file
+        path: .agents/skills/use-cases/SKILL.md
+      - kind: file
+        path: docs/activation.md
+    actor: script
+    intent: Confirm the shipped showcase, walkthrough, and use-cases skills have required files and well-formed front-matter.
+    preconditions:
+      - The plugin ships one or more agent skill directories under .agents/skills.
+    trigger: Agent or release gate runs doctor skills before publishing or activating a host.
+    scenarios:
+      - id: skills.assets.asset_validation.doctor
+        kind: steps
+        steps:
+          - Run doctor skills.
+          - Inspect each discovered skill name, required asset, and front-matter.
+          - Confirm every shipped skill reports as valid.
+    observable_outcomes:
+      - Each shipped skill is discovered with a stable name and intact assets.
+      - A skill cannot be published while its required files are missing.
+    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: skills.assets.degraded_assets
+    title: Damaged skill assets surface as diagnostics
+    lifecycle: active
+    value_tier: supporting
+    journey_role: edge
+    usage_frequency: rare
+    tags:
+      - skills
+      - doctor
+      - diagnostics
+    source_refs:
+      - kind: file
+        path: packages/core/src/skills/validateSkillAssets.ts
+      - kind: file
+        path: tests/skills/p7-skills.test.ts
+    actor: script
+    intent: Report missing or malformed skill files as diagnostics instead of silently passing them as healthy.
+    preconditions:
+      - A skill directory is missing a required file or carries malformed front-matter.
+    trigger: Agent runs doctor skills against a damaged or incomplete skill set.
+    scenarios:
+      - id: skills.assets.degraded_assets.report
+        kind: steps
+        steps:
+          - Run doctor skills against a skill missing required assets.
+          - Confirm the damaged skill is reported with a diagnostic.
+          - Confirm healthy skills remain usable and the run is non-fatal.
+    observable_outcomes:
+      - Damaged skills are visible rather than silently treated as valid.
+      - One damaged skill does not hide the status of the others.
+    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.yml

@@ -0,0 +1,9 @@
+schema_version: 1
+workspace_id: use-cases
+component_id: use-cases
+data_root: .
+use_cases_dir: use-cases
+evidence_dir: evidence
+demo_capsules_dir: demo-capsules
+showcase_runs_dir: showcase-runs
+default_workflow_mode: continuous