SniperGold_ML/docs/AI_ASSISTANT_SESSION_START_PROTOCOL_v2.md

# AI ASSISTANT SESSION START PROTOCOL — v2

```text
Document type : GOVERNANCE
DOCUMENT ROLE : GOVERNANCE_POLICY
Created       : 2026-08-28 (P3-GOV-3 — AI ASSISTANT CONTEXT, AUTHORITY & VERIFICATION CONTROL)
Version       : v2
Supersedes    : v1 remains in the repository UNCHANGED (v1 preserved unchanged)
                and is referenced for its historical content.
MANDATORY for every new AI session in this repository.
Authority     : This protocol defines HOW evidence is classified and reconciled.
                It does not itself authorize any execution.
```

## 1. Purpose

This v2 protocol hardens the session-start discipline against:

- stale Markdown; conflicting current-state documents;
- self-generated unverified assumptions; silent verifier defects;
- manual SHA transcription errors; CRLF/LF editing errors;
- mutable-state capture errors;
- accidental promotion of unverified Markdown into project truth;
- premature PASS/COMPLETE classifications;
- confusion between project state and execution authorization.

Every new session must be deterministic about:

```text
WHAT IS FACT
WHAT IS AUTHORIZATION
WHAT IS HISTORY
WHAT IS EVIDENCE
WHAT IS CONTRACT
WHAT IS ONLY A SUMMARY
```

## 2. Mandatory reading order (every new session)

1. `docs/CURRENT_PROJECT_STATE.md` (factual snapshot; read, but it never authorizes).
2. `docs/CURRENT_DECISION_GATE.md` (authorization / prohibition; the ONLY doc that represents owner authorization).
3. Newest `docs/SESSION_HANDOVER_*.md` (continuity / recovery context).
4. This protocol `docs/AI_ASSISTANT_SESSION_START_PROTOCOL_v2.md`.
5. `docs/CODE_VERIFICATION_AND_SILENT_BUG_POLICY_v1.md` (verification discipline).
6. Canonical machine evidence: the real checkpoint
   `ml/p3/p3_s251_external_ingest/output/s251_real_checkpoint.json` (FACTUAL EXECUTION STATE).
7. `docs/PROJECT_PHASE_INDEX.md`, `docs/PROJECT_STATE_TRANSITION_MAP.md`,
   `docs/EVIDENCE_STATUS_REGISTER.md`, `docs/FROZEN_ASSET_REGISTER.md`.

Do NOT assume any document is authoritative merely because its filename says
CURRENT, AUTHORITATIVE, FINAL, VERIFIED, or COMPLETE. Filenames are labels, not
authority.

## 3. Git preflight (every new session)

```text
git rev-parse HEAD
git ls-remote origin HEAD
git branch --show-current
git status --short
git stash list
git remote -v
```

Required:

```text
branch          = main
local HEAD      == origin/main
working tree    CLEAN
stash           EMPTY
untracked       NONE
origin          = SniperGold_ML.git
```

If any check fails: STOP. Do NOT repair automatically.

## 4. Document Authority Map (canonical authority hierarchy)

Every `.md` document is assigned exactly ONE authority role. A document must
NOT silently serve more than one role. Role headers are mandatory where
practical:

```text
DOCUMENT ROLE:
FACTUAL_STATE | AUTHORIZATION | HANDOVER | EVIDENCE_REGISTER
| HISTORICAL | TECHNICAL_CONTRACT | PUBLIC_SUMMARY | GOVERNANCE_POLICY
```

