Conflux

Conflux is a governed orchestration runtime for free-form application creation.

The implementation model is:

• Keep Conductor interactive at intake.
• Compile intent into explicit contracts before execution.
• Allow creative generation inside bounded lanes.
• Enforce deterministic verdict boundaries at admission, mutation, and completion.

This README is an implemented-state, full granular flow document. It describes behavior present in code paths under conflux/core/* today.

Scope and Artifact Authority

Conflux contains both authoritative runtime artifacts and simulation/test artifacts.

• Authoritative runtime and enforcement:
  • conflux/core/*
  • conductor/* (active run artifacts and policies)
• Simulation/test artifacts:
  • StressSim/*

Use StressSim for scenario validation and historical simulation, not as the authoritative control path.

AI Instruction Source

Conflux now uses one canonical AI instruction document:

• AI_OPERATOR_GUIDE.md

This canonical guide includes the mode transition policy:

• execution-by-default for implement/fix/add/go directives
• orchestration-only for explicit plan/analyze/review/talk-only/no-edits directives

Provider-specific entry files (AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, .cursorrules, and provider subdirectory files) are thin wrappers pointing to this canonical source.

Core Control Model

Conflux is designed to separate where creativity is allowed from where determinism is required.

• Creative zones:
  • plan generation
  • implementation command selection
  • decomposition draft shaping
• Deterministic zones:
  • admission checks
  • safety/security/governance/state mutation gates
  • fingerprint drift checks
  • structural/behavioral/quality gates
  • truth promotion and verification

Truth is separated into two lanes:

• invariant_capabilities_proposed: AI-writable working hypotheses.
• invariant_capabilities_proven: reducer-authored truth from evidence.

Only promoted truth is admissible at strict completion boundaries when required by contract.

Full Granular Flow

This README now documents two implemented runtime flows:

• Main flow: the default greenfield/free-form creation path.
• Enhancement flow: the explicit brownfield path entered via conflux_enhance.

The main flow remains the default. The enhancement flow is opt-in and additive.

Main Flow (Default Greenfield / Free-Form Creation)

1) Conductor Entry and Bootstrap

Source: conflux/core/conductor.py

Conductor.initialize(...) performs:

1. Base scaffold setup under conductor/ (product.md, tech-stack.md, workflow.md, etc.) if missing.
2. Optional seed track creation (ralph-core plus domain-derived tracks) when track directory is empty.
3. Invocation of PhaseFlowEngine.run(...) for Phase 0 -> Phase 4.
4. Return of either:
   • pending state with human review queue (phase3.converged=false)
   • compiled state with track contracts (phase3.converged=true)

The intake interaction style is retained; enhancement is in extraction, reconciliation, provenance, and gate rigor.

Runtime service bootstrap hardening

Source: conflux/server.py (ensure_db, ServiceRegistry.init_all)

Service initialization is bounded by:

• CONFLUX_SERVICE_INIT_TIMEOUT_SEC (default 90)

On timeout, Conflux raises a structured runtime error with diagnostics from ServiceRegistry.init_diagnostics() including:

• active/last service
• pending services
• last init trace

This prevents silent startup hangs and yields deterministic operator triage data.

2) Phase 0: Anchor-First Intake and Lossiness Control

Source: conflux/core/phase_flow/engine.py (_phase0)

Phase 0 is where free-form user input is converted into explicit anchor artifacts.

Inputs read

• Goal parameter passed to initialize/run.
• Existing conductor/product.md.
• Existing conductor/tech-stack.md.
• Any prior ambiguity answers.

Extraction and ambiguity generation

Phase 0 extracts and/or asks for:

• goal
• product name
• primary user
• success criteria
• failure criteria
• non-goals
• hard constraints
• safety boundaries
• data boundaries
• language/framework/database

It issues explicit ambiguity prompts when missing, including:

• phase0-product-clarity
• phase0-tech-stack-clarity
• interview prompts (phase0-success-metrics, phase0-hard-constraints, etc.)

Deterministic anchor coverage

Phase 0 computes explicit coverage flags for:

• goal
• success criteria
• failure criteria
• non-goals
• hard constraints
• safety
• data boundaries
• primary user

High-risk context is inferred from anchor text tokens (auth/security/payment/pii/compliance/delete/drop/financial).
For high-risk context, missing failure/data/safety fields are elevated to critical.

Intent lock and lossiness review

Phase 0 generates:

• intent lock summary (phase0-intent-lock-confirm)
• lossiness review request (phase0-lossiness-review) with plain-English unresolved items

Both are first-class prompts and persisted as confirmation metadata when answered.

Artifacts written

• conductor/reconciliation/anchors.json
• conductor/reconciliation/lossiness_report.json
• conductor/reconciliation/assumption_ledger.md

assumption_ledger.md is always plain English and explicitly lists unresolved assumptions by severity.

3) Phase 1/2 Seed and Draft Materialization

Source: conflux/core/phase_flow/engine.py (_seed_phase_inputs, run)

Before reconciliation, engine seeds working drafts from existing state.

Seeding order

1. conductor/reconciliation/phase3_reconciliation_state.json (if present)
2. .gemini_security/scenarios/journeys.json fallback
3. existing track folders in conductor/tracks/
4. category-based extraction from product.md sentences

Draft shaping behavior

• dedupe by stable IDs
• category classification for structural tracks
• semantic fingerprint grouping to avoid micro-track explosion
• auto fallback journey/behavioral track generation only if no tracks exist

No lock occurs here. This is mutable pre-reconciliation material.

4) Phase 3: Reconciliation with Bounded Healing

Source: conflux/core/phase_flow/reconciliation.py

Phase 3 converges mutable drafts into lockable artifacts and explicit review queues.

Anchor-aware review context

Reconciliation builds anchor context from:

• anchors.json
• lossiness_report.json

This context is injected into review queue provenance for auditability.

High-severity lossiness enforcement

If high-severity unresolved assumptions exist and lossiness review is not confirmed, reconciliation enqueues mandatory confirmation review and blocks convergence.

Phase 3 Healing Loop (compile-time structural healing)

For phase3-gate style violations:

1. Classify if auto-fixable.
2. Build deterministic constraint prompt with:
   • bond/rule identity
   • required missing fields
   • anchor summary context
3. Apply either:
   • custom regenerator callback, or
   • deterministic local autofix (schema_fields insertion)
4. Retry with bounded budget (CONFLUX_PHASE3_HEAL_MAX_ATTEMPTS, default 3).
5. On exhaustion, escalate to human review queue.

This keeps Phase 3 moving without using runtime-only arbitration logic.

Collision and ownership reconciliation

Reconciliation also handles:

• structural requirement collisions
• invariant owner assignment requests
• persistent recall of previously resolved ownership from tracks_locked.json
• recursive dampening for synthetic journey generation

Stability loop and cycle detection

Reconciliation runs iterative stability passes (bounded by CONFLUX_RECONCILIATION_MAX_ROUNDS), hashes structural state each round, and blocks with explicit cycle report if cycle is detected.

Phase 3 outputs

• conductor/reconciliation/tracks_locked.json (persisted draft lock state)
• conductor/reconciliation/phase3_reconciliation_state.json
• response payload with:
  • converged
  • human_review_queue
  • phase3_healing (attempts/resolved/escalated)

If not converged, compile is skipped and status remains pending.

5) Phase 4: Contract Compilation and Provenance Binding

Source: conflux/core/phase_flow/compilation.py

Phase 4 compiles reconciled state to per-track execution contracts.

Compilation prelude

1. Preserve selected reconciliation artifacts (anchors/lossiness/assumption ledger/state) during reconciliation directory refresh.
2. Write locked journey invariants:
   • conductor/reconciliation/journey_invariants_locked.json
3. Write tracks_locked.json.
4. Publish security scenario snapshots:
   • .gemini_security/scenarios/scenarios.json
   • .gemini_security/scenarios/journeys.json

Per-track compile steps

For each unified track:

1. Ensure/validate contract envelope (ensure_track_contract).
2. Apply explicit, governance-authorized auto-repair only when enabled:
   • CONFLUX_ALLOW_CONTRACT_AUTOREPAIR=1
   • CONFLUX_CONTRACT_AUTOREPAIR_DECISION_KEY=<approved_key>
3. Apply archetype and stack profile alignment.
4. Bind lineage (journey_refs).
5. Attach journey invariants and evidence requirements.
6. If no invariants exist, inject synthetic sanity invariant (non-zero invariant baseline).
7. Classify invariant testability deterministically:
   • tier1 (fully deterministic)
   • tier2 (oracle-collusion-risk; requires independent pass)
   • tier3 (requires human confirmation)
8. Generate human-verification task artifact when tier3 invariants exist:
   • conductor/tracks/<track>/planning/human_verification_tasks.json
9. Infer capabilities into:
   • invariant_capabilities_proposed
   • invariant_capabilities (working copy)
   • invariant_capabilities_proven initialized if absent
10. Build stack lock and harness derivation from detected ecosystem.
11. Force strict quality gate posture for intent/truth/provenance/invariant evidence.
12. Derive allowed_write_roots from track + ecosystem + docs.
13. Resolve implementation_commands.
14. Generate intent provenance payload:
    • anchors
    • per-track claims
    • unresolved assumptions
    • lossiness/intention confirmation flags
15. Initialize truth promotion status:
    • truth_promotion.status = pending
16. Write:
    • conductor/tracks/<track>/contract.json
    • conductor/tracks/<track>/PRIME.md
    • claim provenance section in spec.md
    • planning seeds (oracle_fixtures.json, phase4_prime_seed.json)

Compilation outputs

• updated track list
• preserved reconciliation artifact list

5.1) Late Policy Finalization (Post-Compile)

Sources: conflux/core/phase_flow/engine.py, conflux/core/policy_profile.py

After compile succeeds, Conflux runs a late policy pass before final success.

This stage writes:

• conductor/reconciliation/default_constitution.json
• conductor/reconciliation/default_constitution_summary.md
• conductor/reconciliation/decision_policy.json

Fully confirmed means all of the following are true for the current run:

• late policy review queue has no unresolved required prompts
• strict late-policy mode is satisfied (CONFLUX_REQUIRE_LATE_POLICY_CONFIRM=1, default)
• deterministic policy promotion thresholds are met by eligible decisions

When fully confirmed, this stage also writes:

• conductor/reconciliation/decision_policy_proven.json

Policy promotion is driven by deterministic evidence reduction (conflux/core/policy/promotion.py) using:

• minimum eligible decision samples per gate (default: 3)
• consistency threshold (default: >= 0.8)
• promotion-eligible decisions only (consequence quality pass + medium/high confidence)

Prompt behavior:

• This stage is intentionally late (post-compile).
• It accepts policy preference answers including unsure.
• In strict mode (CONFLUX_REQUIRE_LATE_POLICY_CONFIRM=1, default), unresolved late policy prompts keep status at pending.

6) Admission and Pre-Execution Certification

Primary sources:

• conflux/core/track_contract.py
• conflux/core/orchestrator/admission.py
• conflux/core/harness_security.py

Admission is blocking, not advisory.

validate_track_admission(...) enforces

1. Valid contract schema and strict gate expectations.
2. PRIME presence and required sections.
3. Harness DoD schema:
   • executor/command safety
   • scenario map coverage
   • expected artifacts
   • attestation constraints
   • oracle fixture requirements
4. Harness certification (Phase 4.5 style) when enabled.
5. Invariant admission (journey_invariants + coverage + capabilities).
6. High-risk intent provenance admission:
   • anchors required
   • track claim provenance required
   • high-severity unresolved assumptions require confirmed lossiness review

Admission overrides

admission_override.ev_override=true is allowed only with:

• non-empty governance_decision_key
• logged decision authorizing override in governance decision log

Dependency bypass via override also requires the same authorized override path.

7) Runtime Lanes

Conflux has three active runtime lanes, all enforcing completion-time quality behavior checks.

7.1 Work-Order Lane

Source: conflux/core/work_order_manager.py

Default step chain:

1. admission_gate
2. pre_admission_integrity
3. execution_safety_gate
4. governance_gate
5. prepare_loop
6. generate_plan
7. security_secrets_gate
8. state_mutation_gate
9. dependency_gate
10. spawn_loop
11. wait_worker
12. structural_gate (optional only under explicit allow switch)
13. behavioral_satisfaction_gate (optional only under explicit allow switch)
14. quality_behavior_gate

Work-order runtime specifics

• Uses actual generated/planned commands for security-secrets evaluation.
• Applies execution fingerprint guard before mutation command steps.
• Runs independent adversarial test pass when contract requires it (tier2 paths).
• Runs dependency transactions with rollback on install/policy failures.
• Acquires/releases PRIME lock around worker lifecycle when lock manager present.
• Records forensic incidents on failures.
• Rolls back state transaction and releases mutation locks on non-complete terminal states.
• Supports controlled flake retries via quality gate flake quarantine.
• Supports explicit pause state awaiting_human_review for tier3 verification.
• Human escalation replies are plain-text-first; optional helper command:
  • /conflux-question <your question>
• Human review resolution/resume is exposed through work-order tooling:
  • respond_work_order_escalation
• Track-level (non-work-order) human verification responses are exposed via:
  • respond_track_human_verification

Structural/behavioral step disable is only available behind explicit environment allowance:

• CONFLUX_WORKORDER_ALLOW_GATE_DISABLE=1

7.2 Direct Worker Lane

Sources:

• conflux/core/worker_task.py
• conflux/core/worker/engine.py
• conflux/core/worker/phases/*

Worker phase order:

1. InitPhase
2. SafetyPhase
3. ImplementPhase
4. VerifyPhase
5. CrystallizePhase
6. HealPhase

InitPhase

• loads and validates contract
• resolves dependencies and role mutability
• computes execution fingerprints
• writes planning/execution_fingerprints.json

SafetyPhase

• execution safety gate
• governance gate
• security/secrets gate with resolved implementation commands
• state mutation gate with lock owner and transaction state

ImplementPhase

• requires expected execution fingerprint in context
• resolves implementation commands
• pre-checks write-root violations
• enforces stack lock command validity
• runs per-command fingerprint guard before each mutation
• executes commands and writes:
  • planning/builder_report.json
  • planning/implementation_evidence_report.json
  • planning/idempotent_materialization_report.json

VerifyPhase

• runs vibe_ralph.sh deterministic structural/harness gate
• reads harness report
• runs independent adversarial test pass when required

CrystallizePhase

• checks crystallization trace gate (required or optional per contract)
• when truth promotion required:
  • runs deterministic truth reducer
  • blocks if reducer does not promote

HealPhase

• runs only when verify failed
• re-checks fingerprint guard before any healing mutation
• invokes Sentinel bounded self-heal
• requires actual patch application (fix_applied strict semantics)
• re-runs deterministic verification (vibe_ralph.sh)
• reruns truth promotion when required

Worker engine invalidation and finalization

PhaseEngine polls StatePulse safe-point after each phase.
If dependent public mutation/contract promotion is observed:

• transition through quiesce/rebase state
• emit rebasing event
• stop current linear run for orchestrator-managed continuation

On non-completion:

• rollback state transaction if present
• release mutation locks

Even after COMPLETED state, direct worker lane runs final quality_behavior_gate before process success. When human verification is pending, direct worker emits awaiting_human_review heartbeat and exits with a dedicated non-success code so orchestrators treat it as paused (not failed).

7.3 Hyperscale Orchestrator Lane

Source: conflux/core/hyperscale_orchestrator.py

Hyperscale dispatches worker_task.py processes, tracks retries/healing states, and now enforces final quality behavior gate before setting track status to COMPLETED. It now treats awaiting_human_review as a first-class paused terminal for that run:

• track status is awaiting_human_review (not failed)
• dependent tracks are marked awaiting_human_dependency when blocked on a paused dependency
• result payload includes:
  • awaiting_human_review_tracks
  • awaiting_human_dependency_tracks

Lane Boundary Enforcement (Explicit, Code-Enforced)

Sources:

• conflux/core/workflow_lane.py
• conflux/core/track_contract.py (workflow_policy)
• conflux/tools/work_orders.py
• conflux/tools/hyperscale.py

Each track contract now includes workflow_policy and runtime entrypoints enforce it before dispatch:

• Control-lane operations:
  • create_work_order
  • respond_work_order_escalation
  • respond_track_human_verification
• Throughput-lane operations:
  • spawn_ralph_loop
  • dispatch
  • execute_hyperscale

If an operation is invoked from a disallowed lane, execution is blocked with WORKFLOW LANE BLOCK [...] and includes deterministic reason fields (operation, lane, allowed_lanes, phase, required_owner when relevant).

8) Active Event Bus and Safe-Point Polling

Sources:

• conflux/core/pulse.py
• conflux/core/worker/cursor.py

StatePulse is append-only event log backed by SQLite:

• events table with monotonic seq
• worker_cursors for last seen sequence and working base
• worker heartbeat and lease tables

Worker cursor invalidation rules:

• only dependency tracks are considered relevant
• CONTRACT_PROMOTION invalidates
• SYMBOL_MUTATION invalidates when scope is not impl:internal

This supports deterministic replay and reactive rebasing without blind linear execution.

9) Truth Promotion Pipeline

Source: conflux/core/truth_promotion.py

Truth reducer is deterministic and non-LLM:

1. Normalize and validate invariant schema.
2. Load invariant evidence requirements from contract.
3. Read evidence artifacts under project root (path escape blocked).
4. Validate required fields and status semantics.
5. Derive proven capabilities map.
6. Build signed payload with:
   • truth_input_hash
   • policy hash
   • proposed/proven hashes
   • error hash
7. Sign payload (HMAC key from env or .gemini_security/truth_promotion.key).
8. Append hash-chained event to .gemini_security/truth_promotion.log.
9. Write planning/truth_promotion_report.json.
10. Persist promoted state in contract.json.

Verification for completion:

• signature validity
• track identity match
• truth_input_hash continuity
• log hash presence in chained log
• report status must be promoted

Failure in any check blocks completion through quality gate.

10) Gate Catalog and Enforcement Roles

Gate implementations are under conflux/core/gates/*.

• safety: command safety and destructive operation policy.
• governance: decision holds for high-risk operations.
• state: mutation lock and transaction boundary control.
• quality: structural/behavioral/provenance/truth completion gate.
• crystallization: crystallization trace requirement validation.

All major gates now invoke a shared policy conflict resolver:

• module: conflux/core/policy/resolver.py
• outputs deterministic conflict packets and consequence statements
• writes per-track:
  • planning/conflict_packets.jsonl
  • planning/escalation_packets.jsonl (when escalating)
  • planning/policy_decision_log.jsonl

Control-plane policy defaults come from conflux/core/control_plane.py and can be extended by:

• conductor/policies/control_plane_policy.json
• conductor/policies/consequence_template_spec.md

11) Sentinel and Patch Scope Enforcement

Source: conflux/core/sentinel.py

Sentinel healing includes:

• failure fingerprinting and retry loop suppression
• forensic artifacts and replay context
• fingerprint guard awareness
• patch application restricted to:
  • project root boundaries
  • track contract allowed_write_roots

fix_applied is strict and only true when patches were actually applied.

12) Artifact Map (Granular)

Reconciliation artifacts

• conductor/reconciliation/anchors.json
• conductor/reconciliation/lossiness_report.json
• conductor/reconciliation/assumption_ledger.md
• conductor/reconciliation/phase3_reconciliation_state.json
• conductor/reconciliation/journey_invariants_locked.json
• conductor/reconciliation/tracks_locked.json
• conductor/reconciliation/default_constitution.json
• conductor/reconciliation/default_constitution_summary.md
• conductor/reconciliation/decision_policy.json
• conductor/reconciliation/decision_policy_proven.json
• conductor/reconciliation/policy_promotion_report.json
• conductor/reconciliation/strategic_drift_report.md
• .gemini_security/policy_decision_log.jsonl (global policy decision audit stream)

Track contract/artifact surfaces

• conductor/tracks/<track>/contract.json
• conductor/tracks/<track>/PRIME.md
• conductor/tracks/<track>/spec.md
• conductor/tracks/<track>/planning/phase4_prime_seed.json
• conductor/tracks/<track>/planning/oracle_fixtures.json
• conductor/tracks/<track>/planning/human_verification_tasks.json

Runtime evidence artifacts

• planning/execution_fingerprints.json
• planning/builder_report.json
• planning/implementation_evidence_report.json
• planning/idempotent_materialization_report.json
• planning/security_plane_report.json
• planning/quality_behavior_report.json
• planning/truth_promotion_report.json
• planning/harness_report.json
• planning/harness_attestation.json
• planning/state_transaction.json
• planning/invariants/<invariant_id>.json (deterministic or human-confirmed invariant evidence)

System-level security and event artifacts

• .gemini_security/pulse.db
• .gemini_security/truth_promotion.log
• .gemini_security/truth_promotion.key
• .gemini_security/governance_decisions.log
• .gemini_security/mutation_locks.json
• .gemini_security/flake_quarantine.json
• .gemini_security/scenarios/scenarios.json
• .gemini_security/scenarios/journeys.json

13) Determinism Without Deadlock

The implemented system uses bounded loops and explicit escalation rather than hard stop everywhere:

• Phase 3 bounded healing retries before human queue escalation.
• Runtime heal attempts bounded by contract.
• Flake-aware retry budget only when quality gate recommends.
• Fingerprint drift blocks mutation but allows bounded rebind attempts.
• Governance overrides are explicit and auditable, not implicit.

This is the intended balance:

• keep exploratory generation adaptive
• keep mutation/admission/completion truth deterministic

14) Intent Enforcement vs Observability

Authoritative verdict path:

• contracts
• gates
• deterministic reducers/verifiers

Observability path:

• Vigilance client and HUD telemetry

Vigilance is not the sole control authority; it is visibility infrastructure.

15) Workflow Mode and Explicit Hyperscale Consent

Primary sources:

• conflux/tools/tracks.py
• conflux/tools/hyperscale.py

Conflux separates orchestration mode from implementation semantics.

Mode controls

• set_autonomous_workflow_mode(mode=ask|single_track|hyperscale, ...)
• get_autonomous_workflow_mode()
• persisted mode state:
  • .gemini/workflow_mode.json

Hyperscale consent controls

• set_hyperscale_opt_in(enabled=true|false, rationale=...)
• get_hyperscale_opt_in_status()
• persisted opt-in state:
  • .gemini/hyperscale_opt_in.json

Deterministic enforcement

When CONFLUX_REQUIRE_HYPERSCALE_OPT_IN=1 (default), any hyperscale path is blocked until explicit consent exists.

Block payloads include:

• plain-English explanation
• actionable next steps
• choice explanations
• failure-mode tags

This prevents silent promotion from single-track to parallel execution.

Single-track execution outcomes

Single-track runtime returns explicit status families:

• awaiting_cli_agent_execution
• awaiting_human_review
• blocked
• completed_with_errors
• success (when inline worker execution is selected and all tracks complete)

This is intentional: an MVP-like track completion does not imply full-program completion.

16) Canonical Mutation Path and Write-Integrity Boundaries

Primary sources:

• conflux/tools/core_security.py (secure_write)
• conflux/core/work_order_manager.py (command-step write enforcement)
• conflux/tools/forensics.py (completion-time provenance checks)

Canonical mutation path

Track contracts default to:

• quality_gates.require_canonical_mutation_path = true
• quality_gates.require_state_mutation_gate = true

Command-path legacy writes (redirection/heredoc) are treated as non-canonical and are blocked unless explicitly permitted by environment:

• CONFLUX_ALLOW_LEGACY_COMMAND_WRITES=1

State mutation gate must be active before command writes proceed:

• failure code: state_mutation_gate_not_satisfied_for_write

Completion-time provenance hard checks

verify_claimed_completion blocks when:

• state transaction artifact is missing for tracks requiring state mutation gate
• secure-write provenance is missing when canonical mutation path is required
• implementation evidence has no non-management mutations
• planning/completion.md contains unresolved self-report markers (for example TODO/not implemented/placeholder) when placeholder rejection is enabled

This closes “artifact-only completion” paths without real admissible mutations.

Surgical phase-ledger edit guard

For conductor/workflow.md and conductor/tracks/<track>/plan.md, broad rewrites are blocked by similarity threshold:

• CONFLUX_REQUIRE_SURGICAL_PHASE_LEDGER_EDITS=1 (default)
• CONFLUX_PHASE_LEDGER_SURGICAL_THRESHOLD=0.75 (default)

Returned block payload includes deterministic failure mode metadata:

• non_surgical_phase_ledger_edit_blocked
• phase_ledger_overwrite_risk

17) Human Escalation Matrix (When It Is Required vs Suppressed)

Primary sources:

• conflux/core/phase_flow/compilation.py
• conflux/core/invariants.py
• conflux/core/human_verification.py
• conflux/core/observation_gates.py
• conflux/core/gates/quality_gate.py
• conductor/workflow.md

Deterministic policy

Escalation is tied to invariant testability:

• tier1: no human verification requirement
• tier2: independent/adversarial machine pass
• tier3: human verification required

Compilation binds these gates from invariant classes:

• require_human_verification_for_unverifiable
• require_observation_gates_per_subtask
• require_ui_lock_confirmation

These are enabled only when tier3 evidence is required.

Required-task semantics

If human verification is required:

• missing task artifact blocks (human_verification_tasks_missing)
• empty task list blocks (human_verification_tasks_empty)
• unresolved tasks block (pending_human_verification)
• invalid/unsigned attestation blocks (human_verification_untrusted_confirmation)

Plain-English response protocol

Human review prompts and action-center payloads include:

• decision question
• expected outcome
• choice explanations
• response examples

This is designed to minimize ambiguous “approve/deny without context” prompts.

18) Skill Policy Engine for Difficult Free-Form Construction Aspects

Primary sources:

• conflux/core/skill_policy.py
• conflux/core/capability_manager.py
• conflux/server.py (_apply_skill_policy)

Conflux skill injection is policy-driven and context-sensitive.
“Free-form application creation” here refers to process flexibility, not unbounded runtime behavior.

Runtime skill selection model

SkillPolicyEngine.evaluate(...) computes per-skill:

• eligibility via keyword/gate/loop-type/risk rules
• requiredness via required_when and required_on_risk
• skip conditions (immediate_mode, read_only, etc.)

Mode controls:

• off
• recommend
• require-risky
• strict

Auto-apply behavior is enabled by default:

• CONFLUX_SKILL_AUTO_APPLY=1
• max injected skill count/chars are bounded by env configuration

Built-in difficult-aspect generalized skills

These are generalized construction aids for hard software-engineering domains:

• skills/data-migration-safety
• skills/transaction-concurrency-guard
• skills/sync-conflict-playbook
• skills/search-index-tuning
• skills/external-integration-reliability

These are intentionally narrow. They are not generic “free-form app” triggers.

Skill policy artifact

Runtime policy state is persisted at:

• .gemini_security/skill_policy.json

If absent, default policy is synthesized in-memory (recommend mode, empty overrides).

19) Validation Command

Run the integrated regression suite:

PYTHONPATH=/home/bamn/Conflux pytest -q

Current workspace baseline after integration: full suite passing.

Enhancement Flow (conflux_enhance)

Primary sources:

• conflux/tools/enhance.py
• conflux/core/enhance/*
• conflux/tools/core_security.py (secure_write enhancement write interdiction)

conflux_enhance is the explicit brownfield enhancement path for an existing application.

It is intentionally:

• opt-in
• additive
• phase-governed
• isolated from the default main greenfield flow

It does not replace coordinate_autonomous_build.
It creates a separate enhancement session with its own artifacts under:

• conductor/enhance/<session-id>/

Enhancement intent

The enhancement flow is designed for:

• scanning an existing codebase
• drafting missing Conductor documents when absent
• requiring human review before inferred drafts become authoritative
• capturing a baseline snapshot before feature mutation
• bounding product mutation to approved scope during enhancement work

Enhancement runtime entrypoints

Current enhancement MCP tools include:

• conflux_enhance
• get_enhancement_session_status
• get_enhancement_baseline_discovery
• rerun_enhancement_baseline_discovery
• record_enhancement_human_approval
• approve_enhancement_grounding_review
• get_enhancement_draft_status
• review_inferred_enhancement_draft
• get_enhancement_goals
• record_enhancement_goal_iteration
• get_enhancement_harness_status
• record_enhancement_harness_artifact
• capture_enhancement_baseline_snapshot
• get_enhancement_baseline_status
• promote_enhancement_baseline_lock
• get_enhancement_impact_scope_status
• approve_enhancement_impact_scope
• advance_enhancement_phase
• record_enhancement_completion_report
• verify_enhancement_completion
• get_enhancement_integration_status

Enhancement phase machine

Authoritative phase logic:

• conflux/core/enhance/state_machine.py

Current legal enhancement phases:

1. enhance_intake
2. baseline_discovery
3. draft_review
4. baseline_characterization
5. baseline_lock
6. enhancement_planning
7. enhancement_implementation
8. verification_remediation
9. completion_review
10. completed
11. blocked

The active session persists:

• project_mode
• workflow_mode
• phase
• phase_status
• blocked_reason
• baseline_status
• draft_status
• scope_status
• pending_human_actions
• enhancement_goal

Enhancement sessions are always tagged as:

• project_mode = brownfield_enhancement

Enhancement flow sequence

1) Enhancement intake

Entered by:

• conflux_enhance

Behavior:

1. Requires explicit brownfield confirmation (confirm_brownfield=true).
2. Requires workflow mode to be resolved (single_track or hyperscale).
3. Creates or resumes an enhancement session.
4. Stores session state in:
   • .gemini/active_enhancement_session.json
   • conductor/enhance/<session-id>/enhancement_session.json

If workflow mode is unresolved, enhancement blocks with the same explicit workflow-choice posture used elsewhere.

2) Baseline discovery

Authoritative module:

• conflux/core/enhance/discovery.py

Behavior:

1. Scans the current repository root.
2. Detects existing Conductor docs:
   • conductor/product.md
   • conductor/tech-stack.md
   • conductor/tracks.md
3. Detects basic ecosystem signals:
   • package.json
   • pyproject.toml
   • requirements.txt
   • go.mod
4. Builds an existing test inventory.
5. Computes grounding_confidence.
6. Writes:
   • conductor/enhance/<session-id>/baseline_discovery_report.json

This report is deterministic and is used as the first brownfield assessment artifact before implementation begins.

3) Inferred draft generation and review

Authoritative module:

• conflux/core/enhance/drafts.py

When canonical Conductor docs are missing, enhancement creates inferred drafts under:

• conductor/enhance/<session-id>/drafts/product.md
• conductor/enhance/<session-id>/drafts/tech-stack.md
• conductor/enhance/<session-id>/drafts/tracks.md

Draft states are explicit:

• existing_authority
• inferred_draft
• human_edited
• approved
• waived

Rules:

• Existing canonical docs are treated as already authoritative (existing_authority).
• Inferred drafts are not authoritative.
• Inferred drafts must be:
  • approved,
  • edited and approved,
  • or waived before enhancement can advance into baseline characterization.
• Final draft actions require a signed human approval token recorded by a non-AI operator session via record_enhancement_human_approval.

Review state is persisted at:

• conductor/enhance/<session-id>/draft_review_status.json

If draft review is incomplete, phase advancement is blocked with:

• reason = draft_review_pending

4) Baseline characterization

This is the first mutation-governed enhancement phase.

Current implemented behavior:

1. Product mutation is still blocked.
2. Enhancement uses the canonical mutation gateway:
   • secure_write
3. secure_write consults enhancement mutation policy and allows only:
   • new tests
   • harness-like files
   • enhancement planning artifacts
   • enhancement evidence/baseline artifacts

This prevents premature application edits during the characterization window.

5) Baseline snapshot capture

Authoritative module:

• conflux/core/enhance/baseline.py

Before baseline lock, enhancement can capture a baseline snapshot via:

• capture_enhancement_baseline_snapshot

Behavior:

1. Walk the current project filesystem.
2. Build a deterministic file manifest summary.
3. Compute a file_manifest_hash.
4. Write:
   • conductor/enhance/<session-id>/baseline_snapshot.json
5. Mark baseline characterization report as certified:
   • conductor/enhance/<session-id>/baseline_characterization_report.json

This is the current implemented baseline lock precursor.

6) Baseline lock

After a valid snapshot exists, enhancement can enter baseline_lock and promote the lock via:

• promote_enhancement_baseline_lock

Behavior:

1. Validates that:
   • baseline snapshot exists
   • baseline characterization report is certified
2. Appends a baseline lock event to:
   • conductor/enhance/<session-id>/shadow_provenance.jsonl
3. Marks session:
   • baseline_status = locked

If the snapshot or certification is missing, entry into baseline_lock is blocked with:

• reason = baseline_snapshot_pending

If the lock is not yet promoted, entry into enhancement_planning is blocked with:

• reason = baseline_lock_pending

7) Enhancement planning

This phase exists only after the baseline is locked.

Current implemented planning controls:

1. Product mutation is still blocked.
2. Enhancement planning artifacts remain writable.
3. The next hard requirement is impact-scope approval before implementation begins.

This is where the user or operator defines what part of the existing application may actually change.

8) Impact scope approval

Authoritative module:

• conflux/core/enhance/impact_scope.py

Impact scope is persisted at:

• conductor/enhance/<session-id>/impact_scope.json

Scope includes:

• allowed_product_paths
• relevant_old_tests
• excluded_paths
• rationale
• bound signed human_approval

Rules:

• At least one allowed product path is required.
• Existing tests are writable only if explicitly listed in relevant_old_tests.
• Excluded paths remain blocked even if otherwise reachable.
• Scope approval requires a signed human approval token recorded by a non-AI operator session via record_enhancement_human_approval.

If impact scope is missing, entry into enhancement_implementation is blocked with:

• reason = impact_scope_pending

9) Enhancement implementation

This is the first phase where product mutation is allowed.

Enforcement path:

• secure_write
• conflux/core/enhance/mutation_policy.py

Current implemented write rules:

• product_source writes are allowed only inside approved allowed_product_paths
• existing_test writes are allowed only when the exact test path is listed in relevant_old_tests
• new_test, harness, planning, and evidence remain writable in the allowed phase
• out-of-scope product writes are blocked
• unrelated old test rewrites are blocked

This is the current structural implementation boundary for brownfield enhancement.

10) Verification remediation

This phase currently reuses the same scoped write posture as enhancement implementation.

That means:

• product fixes remain limited to approved product paths
• old test edits remain limited to approved relevant old tests
• unrelated rewrites remain blocked

This gives the remediation loop the same bounded intent posture as primary implementation.

11) Completion review, harness evidence, and completion report

Authoritative module:

• conflux/core/enhance/satisfaction.py
• conflux/core/enhance/harness.py

Before enhancement can move to completed, it must record an enhancement completion report via:

• record_enhancement_harness_artifact
• record_enhancement_completion_report
• verify_enhancement_completion

Current required fields:

• criteria_results (per-goal resolution records)
• rationale
• bound signed human_approval

The report is persisted at:

• conductor/enhance/<session-id>/enhancement_satisfaction_report.json

The harness evidence is persisted at:

• conductor/enhance/<session-id>/enhancement_harness_report.json
• conductor/enhance/<session-id>/enhancement_harness_attestation.json

Rules:

• Completion requires all of the following:
  • a passing external harness artifact
  • a valid harness attestation
  • per-goal criteria results with no unresolved goals
  • a signed human approval token for the completion report
  • a passing verify_enhancement_completion claim-verification result

If either is false or the report is missing, phase advancement to completed is blocked with:

• reason = enhancement_satisfaction_pending

Enhancement artifact map

Current enhancement-specific artifacts:

• conductor/enhance/<session-id>/enhancement_session.json
• conductor/enhance/<session-id>/baseline_discovery_report.json
• conductor/enhance/<session-id>/enhancement_human_approvals.json
• conductor/enhance/<session-id>/draft_review_status.json
• conductor/enhance/<session-id>/drafts/product.md
• conductor/enhance/<session-id>/drafts/tech-stack.md
• conductor/enhance/<session-id>/drafts/tracks.md
• conductor/enhance/<session-id>/baseline_characterization_report.json
• conductor/enhance/<session-id>/baseline_snapshot.json
• conductor/enhance/<session-id>/enhancement_goals.json
• conductor/enhance/<session-id>/impact_scope.json
• conductor/enhance/<session-id>/shadow_provenance.jsonl
• conductor/enhance/<session-id>/enhancement_harness_report.json
• conductor/enhance/<session-id>/enhancement_harness_attestation.json
• conductor/enhance/<session-id>/enhancement_satisfaction_report.json
• conductor/enhance/<session-id>/enhancement_claim_verification.json

Enhancement write boundaries

Primary enforcement source:

• conflux/tools/core_security.py

Enhancement-only write interdiction is active only when an enhancement session exists.

This means:

• the default greenfield flow is unchanged
• enhancement controls only apply inside brownfield_enhancement mode

Phase-specific implemented behavior:

• baseline_discovery, draft_review, enhancement_planning:
  • only enhancement planning/draft/evidence artifacts may change
• baseline_characterization:
  • new tests, harness files, and enhancement artifacts may change
  • product files and existing tests are blocked
• baseline_lock:
  • baseline/evidence/planning artifacts may change
• enhancement_implementation, verification_remediation:
  • product files only in approved scope
  • existing tests only in approved relevant-test set

Enhancement integration boundary (current implemented state)

Current enhancement runtime is intentionally not fully fused into every existing Conflux subsystem.

Future deep integration points exist as explicit stubs in:

• conflux/core/enhance/integration.py

Visible status surface:

• get_enhancement_integration_status

Currently stubbed bridge points:

• forensics_claim_bridge
• track_contract_bridge
• work_order_bridge
• policy_packet_bridge

These are intentionally inactive in the current implementation so that:

• the default single-track free-form creation flow remains stable
• enhancement mode can evolve without changing canonical greenfield semantics prematurely

Enhancement summary

The implemented enhancement flow currently guarantees:

• explicit opt-in via conflux_enhance
• deterministic brownfield discovery artifact creation
• active conductor state blocks grounding approval instead of being silently overridden
• no inferred docs becoming authoritative without review
• no draft/scope/completion approval without a signed human approval token
• no product mutation before baseline characterization and baseline lock
• no enhancement implementation without approved impact scope
• no completion without attested harness evidence, per-goal satisfaction, and final claim verification

This is the current implemented v1 behavior in code, not a future-design-only description.