meetLab Operations Guide.

The root-stub Makefile is the canonical entry point. cd orchestration && make ... remains a documented fallback. All targets require ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11 to bypass internal guards — commands without this flag are not compliant.

Canonical (root stub, v1.2.0)

make check-drift ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11
make tier0 tier1 tier2 ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11
make edpipe-run ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11

Direct fallback

cd orchestration && make tier0 tier1 tier2 ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11

Critical preconditions

Invariant. No operational circumstance permits exception.

• Trust the paths. Tiers for materialization. Explicit registry targets for integrity. All paths are domain-separated: /edpipe (Stage), /runtime (Phase), /orchestration (Build).
• Orchestration is mandatory. Every command appends ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11. Targets live in orchestration/Makefile.
• No execution without agreement. Runtime agents must never execute on an NTA document alone. Authority comes only from a persisted ACK envelope at runtime/airlock/envelopes/.
• Seals are immutable. Once written to artifacts/seals/memory_seal_{timestamp}.json, a seal cannot be modified. Phase 7 depends on this. Regeneration invalidates prior envelopes — it is not a refresh.
• Layer 0 registries track decisions. All submission decisions (rejected, accepted, discussed) recorded in runtime/governance/.
• Structural validation precedes materialization. Tier 0 must pass (exit 0) before Tier 1 begins. Drift detection is fail-fast, fail-closed, and recorded to the audit trail.
• Task queue interactions are CLI-only. No agent may modify .taskqueue/ contents except via taskqueue.py. Direct file edits to cards or manifest.json are a protocol violation; the .lock exists to enforce this.

Tier 0 validates structural invariants before Tier 1 materialization begins. It is a pre-materialization gate built on the witness protocol against file_registry.db.

Determinism guarantees

• Idempotent reports — identical inputs produce identical findings.
• No mutation — Tier 0 detects drift but never auto-fixes. Fixes require explicit manual review and commit.
• Fail-fast blocking — exit 1 prevents Tier 1 entry.
• No timestamps in findings — temporal info is excluded from drift determinations.
• JSON reproducibility — --json output is canonical (sort_keys=True, compact separators).

Validators

Error namespace locked at v1.1.0. TIER0_010_STRUCTURAL_DRIFT fires when witness_protocol.py exits non-zero.

Execution sequence

make tier0 ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11
  → make check-drift ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11
    → execute witness_protocol.py against file_registry.db
    → exit 0 if clean, non-zero if validation fails (fail-closed)
  → prepare-dist
  → Tier 1 materialization

v1.3 AI drift audit

Initialize the deterministic baseline first, then run the audit engine:

make registry-init ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11
make index ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11

PY=python3.11 PYTHON=python3.11 python3.11 scripts/ai_drift_audit_v1_3.py \
  --repo-root . \
  --db-path file_registry.db \
  --output-json dist/governance/drift_report_v1_3.json

Exit codes: 0 = no drift (NONE); 1 = medium drift; 2 = high drift.

Standard build sequence

make tier0 tier1 tier2 ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11

Build surface roles · invariant

• dist/ — deterministic build workspace, transitional materialization. Prunable. Never authoritative.
• artifacts/ — sealed promotion surface, authoritative immutable outputs.
• Promotion flow: dist/ → artifacts/ at Tier 2 / Tier 3.

Tier 0 — environment

Validates Python, clears artifacts/manifests/next, prepares directories, verifies Phase 6/7 paths. Output: verified environment state, orchestration paths ready.

Tier 1 — materialization & intelligence

Phase 4b execution order:

1. Initialize registry — registry-init, index
2. Bridge manifest — registry-bridge
3. Prune overviews — generate-l0-l1
4. Materialize shards — materialize-shards
5. Generate manifest index — orchestration/scripts/semantic_index/core/build/manifest_index.py
6. Enhance registry — registry-enhance (4-script suite, see § V)
7. Refine registry cognition — registry-refine
8. Build merged overview — repo-overview-merged
9. Promote seal surface — promote-overviews
10. Complete registry build — registry-build-all

Diagnostic outside Tier 1: make registry-health ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11. Outputs land in dist/ and the promoted artifacts/manifests/manifest_index.jsonl + file_registry.db.

Tier 2 — hardening & sealing

Runs FAT, mints immutable seals, binds context, initializes Phase 6/7 gates. Outputs include:

