Spec slice: Delivery checklist and deployment evidence

[ganesh47]

Parent: #32

Source slice: docs/specs/cstack-delivery-checklist-deployment-evidence-slice.md

Delivery Checklist And Deployment Evidence Slice

Historical note:

• This document is a future slice spec, not part of the active shipped contract.
• The active shipped contract remains docs/specs/cstack-spec-v0.1.md.
• This slice defines how ship and deliver should grow a stronger final-delivery readiness contract.

Thesis

ship and deliver should evaluate a stronger repo-aware readiness contract that includes deployment evidence references, explicit checklist policy, and clearer blocker classification without making cstack responsible for running deployments.

Why This Slice Exists

Current ship and deliver already record:

• ship summaries
• release checklists
• unresolved blockers
• GitHub delivery evidence

What remains missing is a more explicit and inspectable final-delivery contract:

• which environments or deployment targets matter
• which evidence is required for handoff
• which checks or approvals are required by policy
• why a run is ready, blocked, or partial

Product Decision

This slice strengthens readiness evaluation and artifact quality around final delivery.

It explicitly stops short of:

• deployment orchestration
• environment mutation
• remote release execution beyond what current ship or deliver policy already allows

Scope

This slice owns:

• delivery checklist policy
• deployment evidence references
• required checks and approvals classification
• unresolved blocker taxonomy
• richer handoff artifacts for ship and deliver

This slice does not own:

• issue synthesis
• post-ship remediation generation beyond emitting handoff-ready data
• validation strategy design

Independent Team Contract

The delivery checklist team is responsible for:

• readiness policy model
• deployment evidence references
• upgraded ship and deliver artifacts
• inspector views for final-delivery evidence and blockers

The team is explicitly not responsible for:

• executing deployments
• changing GitHub planning lineage
• initiative-level grouping logic

Readiness Model

The first release should support explicit readiness dimensions such as:

• source change complete
• validation evidence complete
• review outcome acceptable
• required checks complete
• linked issue state acceptable
• release evidence complete when --release is active
• deployment evidence referenced when repo policy requires it

Recommended readiness outcomes:

• ready
• changes-requested
• blocked
• partial

Artifact Contract

Recommended upgrades:

• artifacts/release-checklist.md
• artifacts/ship-record.json
• artifacts/github-delivery.json
• artifacts/delivery-report.md

Recommended additions:

• artifacts/deployment-evidence.json
• artifacts/readiness-policy.json

Recommended meanings:

• deployment-evidence.json
  • references to environment, deployment, or release evidence relevant to final handoff
• readiness-policy.json
  • normalized checklist requirements and evaluated status for the run

Recommended readiness-policy.json shape:

{
  "mode": "release",
  "requirements": [
    {
      "name": "required-checks",
      "status": "satisfied"
    },
    {
      "name": "deployment-evidence",
      "status": "missing"
    }
  ],
  "overallStatus": "blocked"
}

Inspector Expectations

inspect should be able to show:

• readiness dimensions
• unresolved blockers by category
• deployment evidence references
• whether readiness was blocked by missing evidence, failed checks, or policy mismatch

Acceptance Criteria

This slice is complete when:

• ship and deliver can express a repo-aware readiness contract
• deployment evidence can be referenced and inspected without cstack owning deployment execution
• unresolved blockers are classified clearly
• final artifacts make handoff quality auditable

Release Boundary

First release for this slice should include:

• upgraded ship and deliver readiness artifacts
• deployment evidence references
• explicit readiness-policy evaluation
• inspector support for final-delivery evidence and blockers

It should not require:

• deployment automation
• post-ship feedback support
• initiative graph support

Non-Goals

This slice should not:

• claim that referencing deployment evidence equals executing deployments
• force environment-specific policy on repos that do not need it
• hide missing evidence inside vague readiness summaries

[ganesh47]

Kickoff note: this issue is now the independent execution thread for the delivery checklist and deployment evidence workstream under #32. A codebase-mapping agent is collecting exact touchpoints, first-slice scope, risks, and test coverage recommendations so implementation can proceed independently.

[ganesh47]

Autonomous team kickoff:

