Ship

7. Repo Quality Standards

Before creating the PR, verify the standards in ship/references/repo-quality-standards.md (README links, PR/commit quality, repo hygiene). The public repo is the face of the project. ship/bin/quality-check.sh automates the checks it can; use judgment for the rest.

After shipping, do these steps in order:

Step 1: Save the artifact. Run this command now — do not skip it. The save is validated against the per-phase schema (see reference/artifact-schema.md); a normal-mode ship artifact requires summary (object) and context_checkpoint. Report-only ship runs may save a looser shape with run_mode: "report_only".

The snippet below sets safe JSON defaults first so jq --argjson does not fail when a shell variable is unset (PR_NUMBER may legitimately be unset in local-mode ships, on a no-PR push, or when CI has not reported yet).

# Safe defaults so --argjson always gets valid JSON, even when a
# variable was not exported in this ship path.
: "${PR_NUMBER:=null}"
: "${PR_URL:=}"
: "${PR_TITLE:=}"
: "${PR_STATUS:=open}"
: "${CI_PASSED:=false}"

SHIP_JSON=$(jq -n \
  --argjson pr_number "$PR_NUMBER" \
  --arg     pr_url    "$PR_URL" \
  --arg     title     "$PR_TITLE" \
  --arg     status    "$PR_STATUS" \
  --argjson ci_passed "$CI_PASSED" \
  --arg     checkpoint_summary "PR #N <title> shipped, CI status, deploy result." \
  '{
     phase: "ship",
     summary: {
       pr_number: $pr_number,
       pr_url:    $pr_url,
       title:     $title,
       status:    $status,
       ci_passed: $ci_passed
     },
     context_checkpoint: {
       summary: $checkpoint_summary,
       key_files: [],
       decisions_made: [],
       open_questions: []
     }
   }')
~/.claude/skills/nanostack/bin/save-artifact.sh ship "$SHIP_JSON"
~/.claude/skills/nanostack/bin/sprint-journal.sh

For a report-only ship (no PR cut, no commit), save the artifact with run_mode: "report_only" instead so the validator accepts the looser shape:

~/.claude/skills/nanostack/bin/save-artifact.sh ship \
  '{"phase":"ship","run_mode":"report_only","summary":"Pre-flight check only; nothing was pushed."}'

Step 2: Proof block. Before "How to see the result", emit a proof block summarizing what was verified during the sprint. Read it from session phase_log:

SESSION=$NANOSTACK_STORE/session.json
[ -f "$SESSION" ] || SESSION="$HOME/.nanostack/session.json"
jq -r '
  ([.phase_log[]? | select(.phase == "review"   and .status == "completed")] | length) as $rev   |
  ([.phase_log[]? | select(.phase == "security" and .status == "completed")] | length) as $sec   |
  ([.phase_log[]? | select(.phase == "qa"       and .status == "completed")] | length) as $qa    |
  "Reviewed: \(if $rev   > 0 then "yes" else "no" end)\n" +
  "Security checked: \(if $sec > 0 then "yes" else "no" end)\n" +
  "QA checked: \(if $qa  > 0 then "yes" else "no" end)"
' "$SESSION" 2>/dev/null

If a phase says no, list it under "Not verified" so the user sees what was skipped instead of inferring it from absence.

Step 3: How to see the result.

Read profile from session per reference/session-state-contract.md. The branch differs by profile:

If profile == "guided" (or no git remote, even when professional): Skip the deployment menu and focus on how to try the result locally. Tell the user where the entry point is and the exact command to run, then list anything that is not yet verified (e.g. "I did not deploy this to the internet"). One next action only. Follow reference/plain-language-contract.md for wording. Example:

<!-- guided-output:start -->

Resultado: Listo para probar.

Como verlo:
1. Abri index.html en el navegador.

Que revise:
- La pantalla carga.
- El boton principal responde.
- No encontre secretos en archivos visibles.

Pendiente:
- No esta publicado en internet todavia.
- No revise la seguridad de las dependencias.

<!-- guided-output:end -->

If profile == "professional" and autopilot == true: Skip this question. Go directly to Next Step (compound + sprint summary). The user will decide how to run it after the sprint closes.

Otherwise (professional, manual), ask:

How do you want to see it?

1. Local — I'll start the server and show you how to open it
2. Production — I'll guide you through deploying to the internet
3. I'm done — just the commit

If Local (option 1):

• HTML files: "Open index.html in your browser"
• Web apps: start the server (npm start, node src/server.js, etc.) and tell the user the URL
• CLI tools: show the command to run it
• Never auto-open URLs or execute open commands. Show the path and let the user decide.

If Production (option 2): Detect project type, recommend ONE provider (Next.js→Vercel, Node→Railway, Static→Cloudflare Pages, Python→Railway, Go→Fly.io). Walk through: account, connect repo, env vars, push. Mention domain (~$10/yr), SSL (automatic), monitoring (Sentry free + UptimeRobot free). Show monthly cost.

If Done (option 3): Skip to next features.

Report output (report-only mode only)

When RUN_MODE == "report_only", this is the only section that runs. It produces a summary the user can read and act on; the agent itself does not commit to any action.

The report has four blocks:

1. What would ship. Branch name (or "no git remote"), staged files, commit message that would be used, PR title and body that would be filed.
2. What is verified. Read fresh artifacts from .nanostack/. List which of review / security / qa are present and pass. Use bin/find-artifact.sh <phase> 1 to confirm freshness. If any are missing or stale, name them.
3. What is not verified. Anything the report could not check: deploy target, post-deploy canary, dependencies, integration with downstream services. State this honestly; do not hide gaps.
4. What the user can do next. Exactly the commands needed to ship for real, in order. Example:

   To ship for real:
     /review     # missing
     /security   # missing
     /qa         # missing
     session.sh init development --run-mode normal
     /ship

Use the wording in reference/plain-language-contract.md when PROFILE == "guided" (Resultado / Como verlo / Que revise / Pendiente). Professional output may keep technical terms (PR, CI, branch).

Stop after printing the report. Do not call telemetry-finalize with success; pass report_only so the event reflects what actually happened.

Output Format

Close with a summary:

Ship: PR #N created. CI passed.
Tests: X → Y (+N new). No regressions.

Include before/after test counts when tests were added. Quantify the improvement.

Gotchas

• Run tests before creating PR. CI is slower than catching it locally.
• One PR = one concern. Split unrelated changes.
• Check existing PRs before creating yours. Search first.
• Read CONTRIBUTING.md. Every project has different rules.

Telemetry finalize

Before handing off to compound or the user:

_F="$HOME/.claude/skills/nanostack/bin/lib/skill-finalize.sh"
[ -f "$_F" ] && . "$_F" ship success
unset _F

Pass abort or error instead of success if ship did not complete normally.

Next Step

After shipping, two things happen in order:

First: capture learnings. Run compound immediately:

Use Skill tool: skill="compound"

Do not ask. Do not skip. Compound reads the sprint artifacts and saves solutions for future sprints.

Then: close the sprint. This is the last thing the user sees. Make it count.

1. What was built. Summarize what the user now has in plain language. Not phase names or artifact counts. What does the thing DO, where is it, and how to use it.

2. How to use it. Show the exact command or URL to try it right now.

3. What could come next. Suggest 2-3 concrete extensions as /feature commands the user can run immediately.

Example:

Sprint complete. You have a JSON validator CLI.

Try it: node src/index.js test.json

Ideas for the next feature:

• /feature Add --format flag to pretty-print valid JSON
• /feature Add directory mode: jsonlint schemas/*.json
• /feature Add --fix mode that auto-corrects trailing commas