• transitional writes in dist/ (seal/bootstrap, context, ontology, pruning)
• promoted immutable outputs: artifacts/seals/memory_seal_{ISO_timestamp}.json (immutable seal) and artifacts/seals/seed_seal_{ISO_timestamp}.json
• runtime/governance/session_state.json (Phase 6 state)
• runtime/governance/state/phase_state.json (Phase state checkpoint)

Artifact prerequisites

The registry system has two distinct authority classes. They must never be collapsed.

7A · authoritative deterministic baseline

make clean-registry ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11 && \
make registry-init  ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11 && \
make index          ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11 && \
make witness        ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11

make index (indexer_v4) auto-prunes ghost registrations (missing-on-disk active rows) before witness. Indexer workspace guard excludes vidpipe/, .claude/worktrees/, .taskqueue/.

7B · enhancement protocol (4 scripts, in order)

1. ensure_registry_schema.py — adds missing columns (idempotent; Phases 1–3)
2. populate_registry_enhanced.py — Phase 1 (8 fields: discovery metadata)
3. populate_registry_metrics.py — Phase 2 (6 fields: optimization metrics)
4. populate_registry_compliance.py — Phase 3 (5 fields: compliance data)

Authority precedence chain

Registry → Memory Seal → Manifest Index Reachability → Context Bridge → Phase Alignment → Active Envelope Validation → Governance State Hash → ACA Authorization → Audit Completeness → Ledger Integrity → ACA Heartbeat.

Governance gate stack · canonical ACA validation

make aca-authorize INTENT_ID=$(git rev-parse --short HEAD) \
  ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11

Binds ACA authorization to the commit currently checked out. Execution gate stack runs in order:

The task queue pipeline operates within a strict two-database authority model. These databases must never be collapsed or treated as interchangeable.

Two distinct cryptographic hash layers. Different purposes, different security levels. They must not be conflated; identifiers from one layer must never be substituted for the other.

Boundary rule: governance_ledger.json uses Layer 1 only. artifacts/seals/ uses Layer 2 only. Substituting a 16-char Layer 1 hash into a seal record is a protocol violation and is rejected by the Phase 6 admission gate.

Governance ledger · TASK_COMPLETE record

{
  "event": "TASK_COMPLETE",
  "card_id": "WS-1.4",
  "spec_hash":   "a3f9c21b88d04e1f",
  "result_hash": "9f3a1c7b2e804d5f",
  "entry_hash":  "c7d2e04a1b938f62",
  "timestamp": "ISO-8601 UTC",
  "actor": "codex|jules|human"
}

spec_hash = frozen intent at shred; result_hash = output attestation at complete; entry_hash self-verifies the record (all fields except itself, sorted keys, SHA-256, truncated to 16 chars). The approve command verifies entry_hash before moving the card to done.

The ledger is append-only and uses a dedicated lock governance_ledger.json.lock, distinct from .taskqueue/.lock. The two locks are never acquired together — a queue reset cannot structurally erase the historical authority ledger.

Stage-2 — canonicalization

Deterministic lexical canonicalization of the Stage-1 AST under Option A: exact 1:1 glossary token replacement. No insertion / deletion, no topology mutation, no grammar rewrite, no numeric modification.

PY=python3.11 PYTHON=python3.11 python3.11 edpipe/scripts/edpipe_stage2_canonicalize.py \
  --stage1 AST_STAGE1.json \
  --glossary glossary_v1.0.json \
  --dsdm dsdm_v1.0.json \
  --actors allowed_actors_v1.0.json \
  --manifest-stage1 MANIFEST_STAGE1.json \
  --out-stage2 AST_STAGE2.json \
  --out-delta STAGE2_DELTA.jsonl

Stages 3–6 enforcement chain

Phase 6 — admission gate (fail-closed ACA)

1. read active seal from runtime/governance/session_state.json "seal_path"
2. verify seal has governing_count > 0 (quorum check) from artifacts/seals/
3. verify audit trail shows valid append
4. issue APPROVED verdict with verdict_id (deterministic hash)
5. return DENIED with HALT code if any check fails — fail-closed

Phase 6.5 — airlock enforcement

Dynamically seals all governance artifacts under runtime/airlock/:

