sdcorejs-ship

name

sdcorejs-ship

description

Final delivery and dependency-update gate. Use for verify-before-done, branch readiness, ready-to-merge, ship/push/release/tag, update dependencies, update package, bump package, npm outdated, audit fix, or consistency checks before handoff. Owns verify-before-done, branch-ready, ship, dependency-update, and release-ready modes; delegates git artifacts to sdcorejs-git. Applies to all tracks and this repo. Runtime-localized.

Codex path resolution: Resolve ../_refs/... relative to this SKILL.md. Resolve another SDCoreJS skill by opening the sibling folder ../<skill-name>/SKILL.md.

Ship

Purpose And Boundary

Own the final delivery readiness boundary: prove the work satisfies the right contract, prove the branch hygiene evidence is current, and then hand off to artifact workflows only when the user explicitly asks for them.

sdcorejs-ship decides readiness. sdcorejs-git creates Git artifacts only after current ship and branch-ready evidence exists and the user explicitly asks for commit, PR, push, changelog, tag, or release artifacts.

sdcorejs-ship is responsible for:

• feature acceptance verification;
• bugfix verification;
• specless and docs-only hygiene verification;
• dependency-update safety verification;
• release readiness checks;
• final branch-ready checks;
• collecting evidence from explore, review, test, debug, repair-loop, and prior branch-ready contexts;
• producing ship_context.

sdcorejs-ship is not responsible for:

• committing changes, creating PRs, pushing branches, tagging releases, publishing packages, or creating release artifacts directly;
• patching review/debug/test failures from read-only verify or branch-ready gates;
• silently installing tools or downloading probe tools;
• bypassing sdcorejs-review, sdcorejs-test, sdcorejs-debug, sdcorejs-repair-loop, sdcorejs-git, or sdcorejs-explore.

Shared Protocols

Before executing this skill:

1. Read and apply ../_refs/shared/tasklist.md for non-trivial execution tasks.
2. Read and apply ../_refs/shared/persona.md if a project persona exists.
3. Read and apply ../_refs/shared/project-context.md for project memory, resume checkpoints, summaries, specs/plans, tasks, and relevant memories.
4. Current user request, current files, diffs, logs, failing tests, and command output override stored context.
5. Before presenting user-facing choices, approval gates, yes/no questions, or mode selections, read and apply ../_refs/shared/user-choice-prompt.md so options are sequential numbered choices.
6. Redact suspected secrets before printing evidence.

Mode Selection

Mode	Trigger examples	Output
verify-before-done	"verify", "verify acceptance", "is this done", "final gate"	verification report plus ship_context
branch-ready	"ready to merge", "branch ready", "check before PR", "ready to ship"	final read-only hygiene report plus ship_context
ship	"ship", "push it", "ready to merge", "create PR", "release"	write-producing tail steps, verification, final branch-ready, optional git handoff
dependency-update	"update dependencies", "update package", "bump ", "outdated", "audit fix"	protected-branch-safe dependency workflow plus regression evidence
release-ready	"release readiness", "prepare tag", "publish", "next tag"	release ledger, risk notes, final readiness verdict

If the user asks only for an artifact-only commit, PR, changelog, or release notes action, route to sdcorejs-git; that skill still rejects missing or stale ship evidence before creating delivery artifacts. If the prompt asks whether work is ready, should be pushed, can be merged, can be released, or is safe to ship, stay in sdcorejs-ship.

Verification Mode Classification

Classify verification_mode before selecting commands or criteria:

verification_mode	Use when
feature-acceptance	A spec, plan, product ledger, test plan, or explicit acceptance criteria exists and must be verified criterion by criterion.
bugfix-verification	A bug fix must verify original repro, regression evidence, and broader checks when available.
specless-verification	A small change has no explicit spec or AC; verify changed scope and report manual done confirmation needs.
dependency-regression	Package manifest or lockfile changes require dependency risk, install, audit where supported, and impacted checks.
docs-only-hygiene	Documentation, prompt, skill-text, or mirror-only changes need text/mirror/routing hygiene rather than product AC.
release-readiness	Tag, release, publish, or version preparation needs a release ledger and explicit approval for destructive actions.
branch-ready-only	The user asked only for final read-only branch hygiene before Git artifact handoff.

Rules:

• Do not treat every ship request as feature-acceptance.
• Bug fixes use bugfix-verification, not fabricated feature AC.
• Docs-only work may skip product acceptance but must still run applicable text, mirror, frontmatter, routing, and repo hygiene checks.
• Release/tag/publish requests use release-readiness; do not run tag, push, version bump, publish, or GitHub release commands from ship.
• Record verification_mode in ship_context.

