bootstrap/guides/e2e-delivery.md

E2E Delivery Procedure (MANDATORY)

This guide is REQUIRED for all agent sessions.

0. Mode Handshake (Before Any Action)

First response MUST declare mode before tool calls or implementation steps:

1. Orchestration mission: Now initiating Orchestrator mode...
2. Implementation mission: Now initiating Delivery mode...
3. Review-only mission: Now initiating Review mode...

1. PRD Gate (Before Coding)

1. Ensure docs/PRD.md or docs/PRD.json exists before coding.
2. Load ~/.config/mosaic/guides/PRD.md.
3. Prepare/update PRD from user input and available project context.
4. If requirements are missing:
   • proceed with best-guess assumptions by default,
   • mark each assumption with ASSUMPTION: and rationale,
   • escalate only when uncertainty is high-impact and cannot be bounded safely.
5. Treat PRD as the requirement source for implementation, testing, and review.

1a. Tracking Gate (Before Coding)

1. For non-trivial work, docs/TASKS.md MUST exist before coding.
2. If docs/TASKS.md is missing, create it from ~/.config/mosaic/templates/docs/TASKS.md.template.
3. Detect provider first via ~/.config/mosaic/rails/git/detect-platform.sh.
4. For issue/PR/milestone operations, use Mosaic wrappers first (~/.config/mosaic/rails/git/*.sh).
5. If external git provider is available (Gitea/GitHub/GitLab), create or update issue(s) before coding.
6. Record provider issue reference(s) in docs/TASKS.md (example: #123).
7. If no external provider is available, use internal task refs in docs/TASKS.md (example: TASKS:T1).
8. Scratchpad MUST reference both task ID and issue/internal ref.

2. Intake and Scope

1. Define scope, constraints, and acceptance criteria.
2. Identify affected surfaces (API, DB, UI, infra, auth, CI/CD, docs).
3. Identify required guides and load them before implementation.
4. For code/API/auth/infra changes, load ~/.config/mosaic/guides/DOCUMENTATION.md.
5. Determine budget constraints:
   • if the user provided a plan limit or token budget, treat it as a HARD cap,
   • if budget is unknown, derive a working budget from estimates and runtime limits, then continue autonomously.
6. Record budget assumptions and caps in the scratchpad before implementation starts.
7. Track estimated vs used tokens per logical unit and adapt strategy to remain inside budget.
8. If projected usage exceeds budget, auto-reduce scope/parallelism first; escalate only if cap still cannot be met.

2a. Steered Autonomy (Lights-Out)

1. Agent owns delivery end-to-end: planning, coding, testing, review, PR/repo operations, release/tag, and deployment (when in scope).
2. Human intervention is escalation-only; do not pause for routine approvals or handoffs.
3. Continue execution until completion criteria are met or an escalation trigger is hit.

3. Scratchpad Requirement

1. Create a task-specific scratchpad before implementation.
2. Record:
   • objective
   • plan
   • progress checkpoints
   • tests run
   • risks/blockers
   • final verification evidence

4. Embedded Execution Cycle (MANDATORY)

For implementation work, you MUST run this cycle in order:

1. plan - map PRD requirements to concrete implementation steps.
2. code - implement one logical unit.
3. test - run required baseline and situational checks for that unit.
4. review - perform independent code review on the current delta.
5. remediate - fix all findings and any test failures.
6. review - re-review remediated changes until blockers are cleared.
7. commit - commit only when the logical unit passes tests and review.
8. pre-push queue guard - before pushing, wait for running/queued project pipelines to clear: ~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push.
9. push - push immediately after queue guard passes.
10. PR integration - if external git provider is available, create/update PR to main and merge with required strategy via Mosaic wrappers.
11. pre-merge queue guard - before merging PR, wait for running/queued project pipelines to clear: ~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge.
12. CI/pipeline verification - wait for terminal CI status and require green before completion (~/.config/mosaic/rails/git/pr-ci-wait.sh for PR-based workflow).
13. issue closure - close linked external issue (or close internal docs/TASKS.md task ref when provider is unavailable).
14. greenfield situational test - validate required user flows in a clean environment/startup path (post-merge for trunk workflow changes).
15. deploy + post-deploy validation - when deployment is in scope, deploy to configured target and run post-deploy health/smoke checks.
16. repeat - continue until all acceptance criteria are complete.

Post-PR Hard Gate (Execute Sequentially, No Exceptions)

1. ~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main
2. ~/.config/mosaic/rails/git/pr-merge.sh -n <PR_NUMBER> -m squash
3. ~/.config/mosaic/rails/git/pr-ci-wait.sh -n <PR_NUMBER>
4. ~/.config/mosaic/rails/git/issue-close.sh -i <ISSUE_NUMBER> (or close internal docs/TASKS.md ref when no provider exists)
5. If any step fails: set status blocked, report the exact failed wrapper command, and stop.
6. Do not ask the human to perform routine merge/close operations.
7. Do not claim completion before step 4 succeeds.

Forbidden Anti-Patterns

1. Do NOT stop at "PR created" or "PR updated".
2. Do NOT ask "should I merge?" for routine delivery PRs.
3. Do NOT ask "should I close the issue?" after merge + green CI.

If any step fails, you MUST remediate and re-run from the relevant step before proceeding. If push-queue/merge-queue/PR merge/CI/issue closure fails, status is blocked (not complete) and you MUST report the exact failed wrapper command.

5. Testing Priority Model

Use this order of priority:

1. Situational tests are the PRIMARY gate and MUST prove changed behavior meets requirements.
2. Baseline tests are REQUIRED safety checks and MUST run for all software changes.
3. TDD is risk-based and REQUIRED only for specific high-risk change types.

6. Mandatory Test Baseline

For all software changes, you MUST run baseline checks applicable to the repo/toolchain:

1. lint (or equivalent static checks)
2. type checks (if language/tooling supports it)
3. unit tests for changed logic
4. integration tests for changed boundaries

7. Situational Testing Matrix (PRIMARY GATE)

Run additional tests based on what changed:

Change Surface	Required Situational Tests
Authentication/authorization	auth failure-path tests, permission boundary tests, token/session validation
Database schema/migrations	migration up/down validation, rollback safety, data integrity checks
API contract changes	backward compatibility checks, consumer-impact tests, contract tests
Frontend/UI workflow changes	end-to-end flow tests, accessibility sanity checks, state transition checks
CI/CD or deployment changes	pipeline execution validation, artifact integrity checks, rollback path check
Security-sensitive logic	abuse-case tests, input validation fuzzing/sanitization checks
Performance-critical path	baseline comparison, regression threshold checks

8. Risk-Based TDD Requirement

TDD is REQUIRED for:

1. bug fixes (write a reproducer test first)
2. security/auth/permission logic changes
3. critical business logic and data-mutation rules

TDD is RECOMMENDED (not mandatory) for low-risk UI, copy, styling, and mechanical refactors. If TDD is skipped for a non-required case, record the rationale in the scratchpad.

9. Mandatory Code Review Gate

If you modify source code, you MUST run an independent code review before completion.

1. Use automated review tooling when available.
2. If automated tooling is unavailable, run manual review using ~/.config/mosaic/guides/CODE-REVIEW.md.
3. Any blocker or critical finding MUST be fixed or tracked as an explicit remediation task before closure.

10. Mandatory Documentation Gate

For code/API/auth/infra changes, documentation updates are REQUIRED before completion.

1. Apply the standard in ~/.config/mosaic/guides/DOCUMENTATION.md.
2. Update required docs in the same logical change set as implementation.
3. Complete ~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md.
4. If publish platform is unspecified, ask the user to choose in-app or external platform before publishing.
5. Missing required documentation is a BLOCKER.

11. Completion Gate (All Required)

You MUST satisfy all items before completion:

1. Acceptance criteria met.
2. Baseline tests passed.
3. Situational tests passed (primary gate), including required greenfield situational validation.
4. PRD is current and implementation is aligned with PRD.
5. Acceptance criteria mapped to verification evidence.
6. Code review completed for source code changes.
7. Required documentation updates completed and reviewed.
8. Scratchpad updated with evidence.
9. Known risks documented.
10. No unresolved blocker hidden.
11. If deployment is in scope, deployment target, release version, and post-deploy verification evidence are documented.
12. docs/TASKS.md status and issue/internal references are updated to match delivered work.
13. If source code changed and external provider is available: PR merged to main (squash), with merge evidence recorded.
14. CI/pipeline status is terminal green for the merged PR/head commit.
15. Linked external issue is closed (or internal task ref is closed when no provider exists).
16. If any of items 13-15 fail due access/tooling, report blocked with exact failed wrapper command and do not claim completion.

12. Review and Reporting

Completion report MUST include:

1. what changed
2. PRD alignment summary
3. acceptance criteria to evidence mapping
4. what was tested (baseline + situational)
5. what was reviewed (code review scope)
6. what documentation was updated
7. command-level evidence summary
8. residual risks
9. deployment and post-deploy verification summary (if in scope)
10. explicit pass/fail status
11. tracking summary (docs/TASKS.md updates and issue/internal refs)
12. PR lifecycle summary (PR number, merge commit, merge method)
13. CI/pipeline summary (run/check URL, terminal status)
14. issue closure summary (issue number/ref and close evidence)