PHASE-1-SHADOW-RUN: prepare requeue readiness gates

2026-08-06 14:23:38 +09:00
parent 6fc79c8ead
commit f09a65e909
2 changed files with 58 additions and 1 deletions
@@ -24,4 +24,4 @@ AEG-X-011,S4,Cross,Golden vector 고도화,BLOCKED,TBD,"AGENTS.md: Algorithm cha
 AEG-VS-09-01,S4,VS-09,BuildEvidenceSnapshot,BLOCKED,TBD,"CLAUDE.md: Evidence requires Phase 1 results",PM/Architect,"Gate 2 prerequisite. Blocked by Phase 1."
 AEG-VS-10-01,S4,VS-10,GenerateSellDecision,BLOCKED,TBD,"CLAUDE.md: Model must pass PBO/DSR validation",PM/Architect,"Gate 3 prerequisite. Blocked by Phase 1."
 AEG-VS-19-01,S5,VS-19,RunFrozenBacktest,BLOCKED,TBD,"CLAUDE.md: Requires evidence from Phase 1-4",PM/Architect,"Gate 3 prerequisite. Blocked by Phase 1."
-PHASE-1-SHADOW-RUN,S0-S5,Cross,252+ Trading Day Shadow Run,BLOCKED,TBD,"docs/CURRENT/PHASE-1_SHADOW_RUN_STATUS_CORRECTION.md; docs/CURRENT/AEG-X-004_DBUP_EVIDENCE.md; db/migrations/0032_shadow_run_queued_status_contract.sql; logs/phase-1-execution.log; logs/host-startup-20260804-173000.log",BE/SRE,"Status-contract correction and approved test-db rehearsal are complete (0032; targeted 1/1, DbUp 12/12, recovery 6/6). Job 893 was never started. Remains BLOCKED pending explicit re-queue approval, fresh Run/Job IDs, and production migration/DBA approval."
+PHASE-1-SHADOW-RUN,S0-S5,Cross,252+ Trading Day Shadow Run,BLOCKED,TBD,"docs/CURRENT/PHASE-1_SHADOW_RUN_STATUS_CORRECTION.md; docs/CURRENT/AEG-X-004_DBUP_EVIDENCE.md; docs/CURRENT/PHASE-1_REQUEUE_READINESS.md; db/migrations/0032_shadow_run_queued_status_contract.sql; logs/phase-1-execution.log; logs/host-startup-20260804-173000.log",BE/SRE,"Status-contract correction and approved test-db rehearsal are complete (0032; targeted 1/1, DbUp 12/12, recovery 6/6). Requeue readiness/preflight package is prepared. Job 893 was never started. Remains BLOCKED pending explicit approval, fresh Run/Job IDs, and production migration/DBA approval."
@@ -0,0 +1,57 @@
+# Phase 1 Shadow Run Requeue Readiness
+
+## Traceability
+
+- WBS: `PHASE-1-SHADOW-RUN`
+- Slice: requeue readiness and approval package
+- Source: `docs/CURRENT/WBS_EXECUTION_PROCEDURES.md`, `docs/CURRENT/PHASE-1_SHADOW_RUN_STATUS_CORRECTION.md`, `docs/CURRENT/AEG-X-004_DBUP_EVIDENCE.md`, `src/KArtSell.Host/Features/ShadowRun/API_CONTRACT.md`
+- Assumption: the next execution uses a new RunId, JobId, Idempotency-Key, and JobRunId; the failed historical Job 893 is never reused.
+- Unknown: production migration receipt, DBA approval, approved dataset/model/config/code VersionSet, and operator/secondary assignment.
+- Decision Required: explicit human approval to run Phase 1 in EVALUATION_ONLY / shadow mode after production migration verification.
+
+## Current evidence boundary
+
+- `0032_shadow_run_queued_status_contract.sql` is append-only and accepts the existing application `Queued` state.
+- Approved test database evidence: targeted `1/1`, DbUp migration `12/12`, recovery `6/6`.
+- Job 893 was never started; no historical run may be resumed or mutated.
+- Automatic order, KIS submission, model promotion, rollback automation, and threshold mutation remain disabled.
+
+## Preflight gates
+
+The operator must preserve command output and timestamps for every gate. A failed gate stops the procedure.
+
+1. Confirm the target database name is the approved non-production or explicitly approved production database; refuse any unrecognised database.
+2. Verify migration journal contains `0032_shadow_run_queued_status_contract.sql` and the `check_status` constraint includes `Queued`.
+3. Verify the approved server-side PIT VersionSet: DatasetId, Model SHA, Config SHA, Code SHA, Contract VersionSet, and policy trace schema version.
+4. Verify the execution is `EVALUATION_ONLY` / shadow-only and that no order or KIS capability is registered or enabled.
+5. Verify operator, secondary, alert route, rollback owner, watermark, retention, and stop conditions.
+6. Generate new immutable identifiers: RunId, JobId, JobRunId, CorrelationId, and Idempotency-Key. Do not reuse Job 893.
+7. Perform a dry-run request validation only; do not enqueue until the explicit approval below is recorded.
+
+## Approval record (required before enqueue)
+
+```text
+Approval ID:
+Approver / role:
+Operator / secondary:
+Target environment and database:
+Migration receipt:
+DatasetId / Model SHA / Config SHA / Code SHA:
+Contract VersionSet / policy trace schema version:
+New RunId / JobId / JobRunId / CorrelationId:
+Stop conditions acknowledged:
+Order/KIS capability confirmed OFF:
+Approval timestamp (UTC):
+```
+
+## Enqueue and observation boundary
+
+After approval, use the documented `POST /api/shadow-runs` contract with the new Idempotency-Key and preserve the HTTP response. Poll only the new RunId. Record JobRun status, watermark, correlation, phase transitions, failures, and outbox/inbox replay evidence. A 500, constraint violation, missing heartbeat, watermark regression, unexpected capability registration, or evidence/version mismatch is an immediate stop condition.
+
+## Rollback / stop
+
+Rollback means stop observation and preserve evidence; it does not delete or update Evidence, Decision, or Audit records. Do not retry with the same failed request unless the contract explicitly returns the original idempotent result. Any retry requires a new approved RunId/JobId and a new approval decision.
+
+## Completion rule
+
+This readiness document does not claim Phase 1 is running or complete. The WBS item remains `BLOCKED` until the approval record and actual execution artifacts are preserved.