• Parent umbrella: Spec: end-to-end product delivery workstreams beyond gstack #32
• Source slice: use the spec body already attached to this issue as the contract.
• Execution rule: first release must be independently shippable and artifact-driven.
• Evaluation rule: prove product value, operational independence, and inspection quality.
• Deliverables for the first implementation slice:
  • explicit artifact schema
  • inspector or ledger impact
  • tests for the new artifact/reporting surface
  • clear non-goals to keep the slice bounded

[ganesh47]

Kickoff mapping from the current codebase:

First shippable slice:

• extend ship and deliver artifacts with explicit readiness policy and deployment evidence references
• improve blocker classification without running deployments
• surface readiness dimensions in inspect

Primary code touchpoints:

• src/types.ts
• src/ship.ts
• src/deliver.ts
• src/github.ts
• src/inspector.ts
• test/ship.test.ts
• test/deliver.test.ts
• test/inspect.test.ts

Constraint:

• deployment evidence is a reference surface, not deployment execution.

[ganesh47]

Autonomous workstream kickoff:

• Parent umbrella: Spec: end-to-end product delivery workstreams beyond gstack #32
• This workstream must ship a first useful release without waiting on the other five slices.
• The first implementation slice must define: artifact schema, inspector impact, tests, and explicit non-goals.
• Keep local artifacts as the durable source of truth.
• Record requested behavior separately from observed behavior.
• Do not add deployment execution in the first slice.

Repo tracker: docs/research/cstack-end-to-end-workstream-tracker.md

[ganesh47]

Execution kickoff:

• First shippable slice: add explicit readiness-policy and deployment-evidence artifacts for ship/deliver.
• Primary code touchpoints: src/ship.ts, src/deliver.ts, src/github.ts, src/inspector.ts, src/config.ts, src/types.ts.
• First tests: readiness-policy and deployment-evidence artifacts are written, policy-gated missing evidence blocks correctly, and inspector renders blocker categories and readiness dimensions.
• Constraint: this slice references deployment evidence but does not run deployments.

Tracker: docs/research/cstack-workstream-execution-tracker.md

[ganesh47]

Implementation kickoff from current codebase shape:

• Primary touchpoints: src/commands/ship.ts, src/ship.ts, src/commands/deliver.ts, src/deliver.ts, src/github.ts, src/inspector.ts, src/types.ts, and deliver/ship tests.
• First shippable slice:
  • add an explicit readiness-policy artifact for ship and deliver
  • add deployment-evidence references as data, not as deployment execution
  • improve blocker classification in ship/deliver summaries and inspector output
• Recommended first artifacts:
  • artifacts/readiness-policy.json
  • artifacts/deployment-evidence.json
• Keep the first release policy-first and evidence-first.
• Tests to add:
  • ship and deliver runs that are blocked specifically by missing deployment evidence
  • readiness-policy artifact generation for ready vs blocked outcomes
  • inspector output that distinguishes failed checks from missing evidence from policy mismatch

Non-goals for the first release:

• running deployments
• introducing environment-specific workflow execution
• post-ship monitoring

[ganesh47]

Autonomous kickoff note:

• Local tracker: docs/research/cstack-workstream-kickoff-tracker.md
• First shippable slice: add readiness-policy.json and deployment-evidence.json to ship and deliver, classify readiness dimensions explicitly, and render them in inspect without running deployments.
• Primary code touchpoints: src/types.ts, src/ship.ts, src/deliver.ts, src/github.ts, src/config.ts, src/inspector.ts.
• Initial tests: test/ship.test.ts, test/deliver.test.ts, test/inspect.test.ts, possibly test/config.test.ts.
• Non-goal for v1: do not execute deployments or force deployment evidence where policy does not require it.

[ganesh47]

Implementation status update: this workstream is now implemented.

Implemented:

• explicit delivery readiness policy and deployment evidence artifacts are written for ship and deliver
• blockers classified by dimension (checks/release/required-evidence/review/security/context) in artifacts
• inspect renders readiness policy and blocker taxonomy for transparent handoff
• readiness gate behavior now references deployment evidence requirements without running deployments

Verification: npm run typecheck and npm test (all suites pass), with targeted coverage in test/ship.test.ts and test/deliver.test.ts.

[ganesh47]

Completed by PR #46, merged into main on March 28, 2026 as commit 8c115d3.