docs: add governance/persona/phases/product/instructions/self_hosting directories

Author: Dee66

docs/INVARIANTS.md

@@ -1,11 +1,125 @@
-# Invariant Consolidation (SE v1)
+# Invariants (ShieldCraft Engine v1)
 
-This file enumerates invariants, where they are enforced, and ensures each is enforced in a single place.
+This file defines non-negotiable invariants of the ShieldCraft Engine (SE).
+An invariant expresses a condition that must always hold, how violations are classified,
+and what actions are permitted or forbidden in response.
 
-- Instruction-level invariants: enforced in `shieldcraft.services.validator` via `validate_spec_instructions`.
-- Repo sync invariants: enforced in `shieldcraft.services.sync.verify_repo_sync`; errors surfaced as `SyncError`.
-- Pointer coverage invariants: checked in `shieldcraft.services.spec.pointer_auditor.ensure_full_pointer_coverage` and used in `preflight`.
-- Checklist invariants (must/forbid): evaluated during `ChecklistGenerator.build` via `invariants.evaluate_invariant` and `evaluate_invariant` results are attached to items; enforcement for must/forbid resides in `ChecklistGenerator`/`derived` as appropriate.
-- Self-host artifact emission: enforced by `Engine.run_self_host` using `is_allowed_selfhost_path()`.
+Each invariant is enforced in exactly one authoritative location.
+No invariant may be enforced implicitly or redundantly.
 
-Policy: Each invariant is documented and enforced in one authoritative module; enforcement points are referenced above.
+---
+
+## Invariant Enforcement Map
+
+- Instruction invariants  
+  Enforced in: `shieldcraft.services.validator.validate_spec_instructions`
+
+- Repository sync invariants  
+  Enforced in: `shieldcraft.services.sync.verify_repo_sync`  
+  Violation surfaced as: `SyncError`
+
+- Pointer coverage invariants  
+  Enforced in: `shieldcraft.services.spec.pointer_auditor.ensure_full_pointer_coverage`  
+  Used during: preflight
+
+- Checklist must/forbid invariants  
+  Evaluated in: `ChecklistGenerator.build` via `invariants.evaluate_invariant`  
+  Enforcement resides in: checklist generation and derived resolution
+
+- Self-host artifact emission invariants  
+  Enforced in: `Engine.run_self_host` using `is_allowed_selfhost_path()`
+
+---
+
+## Failure Classification Invariants
+
+### Failure Classes (Exhaustive)
+
+All failures in SE **must** be classified as exactly one of the following:
+
+- `PRODUCT_INVARIANT_FAILURE`
+- `SPEC_CONTRACT_FAILURE`
+- `SYNC_DRIFT_FAILURE`
+- `ORCHESTRATION_FAILURE`
+- `UNKNOWN_FAILURE`
+
+No other failure classes are permitted.
+
+Failure classification is mandatory before any corrective action.
+
+---
+
+### ORCHESTRATION_FAILURE
+
+An `ORCHESTRATION_FAILURE` applies when **all** of the following are true:
+
+- The failure occurs before SE product logic executes.
+- The failure originates from the orchestration or execution environment.
+- No product artifact hash, spec, checklist, or invariant is violated.
+
+Examples (non-exhaustive):
+- Missing tooling (e.g. pytest not installed)
+- Missing or incorrect environment setup
+- Invalid CI workflow configuration
+- Runner, permission, or infrastructure misconfiguration
+
+---
+
+## Enforcement Rules
+
+- Product code **must not** be modified in response to an `ORCHESTRATION_FAILURE`.
+- Only orchestration-layer artifacts (e.g. CI workflows, runners, environment setup)
+  may be changed.
+- Resolution of an `ORCHESTRATION_FAILURE` is required before any product-level
+  work may proceed.
+
+---
+
+## Persona Constraints
+
+- Personas **must** classify the failure before emitting guidance.
+- Personas **must not** recommend product-level changes until failure class
+  is determined.
+- If the failure class is `ORCHESTRATION_FAILURE`:
+  - Personas **must refuse** product-level recommendations.
+  - Persona output is restricted to orchestration-layer observations or vetoes.
+
+Persona output is data, not inference.
+
+---
+
+## Failure Classification Gate
+
+After any CI or execution failure:
+
+- Evidence **must** be collected.
+- Failure **must** be classified into exactly one failure class.
+- No instruction block may be issued before classification is recorded.
+
+---
+
+## CI Assumption Invariant
+
+CI workflows **must not** assume project structure or implicit tooling.
+
+Forbidden assumptions include:
+- Presence of `requirements.txt`
+- Implicit availability of pytest or global tools
+
+All CI setup **must** derive from:
+- `pyproject.toml`
+- Explicit, versioned installation steps
+
+Violation of this invariant is classified as `ORCHESTRATION_FAILURE`.
+
+---
+
+## Unknown Failures
+
+Any failure that cannot be deterministically classified **must** be classified as
+`UNKNOWN_FAILURE`.
+
+On `UNKNOWN_FAILURE`:
+- All progress halts.
+- Escalation is mandatory.
+- No speculative fixes are permitted.