SniperGold_ML/docs/AI_ASSISTANT_SESSION_START_PROTOCOL_v2.md

AI ASSISTANT SESSION START PROTOCOL — v2

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:

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)

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

Required:

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:

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)

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:

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.

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:

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

Avoid:

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:

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:

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

Never:

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:

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:

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:

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:

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:

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:

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:

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:

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):

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.