1. locks active seal read-only
2. locks runtime/governance/session_state.json read-only
3. locks all governance documents in runtime/airlock/manifests/ read-only
4. emits durable heartbeat (fsync'd to audit log)
5. verifies all locks succeeded — fail-closed

Phase 7 — execution (isolated subprocess)

• environment stripped — only PATH, HOME, PHASE vars permitted
• PHASE=7 lock prevents seal_append imports
• limited arguments — only intent_id and verdict_id
• 60-second hard timeout

Boundary breach (Phase 7 spawned without isolation) → HALT-701.

Select the minimum-scope reset appropriate to the failure condition.

Soft reset · clean dist

make clean ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11

Tier 1 reset

make reset-tier1 ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11

Registry-specific reset

cp file_registry.db file_registry.db.backup
make clean-registry   ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11
make registry-init    ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11
make registry-enhance ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11
make index            ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11
make witness          ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11

Full deterministic rebuild

make clean       ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11
make reset-tier1 ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11
make tier0 tier1 tier2 ORCHESTRATED=1 PY=python3.11 PYTHON=python3.11

Recovery decision tree

HALT codes

Task queue errors

Audit trail (reserved v1.1.0, CI-only)

AUDIT_010_RECORD_APPEND_FAILED, AUDIT_020_INVALID_AUDIT_SCHEMA, AUDIT_030_TRACEABILITY_GAP, AUDIT_040_MANIFEST_DIGEST_MISMATCH, AUDIT_050_ACTOR_UNIDENTIFIED. Record schema is locked; audit append-only at runtime/governance/drift_audit.jsonl.

Substrate

The .taskqueue/ directory is the ephemeral local substrate. It is git-ignored. Version control records only finished, attested artifacts; never queue state, card mutations, or intermediate logs. Committing .taskqueue/ contents is a plane violation.

.taskqueue/
  queue/      ← Materialized cards awaiting pickup
  active/     ← Cards currently held by an executor
  review/     ← Cards pending human approval
  done/       ← Completed and attested cards
  blocked/    ← Cards halted by unresolved dependencies
  manifest.json
  .lock

Atomic write pipeline

All manifest read-modify-write operations serialize through .taskqueue/.lock, opened with os.open + os.O_EXCL (atomic creation, universal across Linux / macOS / Windows). Failure to acquire raises LOCK_TIMEOUT.

The hash persistence paradox — mutating a card invalidates the content_hash recorded in manifest.json — is resolved by a five-phase pipeline executed under the lock:

1. READ — load card content; verify content_hash matches manifest. Abort on mismatch.
2. MUTATE — apply mutation in memory (append exec log, update state, etc.).
3. TEMP WRITE — write mutated content to a temp file in the same directory, with a process-unique suffix.
4. os.replace — atomically overwrite destination (POSIX rename(2); equivalent on Windows).
5. MANIFEST UPDATE — recompute content_hash from disk after replace; write to manifest.json.

If the process dies before os.replace(), the destination is unchanged and the temp is an orphan. If it dies after replace but before manifest update, the file is correct and the manifest is stale by one transition; recovery is recomputing the hash from disk.

SHCL-v2 attestation tables are programmatically rebuilt and replaced in their entirety on each transition — never via regex substitution.

Ambiguity Protocol — fail-closed routing conflict

Triggered at pick / activate when the card's surface field does not match the executor's --surface argument (e.g. "human"-surface card claimed by codex; "opus"-surface card claimed by jules). Mandatory response, executed in order:

1. Halt. Command halts immediately. Card state unchanged. No execution log entry.
2. Emit AMBIGUITY block on stdout with three fields: evidence (conflicting signal pair, card id, title), options (route to declared surface, or operator-authorized re-assignment), recommendation (deduced correct path — a statement of fact, not an invitation to override).
3. Wait. No retry. No fallback routing. Card remains unclaimed.
4. Human sign-off. Operator confirms the correct surface or authorizes re-assignment via card edit + manifest update.

Mechanical agents must not resolve AMBIGUITY blocks autonomously. The block must not be suppressed or redirected to a log. Retrying with the same conflicting surface produces the same halt.

Session closure checklist

• Artifacts — Tier 2 build artifacts exist; Layer 0 registries populated.
• Registry hygiene — health reports generated; current schema inspected.
• Deterministic baseline — run § V 7A sequence; witness returns OK.
• Stage validation — strict order Stage-3 → 4 → 5 → 6; determinism mode for Stages 4–6.
• Artifact integrity — active seal pointers coherent; manifest index exists.
• Task queue hygiene — taskqueue.py status shows no stranded active cards; make index && make witness after any card approval or doc update.
• Version control — all changes committed.