| Document / artifact | Authority role | It defines | It MUST NOT define |
| ------------------- | -------------- | ----------- | ------------------ |
| Real checkpoint / machine manifests / machine test results / immutable state records | CANONICAL MACHINE EVIDENCE | FACTUAL EXECUTION STATE: cursor, last completed chunk, next chunk, byte offsets, cumulative counts, checkpoint state, machine-verifiable results | authorization |
| `CURRENT_PROJECT_STATE.md` | FACTUAL_STATE | HUMAN-READABLE FACTUAL SNAPSHOT ONLY; must agree with canonical machine evidence | execution authorization; overriding canonical checkpoint state |
| `CURRENT_DECISION_GATE.md` | AUTHORIZATION | what may be executed; what is prohibited; whether owner authorization exists | redefining factual checkpoint values (cursor must reference the canonical checkpoint) |
| `SESSION_HANDOVER_*.md` | HANDOVER | what happened; what was verified; what remains; where to resume | overriding canonical evidence; independently authorizing the next action |
| `EVIDENCE_STATUS_REGISTER.md` | EVIDENCE_REGISTER | evidence classification only | current execution cursor; authorization |
| `PROJECT_PHASE_INDEX.md` | PHASE_CHRONOLOGY_INDEX | phase chronology / index | authorization; independently defining the current ingestion cursor |
| `PROJECT_STATE_TRANSITION_MAP.md` | HISTORICAL_TRANSITION | historical / architectural transition description | authorization |
| `FROZEN_ASSET_REGISTER.md` | FROZEN_ASSET_REGISTER | asset immutability / protection (asset_content_identity, last_verified_commit, current_repository_tip) | current execution cursor |
| `FEATURE_CONTRACT` / `LABEL_CONTRACT` | TECHNICAL_CONTRACT | technical semantics only (frozen specifications) | current project phase; dataset cursor; execution authorization |
| `README.md` | PUBLIC_SUMMARY | public / human summary only | canonical machine evidence; current project state; decision gate; frozen contracts |
| Report / handover produced by a session | derived summary (see section 9) | a record of that session | authorization unless separately granted |

### Canonical authority hierarchy (conflict precedence)

```text
CANONICAL MACHINE EVIDENCE
   >  CURRENT_DECISION_GATE (authorization)
   >  frozen TECHNICAL_CONTRACT (frozen semantics)
   >  CURRENT_PROJECT_STATE (factual snapshot)
   >  HANDOVER / EVIDENCE_REGISTER / PHASE_INDEX / TRANSITION_MAP
   >  PUBLIC_SUMMARY (README)
   >  any derived session summary
```

## 5. Conflict resolution rule

If documents disagree:

```text
FACTUAL EXECUTION STATE:     canonical machine evidence wins.
AUTHORIZATION:               CURRENT_DECISION_GATE wins.
TECHNICAL FROZEN SEMANTICS:  the relevant frozen contract wins.
HISTORY:                     historical documents are preserved as historical.
```

If the conflict cannot be classified: STOP. Do not choose by intuition. The
assistant MUST NOT infer a winner from wording alone.

## 6. State vs authorization separation

Explicitly separate FACTUAL STATE from AUTHORIZATION. They are independent.

```text
FACTUAL STATE (from canonical checkpoint):
    last_completed_chunk = 10
    next_chunk = 11
    next_byte_offset = 163578081

AUTHORIZATION (from CURRENT_DECISION_GATE):
    CHUNK 11 = NOT AUTHORIZED
```

"Next chunk" MUST NOT be interpreted as "authorized next action".

## 7. Prohibition of self-authorization

The assistant MUST NOT interpret any of the following as authorization:

- a current-state document saying "next chunk";
- a handover saying "next action";
- a report saying "recommended";
- a previous assistant saying "next authorized action";
- a checkpoint cursor pointing to a chunk;
- an old prompt containing an execution instruction.

Actual execution requires an ACTIVE owner authorization represented in
`CURRENT_DECISION_GATE` or the current session prompt.

## 8. Markdown trust model

- Assign every `.md` a single role (section 4).
- AI-generated Markdown is DERIVED, not canonical (section 9).
- A Git commit proves provenance, NOT semantic correctness.
- Never promote your own Markdown to canonical truth merely because it was
  committed.

## 9. Report generation policy

Reports MUST be generated from canonical structured data whenever practical:

```text
machine evidence
    -> structured result
    -> deterministic report generation
    -> Markdown
```

Avoid:

```text
reasoning -> manual transcription -> Markdown
```

Especially for SHA values, byte offsets, row counts, checkpoint values,
timestamps and verdicts.

## 10. Exact-value policy

The following MUST NEVER be manually reconstructed from model memory:

- SHA-1 / SHA-256 / commit IDs;
- byte offsets; row counts;
- checkpoint hashes; source hashes; artifact hashes.

Use programmatic extraction. If exact-value transcription is unavoidable:

```text
read actual source -> copy exact value -> programmatically validate format
-> verify against source again
```

If mismatch: STOP.

## 11. Failed evidence preservation

A failed verification artifact MUST NOT be overwritten:

```text
failed_run_<id> -> preserve -> diagnose -> corrected_run_<id>
```

Never:

```text
failed_run -> overwrite -> PASS
```