Acceptance Scope Selection

Select acceptance_scope in this order:

1. Explicit user-provided spec, path, criteria, task ID, or release range.
2. Current task, plan, spec, or active workflow context.
3. Product ledger, plan ledger, or test plan associated with the current task.
4. review_context, repair_source, debug_context, or test_context from a caller.
5. Changed files and current diff scope.
6. If multiple plausible scopes remain, ask one numbered choice.

Record:

acceptance_scope:
  selected_spec:
  selected_plan:
  selected_task:
  changed_files_scope:
  criteria_count:
  manual_criteria:
  deferred_criteria:
  selection_reason:

Rules:

• Do not blindly pick the newest spec in a track folder.
• Do not default to Angular examples or any other track-specific sample.
• If no spec exists, use specless-verification or bugfix-verification instead of inventing AC.
• If multiple specs match and caller context does not disambiguate, ask the user to choose.

Evidence And Command Discipline

Discover verification commands from package manager, lockfiles, workspace configuration, package.json scripts, project config, original failing command, test_context, debug_context, review_context, repair_source, selected acceptance criteria, and repo docs.

Rules:

• Do not hardcode npm/npx as a universal default.
• Do not mix npm, pnpm, yarn, or bun.
• Do not invent missing scripts.
• Do not assume build, lint, test, e2e, typecheck, content, or i18n scripts exist.
• Do not use auto-download probe tools without explicit user approval.
• Missing scripts and unavailable tools go into commands_skipped with evidence.
• Prefer focused commands first, then broader checks when available and appropriate.
• In monorepos, respect workspace/package scope when detectable.
• commands_run includes only commands that actually ran.
• Do not mark skipped commands as PASS.

Mode: verify-before-done

Read ../_refs/orchestration/tail/verify-before-done.md completely, then run the selected verification mode.

Feature acceptance:

• Verify every explicit AC.
• Map each AC to evidence: command, test, manual check, file inspection, screenshot/probe, or deferred note.
• Mark each AC PASS, FAIL, MANUAL, DEFERRED, or NOT_APPLICABLE.
• Do not collapse multiple ACs into a generic "tests passed" claim.
• Manual/deferred criteria require explicit user acknowledgement.
• Any failed required AC makes the verdict BLOCKED.

Bugfix verification:

• Consume debug_context or repro evidence when present.
• Verify the original repro or evidence-equivalent focused repro.
• Run the focused regression test when available.
• Run broader discovered checks when appropriate.
• Confirm diagnostic instrumentation is removed or explicitly approved.
• If original repro cannot run locally, record the gap and do not claim fixed in that environment.

Specless/docs-only verification:

• Use changed file scope plus discovered repo hygiene.
• Do not invent product acceptance criteria.
• For docs-only or skill-text-only work, run mirror sync/check, text hygiene, prompt e2e/invariant tests, markdown/frontmatter validation, or equivalent discovered scripts when applicable.
• Report manual done confirmation needs when no objective AC exists.

If verification fails, route to:

• sdcorejs-repair-loop for fixable collections of findings from verify-before-done;
• sdcorejs-debug for concrete bug/root-cause failures;
• sdcorejs-test for missing or large test coverage work;
• sdcorejs-review for quality, security, performance, accessibility, or architecture review requests.

Pass this repair_source shape when invoking repair-loop:

repair_source:
  kind: verify-before-done
  verification_mode:
  acceptance_scope:
  original_commands:
  package_manager:
  failed_criteria:
  associated_HEAD_or_diff:

Do not patch source directly inside verify-before-done.

Mode: branch-ready

Read ../_refs/orchestration/tail/branch-ready.md completely, then run its read-only hygiene checks.

Branch-ready is the final read-only gate immediately before sdcorejs-git creates commit, PR, push, tag, or release artifacts. No writes after branch-ready unless branch-ready is run again.

Rules:

• Branch-ready mode is read-only.
• Evidence must be tied to the current HEAD plus dirty diff or exact clean HEAD.
• If any source, docs, mirror, changelog, release-note, task, memory, formatting, codegen, or lockfile write happens after branch-ready, evidence is stale and branch-ready must run again.
• Branch-ready blockers are not waivable for commit, PR, push, tag, or release artifacts. A user may request draft/manual notes, but the branch-ready verdict remains BLOCKED.

Mode: ship

