deliver

name: deliver description: "Package pipeline outputs into structured deliverables: artifact bundles, PR descriptions, decision logs, attention flags, and delivery reports. Bridges .artifacts/ (working memory) to Knowledge/
\ (long-term memory).\n TRIGGER: "deliver this", "package for review", "create delivery report", "wrap up this feature".\n NOT FOR: for ongoing work (just keep building), or for shipping/deploying
\ code (future ship skill)." consumes_artifacts:

• evaluation
• research
• alternatives
• design_doc
• changeset
• review
• test_report produces_artifact: delivery tier: always

Delivery Packaging

The terminal stage of the lifecycle pipeline. Assembles all artifacts from a pipeline run into a structured deliverable that humans (or future pipeline runs) can review, approve, and act on.

Works at L0 (generates a session summary report). Full artifact bundling at L1+.

What Delivery Produces

Workflow

Step 1: Gather Artifacts

Collect all artifacts from the current pipeline run:

L0 (no project):

• Scan the current session for: code changes, decisions made, issues found
• No artifacts to read — derive from conversation

L1+ (project with .artifacts/):

• Read manifest.json for all artifacts in the current pipeline run
• Load each active artifact's summary and key data points
• Check pipeline state — delivery should be the terminal state

Artifacts to collect (in pipeline order):
  evaluation  -> scope, acceptance criteria, ROI score
  research    -> key findings, sources
  alternatives -> chosen approach, rejected approaches + reasons
  design_doc  -> decisions, API contract, data model
  changeset   -> files changed, commits, branch
  review      -> findings, approval status, security issues
  test_report -> pass/fail, bugs fixed, remaining issues

Step 2: Assemble Delivery Report

## Delivery Report: <feature/task title>

### Summary
<2-3 sentences: what was built, why, and current status>

### Pipeline Path
EVALUATE -> THINK -> PLAN -> BUILD -> REVIEW -> TEST -> DELIVER
(checkmarks for completed stages, X for skipped)

### What Was Built
- <key change 1: file/component + what changed>
- <key change 2>
- <key change 3>

### Key Decisions
| Decision | Rationale | Alternative Considered |
|----------|-----------|----------------------|
| <decision 1> | <why> | <what was rejected> |

### Quality Summary
- **Tests:** X passed, Y failed, Z fixed during QA
- **Security:** N findings (M auto-fixed, K reported)
- **Review:** <approval status>

### Unresolved Issues
1. <issue + file:line + severity>
2. <issue + diagnosis + suggested fix>

### Attention Flags (Human Review Needed)
- [ ] <item requiring human decision>
- [ ] <item requiring human review>

### Suggested Next Actions
1. <action 1>
2. <action 2>

Step 3: Generate PR Description (if changeset exists)

## Summary
<1-3 bullet points from delivery report>

## Changes
<file list from changeset artifact, grouped by domain>

## Test Results
<from test_report artifact>

## Design Decisions
<from design_doc artifact — key choices and rationale>

## Review Notes
<from review artifact — addressed findings>

Step 4: Update Project Context

PROJECT.md — append to Recent Decisions:

- YYYY-MM-DD: <feature> delivered. Key decisions: <list>. Follow-ups: <list>.

IMPROVEMENT.md — the writeback hook handles this automatically, but delivery can add high-level lessons:

- YYYY-MM-DD (delivery): <pattern that worked / failed across the full pipeline>

Step 5: Publish Delivery Artifact

{
  "title": "Feature X delivery",
  "status": "complete",
  "artifacts_included": ["evaluation", "design_doc", "changeset", "review", "test_report"],
  "summary": "...",
  "decisions": [{"decision": "...", "rationale": "..."}],
  "quality": {
    "tests_passed": 45,
    "tests_failed": 0,
    "security_findings": 2,
    "review_approved": true
  },
  "unresolved": [{"issue": "...", "severity": "medium", "suggestion": "..."}],
  "attention_flags": ["..."],
  "next_actions": ["..."]
}

Step 6: Advance Pipeline State

advance_pipeline(project, "reflect")  # Terminal state

Step 7: Offer to Save Report

Ask the user:

"Want me to save this delivery report to Knowledge/Reports/?"

If yes, save as Knowledge/Reports/YYYY-MM-DD-<feature>.md.

L0 Behavior (No Project)

Without artifacts, delivery is a session summary report:

1. Scan the conversation for: files created/modified, decisions made, issues found
2. Generate a lighter version of the delivery report (no artifact references)
3. Offer to save to Knowledge/Reports/

Still valuable — structures the session's output for future reference.

Rules

• Never skip attention flags — if review had unresolved findings or QA had remaining bugs, they MUST appear as attention flags
• Don't duplicate IMPROVEMENT.md writeback — the hook handles per-lesson extraction. Delivery adds pipeline-level insights only.
• PR description is optional — only generate if changeset artifact exists
• Keep the report scannable — tables and bullet points over paragraphs. A busy human should understand the delivery in 30 seconds.
• Delivery is the pipeline's receipt — it marks completion and provides the audit trail for what was built, why, and what remains.

Escalation Protocol

L0 INFORM (clean delivery)

When all upstream stages passed without issues:

> [INFORM] **Delivery ready: <feature>** — all tests pass, review clean,
> no open escalations. PR description generated.

L2 BLOCK (unresolved issues)

When upstream stages have unresolved escalations or critical findings:

> [BLOCK] **Cannot deliver: N unresolved items from upstream stages**
>
> These must be addressed before delivery:
> 1. [REVIEW] Critical security finding in auth.py (confidence 9/10)
> 2. [TEST] WTF gate halted — 3 unfixed bugs remain
>
> **Options:**
> 1. Fix the issues first (re-run review + QA)
> 2. Deliver with known issues (add to attention flags)
> 3. Defer delivery — needs more work

Artifact Operations

Discover all upstream artifacts (first step):

python backend/scripts/artifact_cli.py discover --project <PROJECT> \
  --types evaluation,research,alternatives,design_doc,changeset,review,test_report --full

Publish delivery artifact:

python backend/scripts/artifact_cli.py publish \
  --project <PROJECT> --type delivery --producer s_deliver \
  --summary "Feature complete: <title>" \
  --data '<JSON of delivery output>'

Advance pipeline to reflect:

python backend/scripts/artifact_cli.py advance --project <PROJECT> --state reflect

Verification

Before marking this task complete, show evidence for each:

• Delivery report generated — structured report shown in chat with Summary, What Was Built, Key Decisions, and Quality Summary sections
• Artifacts bundled — all upstream artifacts (evaluation, design_doc, changeset, review, test_report) collected and referenced in the report
• PR description created — if a changeset exists, a formatted PR description with Changes, Test Results, and Design Decisions is produced
• Attention flags surfaced — unresolved findings from review/QA stages appear as explicit attention flags (or confirmed none exist)
• PROJECT.md updated — delivery decision appended to Recent Decisions with date and follow-ups noted