If an old failure was already overwritten historically, preserve that fact as
a provenance limitation. Do NOT reconstruct missing evidence from memory.

## 12. Verifier independence

A verifier is NOT correct merely because it produces the same result twice:

```text
SELF_REPRODUCIBILITY      = same verifier, repeated
CORRECTNESS SUPPORT       = independent evidence / oracle / mutation /
                            cross-artifact reconciliation
```

Report both separately. Two identical wrong runs are still wrong.

## 13. Mutable state rule

Any mutable state used in aggregation or verification MUST be snapshotted
before processing:

```text
input_state  = deepcopy(state_before)
process(...)
output_state = deepcopy(state_after)
```

The recorded input state MUST NEVER be a live mutable reference. For every
chunk expose input_state_hash and output_state_hash, and require:

```text
chunk_N.output_state_hash  ==  chunk_N+1.input_state_hash
```

where applicable.

## 14. Boundary rule

Chunk processing MUST use actual line-safe consumed byte_end values. Never
reconstruct resume boundaries from nominal offsets alone if the actual chunk
may extend to a newline. Continuous and resumed execution MUST use identical
boundary generation logic. Boundary sequences MUST be machine-comparable.

## 15. Line-ending / file-edit integrity

Before editing any file record: path; size; SHA-256; encoding; BOM state;
line-ending type; line count. Preserve the original line-ending convention.
Do NOT normalize LF/CRLF unless explicitly authorized. Prefer surgical edits.
Do NOT perform whole-file rewrites when a bounded edit is sufficient.

For changed files verify: intended semantic changes; line-ending preservation;
encoding preservation; BOM preservation. For untouched files:
SHA-before == SHA-after. Unexpected line-ending conversion:

```text
VERIFICATION FAILURE
```

## 16. Resource limit policy

Resource constraints may alter EXECUTION STRATEGY; they MUST NOT lower
VERIFICATION STANDARDS. Never skip mandatory verification because a session is
long; never reduce mutation coverage without recording it; never convert
incomplete work into PASS; never replace exact checks with approximations;
never omit evidence because of token/time/action limits.

If resource pressure is detected:

```text
1. complete the smallest safe atomic operation
2. persist evidence
3. record remaining work
4. STOP
5. resume in a later session
```

## 17. Session complexity control

Large tasks MUST be decomposed into bounded subphases:

```text
PLAN
-> BOUNDED SUBPHASE
-> VERIFY
-> PERSIST
-> HANDOVER
-> NEXT SUBPHASE
```

If a subphase cannot complete: mark INCOMPLETE / UNVERIFIED. Never respond to
complexity by silently reducing scope.

## 18. Report / handover requirements

Every future phase report and handover MUST include:

```text
DOCUMENT ROLE
AUTHORITATIVE SOURCE
EXACT GIT SHA
CURRENT FACTUAL STATE
AUTHORIZATION STATE
UNRESOLVED ITEMS
NEXT OWNER DECISION
```

The report MUST NOT imply authorization merely from a cursor.

## 19. Governance control-plane suite

This repository carries a machine-checkable governance consistency suite:

```text
ml/p3/governance/p3_gov3_control_plane/
    run_gov3.py before      # fingerprint snapshot before edits
    run_gov3.py suite       # consistency + mutation tests, twice
    run_gov3.py after       # verify file-integrity preservation
```

Expected factual state (sourced from the canonical checkpoint):

```text
last_completed_chunk = 10
next_chunk = 11
next_byte_offset = 163578081
SAFE_MAX_CHUNK_SIZE = 24 MiB
SAFE_CHUNKS_PER_TURN = NOT ESTABLISHED
P3-S25.1D broader multi-chunk benchmark = OPEN
Real Chunk 11 execution = NOT AUTHORIZED by this phase
```

Run the suite when governance documents change. Do NOT weaken the suite to
make it pass; repair only the governance implementation.

## 20. Integration

- Frozen-asset rules: `docs/FROZEN_ASSET_REGISTER.md`,
  `docs/AUTHORIZED_CHANGE_MATRIX.md`.
- Verification discipline: `docs/CODE_VERIFICATION_AND_SILENT_BUG_POLICY_v1.md`.
- Phase traceability: `docs/PROJECT_PHASE_INDEX.md`,
  `docs/PROVENANCE_GAP_REGISTER.md`.

*End of P3-GOV-3 session-start protocol v2. v1 preserved unchanged.*