Use for "done, ship it", "push it", "ready to merge", "create PR", or release requests.

Preferred order:

1. Preflight and resolve delivery_type, mode, and verification_mode.
2. Collect and freshness-check explore_context, review_context, test_context, debug_context, repair_source, and any prior branch_ready_evidence.
3. Complete selected write-producing tail steps before final branch-ready: code documentation, technical docs, user guide, auto-docs/session docs, task tracker, memories, generated mirrors, changelog, and release notes when selected or approved.
4. Run verify-before-done or the appropriate verification mode over the final intended diff.
5. Run branch-ready as the final read-only gate over the final diff.
6. Produce ship_context.
7. Delegate to sdcorejs-git only if the user explicitly asked for commit, PR, push, changelog, tag, or release artifacts and final evidence is current.

If any workflow verifies before docs or changelog writes, re-run branch-ready after those writes. No writes after branch-ready unless branch-ready is run again.

Mode: dependency-update

Use dependency updates as a protected-branch-safe delivery workflow.

Protected Branch Hard Stop

Dependency updates on protected branches are a hard stop. Protected branches include main, master, trunk, production, stable, release/*, and any repo-defined protected branch.

Do not modify package manifests, lockfiles, or config on a protected branch. There is no continue-on-protected-branch option. Offer only:

1. Create a feature branch and continue.
2. Create an isolated worktree.
3. Stop.

Dependency Classification

Classify update type:

• patch
• minor
• major
• security-fix
• transitive-lockfile-only
• dev-only
• runtime
• toolchain

Do not update multiple unrelated dependency groups unless the user approved that scope. Do not silently change package manager or lockfile format. Do not run broad update, audit fix, or force commands that modify many packages unless the user explicitly requested and approved the exact action.

Package-Manager-Specific Command Matrix

Detect the actual package manager first. If project policy uses a custom dependency script, follow that script instead of generic commands.

Package manager	Install existing lockfile	Add/update package	Update existing package	Audit
npm	npm install or npm ci when appropriate and supported by policy	npm install <pkg>@<version> --save-exact when exact pinning is desired	npm update <pkg> where appropriate	npm audit or npm audit --omit=dev only if supported
pnpm	pnpm install	pnpm add <pkg>@<version> --save-exact when exact pinning is desired	pnpm update <pkg> where appropriate	pnpm audit if supported
yarn	yarn install	yarn add <pkg>@<version> --exact when exact pinning is desired	yarn up <pkg>@<version> or project-supported equivalent depending on Yarn version	only when supported by Yarn version/tooling
bun	bun install	bun add <pkg>@<version> --exact when exact pinning is desired	project-supported update command only	skip with evidence if unsupported

Rules:

• Do not run npm commands in pnpm, yarn, or bun repos.
• Do not invent unsupported audit/update commands.
• Record commands_run and commands_skipped.
• Run impacted tests, build, typecheck, lint, and smoke checks only when discovered and relevant.
• Route regressions to sdcorejs-debug or sdcorejs-repair-loop; do not weaken checks to make the update pass.

Mode: release-ready

Use for release, tag, publish, version, or "next tag" requests.

Collect release evidence:

release_evidence:
  release_type: patch | minor | major | prerelease | hotfix | docs-only | unknown
  version_source: package.json | changelog | tag | user-provided | unknown
  release_range: explicit range | latest tag..HEAD | base..HEAD | unknown
  changelog_status: present | generated | needed | skipped
  version_bump_status: approved | not approved | not applicable
  tag_status: approved | not approved | not created
  publish_status: approved | not approved | not run
  branch_status: protected | feature/release branch | unknown
  ci_status:
  compatibility_risk:
  rollback_plan:
  manual_approval_requirements:

Rules:

• Do not create tags by default.
• Do not push tags by default.
• Do not bump versions by default.
• Do not create GitHub releases by default.
• Do not publish packages by default.
• Do not push release branches by default.
• Every destructive release action requires explicit approval.
• Release readiness may delegate changelog or release-note artifact writing to sdcorejs-git (changelog mode), but changelog and release notes are write-producing artifacts and branch-ready must run after those writes.
• Final release verdict is READY, READY_WITH_WARNINGS, BLOCKED, or DEFERRED.

Context Freshness

Consume evidence from:

• explore_context;
• test_context and test_evidence;
• debug_context;
• review_context;
• repair_source or repair ledger;
• prior branch_ready_evidence.

Treat context evidence as stale if files changed after it was produced or if associated_HEAD_or_diff does not match the current diff. Re-run relevant checks when evidence is stale. Do not substitute review, test, or debug evidence for an AC unless it actually verifies that criterion.

Secret And PII Redaction

Never echo secret values from .env, CI files, shell output, source files, stack traces, audit output, package-manager logs, Git diffs, network logs, Authorization headers, cookies, JWTs, API keys, database URLs, private keys, passwords, customer PII, or production payloads.

Rules:

• Never print full lines that contain likely secret values.
• For suspected secrets, report only path, key/category, reason, and redacted evidence such as API_KEY=[REDACTED].
• Do not include secrets in ship_context, final summaries, changelog, release notes, commit messages, or PR bodies.
• Suspected secrets in the diff make branch-ready BLOCKED.

Mode-Specific Write Boundaries

• verify-before-done mode is read-only. It may invoke repair-loop, debug, test, or documentation as separate workflows, but it must not patch source directly.
• branch-ready mode is read-only.
• ship mode may orchestrate write-producing downstream workflows before final branch-ready and must record those writes in ship_context.
• dependency-update mode may edit package manifests and lockfiles only after branch/protected-branch safety and explicit update scope are clear.
• release-ready mode may prepare changelog or release notes only when selected/approved, but must not tag, push, publish, or bump versions without explicit approval.
• Do not commit or create PRs from sdcorejs-ship.

ship_context Output

Every sdcorejs-ship output includes a redacted ship_context block:

ship_context:
  source: sdcorejs-ship
  mode: verify-before-done | branch-ready | ship | dependency-update | release-ready
  verification_mode: feature-acceptance | bugfix-verification | specless-verification | dependency-regression | docs-only-hygiene | release-readiness | branch-ready-only
  delivery_type: feature-pr | bugfix | docs-only | dependency-update | release | manual-check | unknown
  target_root:
  current_HEAD:
  associated_HEAD_or_diff:
  acceptance_scope:
    selected_spec:
    selected_plan:
    selected_task:
    changed_files_scope:
    criteria_count:
    manual_criteria:
    deferred_criteria:
    selection_reason:
  verification:
    commands_run:
      - command:
        result:
        exit:
        associated_HEAD_or_diff:
    commands_skipped:
      - command_or_probe:
        reason:
    criteria:
      - id:
        status: PASS | FAIL | MANUAL | DEFERRED | NOT_APPLICABLE
        evidence:
    result: PASS | FAIL | PARTIAL | SKIPPED
  contexts_consumed:
    explore_context:
    test_context:
    debug_context:
    review_context:
    repair_source:
  writes_before_branch_ready:
    - path:
      writer_skill:
      reason:
  writes_after_branch_ready:
    - path:
      writer_skill:
      reason:
  branch_ready_evidence:
    result:
    commands_run:
    commands_skipped:
    associated_HEAD_or_diff:
  dependency_evidence:
    update_type:
    package_manager:
    packages:
    commands_run:
    commands_skipped:
    audit_result:
  release_evidence:
    version:
    range:
    changelog:
    tag_approval:
    publish_approval:
  manual_deferrals:
    - item:
      reason:
      approved_by_user: true | false
  final_verdict: READY | READY_WITH_WARNINGS | BLOCKED | DEFERRED
  git_handoff_allowed: true | false
  git_handoff_reason:

Rules:

• ship_context must not contain secrets.
• commands_run includes only commands actually run.
• Do not claim a result as PASS if it was skipped.
• associated_HEAD_or_diff must tie evidence to the current diff or HEAD.
• If writes_after_branch_ready is non-empty, final_verdict cannot be READY for Git handoff until branch-ready runs again.
• git_handoff_allowed is true only when final branch-ready evidence is current and the user requested Git artifacts.

Cross-References

• ../_refs/shared/finish-gate.md - consolidated post-code options and final branch-ready ordering.
• ../_refs/orchestration/tail/verify-before-done.md - verification mode and acceptance evidence gate.
• ../_refs/orchestration/tail/branch-ready.md - final read-only hygiene gate.
• sdcorejs-git - commit, PR, changelog, release notes, tag/release artifacts.
• ../_refs/angular/core-version.md - pinned Core UI version guard for Angular dependency updates.
• sdcorejs-repair-loop - fixes failed review or verification findings.
• sdcorejs-debug - root-cause workflow for concrete failures.
• sdcorejs-test - test authoring and test evidence.
• sdcorejs-review - read-only quality evidence.
• sdcorejs-explore - project context and recovery evidence.