c/claude-archeflow-plugin

Fork 0

Files

Christian Nennemann 5e2117c9be feat: add cross-run finding regression detection

2026-04-04 08:44:16 +02:00

24 KiB

Raw Blame History

name, description

name	description
run	Automated PDCA execution loop. Single-command orchestration that initializes a run, flows through Plan/Do/Check/Act phases, emits events at every step, saves artifacts to disk, and handles cycle-back with structured feedback. Use instead of manually following orchestration steps. <example>User: "archeflow:run"</example> <example>User: "Run this through ArcheFlow"</example> <example>User: "archeflow:run --start-from check"</example> <example>User: "archeflow:run --dry-run"</example>

name

description

run

Automated PDCA execution loop. Single-command orchestration that initializes a run, flows through Plan/Do/Check/Act phases, emits events at every step, saves artifacts to disk, and handles cycle-back with structured feedback. Use instead of manually following orchestration steps. <example>User: "archeflow:run"</example> <example>User: "Run this through ArcheFlow"</example> <example>User: "archeflow:run --start-from check"</example> <example>User: "archeflow:run --dry-run"</example>

ArcheFlow Run — Automated PDCA Execution Loop

This skill automates the full orchestration cycle. When invoked, Claude executes all PDCA phases end-to-end, emitting events and saving artifacts at every step. No manual phase-by-phase intervention needed.

Prerequisites

Load these skills (they are referenced throughout):

archeflow:orchestration — agent prompts, workflow selection, adaptation rules
archeflow:process-log — event schema and DAG parent rules
archeflow:artifact-routing — artifact naming, context injection, cycle archiving

Invocation

archeflow:run                           # Full run, auto-select workflow
archeflow:run --workflow standard       # Force a specific workflow
archeflow:run --start-from do           # Resume from Do phase (requires prior artifacts)
archeflow:run --start-from check        # Resume from Check phase
archeflow:run --dry-run                 # Plan phase only, show cost estimate
archeflow:run --max-cycles 1            # Override max cycles

Execution Steps

0. Initialize

Generate a run ID and set up the artifact directory.

# Generate run_id
RUN_ID="$(date -u +%Y-%m-%d)-<task-slug>"

# Create artifact directory
mkdir -p .archeflow/artifacts/${RUN_ID}

# Emit run.start event (seq=1, parent=[])
./lib/archeflow-event.sh "$RUN_ID" run.start plan "" \
  '{"task":"<task description>","workflow":"<fast|standard|thorough>","max_cycles":<N>}'

Track state: Maintain these variables throughout the run:

RUN_ID — unique run identifier
SEQ — current sequence number (read from event file line count after each emit)
CYCLE — current PDCA cycle number (starts at 1)
WORKFLOW — fast/standard/thorough (may change via adaptation rules)
ESCALATED — boolean, set true if A1 triggers

After emitting run.start, record SEQ_RUN_START=1.

If --start-from is specified, verify that the required prior artifacts exist in .archeflow/artifacts/${RUN_ID}/ before skipping phases. If missing, abort with an error.

0a. Lib Script Validation

Verify that all required library scripts exist and are executable before proceeding. Fail fast if any dependency is missing.

# Required lib scripts
REQUIRED_LIBS=(
  "archeflow-event.sh"
  "archeflow-memory.sh"
  "archeflow-git.sh"
  "archeflow-rollback.sh"
  "archeflow-report.sh"
  "archeflow-progress.sh"
)

MISSING=()
for lib in "${REQUIRED_LIBS[@]}"; do
  if [[ ! -x "./lib/$lib" ]]; then
    MISSING+=("$lib")
  fi
done

if [[ ${#MISSING[@]} -gt 0 ]]; then
  echo "ERROR: Missing or non-executable lib scripts:" >&2
  for m in "${MISSING[@]}"; do
    echo "  - lib/$m" >&2
  done
  echo "Ensure ArcheFlow is installed correctly. See README for setup." >&2
  exit 1
fi

# Check jq availability (required for event processing and memory)
if ! command -v jq &>/dev/null; then
  echo "ERROR: jq is required but not found in PATH." >&2
  echo "Install with: apt install jq / brew install jq" >&2
  exit 1
fi

0b. Memory Injection

Load cross-run memory lessons and inject into agent prompts. Use --audit to track which lessons were injected for this run:

# Load cross-run memory for this domain (with audit trail)
MEMORY_LESSONS=$(./lib/archeflow-memory.sh inject "$DOMAIN" "" --audit "$RUN_ID")

# Inject into Explorer/Creator prompts if non-empty
if [[ -n "$MEMORY_LESSONS" ]]; then
  EXPLORER_PROMPT="${EXPLORER_PROMPT}

${MEMORY_LESSONS}"
  CREATOR_PROMPT="${CREATOR_PROMPT}

${MEMORY_LESSONS}"
fi

0c. Model Configuration

Read model assignment from .archeflow/config.yaml and resolve the model for each archetype based on the current workflow. Per-workflow overrides take precedence over per-archetype overrides, which take precedence over the default.

CONFIG=".archeflow/config.yaml"

# Read default model
DEFAULT_MODEL=$(grep -A1 '^models:' "$CONFIG" 2>/dev/null | grep 'default:' | sed 's/.*default:\s*//' | tr -d '"' | head -1)
DEFAULT_MODEL="${DEFAULT_MODEL:-sonnet}"

# Resolve model for a given archetype and workflow
# Usage: resolve_model <archetype> <workflow>
resolve_model() {
  local arch="$1" wf="$2" model=""

  # Check per-workflow per-archetype override
  model=$(sed -n "/workflows:/,\$p" "$CONFIG" 2>/dev/null \
    | sed -n "/${wf}:/,/^    [a-z]/p" \
    | grep -A1 "archetypes:" | grep "${arch}:" \
    | sed "s/.*${arch}:\s*//" | tr -d '"' | head -1)
  [[ -n "$model" ]] && echo "$model" && return

  # Check per-workflow default
  model=$(sed -n "/workflows:/,\$p" "$CONFIG" 2>/dev/null \
    | sed -n "/${wf}:/,/^    [a-z]/p" \
    | grep 'default:' | sed 's/.*default:\s*//' | tr -d '"' | head -1)
  [[ -n "$model" ]] && echo "$model" && return

  # Check per-archetype override
  model=$(sed -n "/^  archetypes:/,/^  [a-z]/p" "$CONFIG" 2>/dev/null \
    | grep "${arch}:" | sed "s/.*${arch}:\s*//" | tr -d '"' | head -1)
  [[ -n "$model" ]] && echo "$model" && return

  # Fall back to default
  echo "$DEFAULT_MODEL"
}

# Example: EXPLORER_MODEL=$(resolve_model explorer "$WORKFLOW")

Use resolve_model when spawning each agent to pass the correct model. The resolved model can be included in the agent.start event data for cost tracking.

1. Plan Phase

1a. Explorer (if standard or thorough)

# Emit agent.start
./lib/archeflow-event.sh "$RUN_ID" agent.start plan explorer \
  '{"archetype":"explorer","prompt_summary":"Research codebase context for task"}' "$SEQ_RUN_START"

Spawn the Explorer agent using the prompt from archeflow:orchestration Step 1.

Agent(
  description: "Explorer: research context for <task>",
  prompt: "<Explorer prompt from orchestration skill>",
  subagent_type: "Explore"
)

After Explorer returns:

Save output to .archeflow/artifacts/${RUN_ID}/plan-explorer.md

Emit agent.complete:

./lib/archeflow-event.sh "$RUN_ID" agent.complete plan explorer \
  '{"archetype":"explorer","duration_ms":<ms>,"artifacts":["plan-explorer.md"],"summary":"<1-line summary>"}' "$SEQ_EXPLORER_START"

Record SEQ_EXPLORER_COMPLETE for DAG references.

1b. Creator

The Creator receives Explorer output (if it exists) or performs Mini-Reflect (fast workflow).

# Emit agent.start — parent is explorer.complete (or run.start for fast)
./lib/archeflow-event.sh "$RUN_ID" agent.start plan creator \
  '{"archetype":"creator","prompt_summary":"Design solution proposal"}' "$SEQ_EXPLORER_COMPLETE"

Spawn the Creator agent using the prompt from archeflow:orchestration Step 1.

Context injection (from artifact-routing skill):

Fast workflow: task description only
Standard/thorough: task description + contents of plan-explorer.md
Cycle 2+: task description + plan-explorer.md + act-feedback.md from prior cycle

Agent(
  description: "Creator: design proposal for <task>",
  prompt: "<Creator prompt from orchestration skill, with context injected per above>",
  subagent_type: "Plan"
)

After Creator returns:

Save output to .archeflow/artifacts/${RUN_ID}/plan-creator.md
Emit agent.complete
Record SEQ_CREATOR_COMPLETE

1c. Confidence Gate (Adaptation Rule A3)

Parsing instructions:

Read plan-creator.md, locate the ### Confidence table. Extract scores for each axis as floats:

CONF_FILE=".archeflow/artifacts/${RUN_ID}/plan-creator.md"

# Extract confidence scores (expects format: "| Task understanding | 0.8 |")
TASK_UNDERSTANDING=$(grep -i "task understanding" "$CONF_FILE" | grep -oE '[0-9]+\.[0-9]+' | head -1)
SOLUTION_COMPLETENESS=$(grep -i "solution completeness" "$CONF_FILE" | grep -oE '[0-9]+\.[0-9]+' | head -1)
RISK_COVERAGE=$(grep -i "risk coverage" "$CONF_FILE" | grep -oE '[0-9]+\.[0-9]+' | head -1)

# Fallback: if unparseable, emit warning and default to 0.0 (triggers gate, not bypasses it)
if [[ -z "$TASK_UNDERSTANDING" || -z "$SOLUTION_COMPLETENESS" || -z "$RISK_COVERAGE" ]]; then
  echo "WARNING: Could not parse confidence scores from plan-creator.md" >&2
  ./lib/archeflow-event.sh "$RUN_ID" decision plan "" \
    '{"what":"confidence_parse_failure","chosen":"warn","rationale":"one or more scores unparseable"}' "$SEQ_CREATOR_COMPLETE"
fi
TASK_UNDERSTANDING="${TASK_UNDERSTANDING:-0.0}"
SOLUTION_COMPLETENESS="${SOLUTION_COMPLETENESS:-0.0}"
RISK_COVERAGE="${RISK_COVERAGE:-0.0}"

Pause branch (Task understanding < 0.5):

The Creator does not sufficiently understand the task. Do not spawn Maker.

Emit decision event with "chosen":"pause"
Display message to user: "Creator rated task understanding at . Clarification needed before proceeding."
Block until the user provides clarification
Re-run Creator with the clarification appended to the task description

./lib/archeflow-event.sh "$RUN_ID" decision plan "" \
  '{"what":"confidence_gate","chosen":"pause","rationale":"task_understanding scored '"$TASK_UNDERSTANDING"'"}' "$SEQ_CREATOR_COMPLETE"

Upgrade branch (Solution completeness < 0.5):

The Creator's proposal is incomplete — more research is needed.

If fast workflow: upgrade to standard, spawn Explorer, then re-run Creator with Explorer output
If already standard/thorough: re-run Explorer with a focused prompt targeting the incomplete areas

./lib/archeflow-event.sh "$RUN_ID" decision plan "" \
  '{"what":"confidence_gate","chosen":"upgrade","rationale":"solution_completeness scored '"$SOLUTION_COMPLETENESS"'"}' "$SEQ_CREATOR_COMPLETE"

# If fast → standard upgrade:
WORKFLOW="standard"
# Spawn Explorer, then re-run Creator with Explorer findings

Mini-Explorer branch (Risk coverage < 0.5):

The Creator identified risks but lacks confidence in their assessment. Spawn a focused Explorer to investigate.

Agent(
  description: "Mini-Explorer: investigate risk area for <task>",
  prompt: "You are the EXPLORER archetype. The Creator rated risk coverage at <score>.
    Identified risks: <risks from plan-creator.md>
    Research ONLY the risky areas. Answer: Is the risk real? What mitigations exist? What tests/guards would help?
    Limit: focused output only.",
  subagent_type: "Explore"
)

Save output to .archeflow/artifacts/${RUN_ID}/plan-mini-explorer.md. The Maker receives both plan-creator.md and plan-mini-explorer.md as context.

./lib/archeflow-event.sh "$RUN_ID" decision plan "" \
  '{"what":"confidence_gate","chosen":"mini_explorer","rationale":"risk_coverage scored '"$RISK_COVERAGE"'"}' "$SEQ_CREATOR_COMPLETE"

Note: The mini-Explorer runs in parallel with Do phase preparation (5 min max). The Maker can proceed once both plan-creator.md and plan-mini-explorer.md are available.

1d. Phase Transition: Plan to Do

# Parent = all completing events in Plan phase
./lib/archeflow-event.sh "$RUN_ID" phase.transition do "" \
  '{"from":"plan","to":"do","artifacts_so_far":["plan-explorer.md","plan-creator.md"]}' "$SEQ_CREATOR_COMPLETE"

Record SEQ_PLAN_TO_DO.

2. Do Phase

2a. Maker

Context injection (from artifact-routing skill):

Contents of plan-creator.md (the proposal)
Cycle 2+: also contents of act-feedback.md filtered to Maker-routed findings only

./lib/archeflow-event.sh "$RUN_ID" agent.start do maker \
  '{"archetype":"maker","prompt_summary":"Implement proposal in isolated worktree"}' "$SEQ_PLAN_TO_DO"

Agent(
  description: "Maker: implement <task>",
  prompt: "<Maker prompt from orchestration skill, with Creator proposal injected>
    <if cycle 2+: Implementation feedback: <Maker-routed findings from act-feedback.md>>",
  isolation: "worktree",
  mode: "bypassPermissions"
)

After Maker returns:

Save implementation summary to .archeflow/artifacts/${RUN_ID}/do-maker.md
Capture list of changed files: git diff --name-only on the Maker's branch, save to .archeflow/artifacts/${RUN_ID}/do-maker-files.txt

Emit agent.complete:

./lib/archeflow-event.sh "$RUN_ID" agent.complete do maker \
  '{"archetype":"maker","duration_ms":<ms>,"artifacts":["do-maker.md","do-maker-files.txt"],"summary":"<files changed, tests added>"}' "$SEQ_MAKER_START"

Record SEQ_MAKER_COMPLETE

Critical: Verify the Maker committed its changes before proceeding. If uncommitted changes exist, instruct the Maker to commit.

2a-ii. Test-First Validation

After Maker completes, check do-maker-files.txt for test files:

TEST_FILES=$(grep -iE '([/_.-](test|spec)[/_.-]|\.(test|spec)\.|_(test|spec)\.|/tests?/|/__tests__/|/specs?/)' ".archeflow/artifacts/${RUN_ID}/do-maker-files.txt" || true)

If TEST_FILES is empty and domain is not writing:

Check if plan-creator.md contains a ### Test Strategy section
If yes: re-run Maker with targeted test instruction (one retry within Do phase)
If no test strategy specified: emit WARNING event and proceed

./lib/archeflow-event.sh "$RUN_ID" decision do "" \
  '{"what":"test_first_gate","chosen":"<pass|warn|retry>","rationale":"<reason>"}' "$SEQ_MAKER_COMPLETE"

The re-run prompt for the retry case:

"The proposal specified these test cases: . No test files were found in your changes. Add the specified tests before finishing."

This is one retry within the Do phase, not a full PDCA cycle. If the retry also produces no tests, emit WARNING and proceed to Check.

2b. Phase Transition: Do to Check

./lib/archeflow-event.sh "$RUN_ID" phase.transition check "" \
  '{"from":"do","to":"check","artifacts_so_far":["plan-explorer.md","plan-creator.md","do-maker.md","do-maker-files.txt"]}' "$SEQ_MAKER_COMPLETE"

Record SEQ_DO_TO_CHECK.

3. Check Phase

Important: Spawn Guardian FIRST, then evaluate A2 before spawning other reviewers.

3a. Guardian (always first)

Context injection: Maker's git diff + proposal risk section only (not full proposal, not Explorer research).

./lib/archeflow-event.sh "$RUN_ID" agent.start check guardian \
  '{"archetype":"guardian","prompt_summary":"Security and risk review of changes"}' "$SEQ_DO_TO_CHECK"

Agent(
  description: "Guardian: security review for <task>",
  prompt: "<Guardian prompt from orchestration skill, with Maker's diff injected>"
)

After Guardian returns:

Save to .archeflow/artifacts/${RUN_ID}/check-guardian.md

Emit review.verdict:

./lib/archeflow-event.sh "$RUN_ID" review.verdict check guardian \
  '{"archetype":"guardian","verdict":"<approved|rejected|approved_with_fixes>","findings":[...]}' "$SEQ_GUARDIAN_START"

Record SEQ_GUARDIAN_VERDICT

3b. Guardian Fast-Path Check (Adaptation Rule A2)

Parse Guardian's output. If 0 CRITICAL and 0 WARNING AND workflow is not escalated AND not first cycle of thorough:

./lib/archeflow-event.sh "$RUN_ID" decision check "" \
  '{"what":"guardian_fast_path","chosen":"skip_remaining_reviewers","rationale":"0 CRITICAL, 0 WARNING"}' "$SEQ_GUARDIAN_VERDICT"

Skip to Phase Transition (3d). Log "Guardian fast-path taken" in report.

Otherwise, proceed to spawn remaining reviewers.

3c. Remaining Reviewers (in parallel)

Spawn these based on workflow (see archeflow:orchestration for which reviewers apply):

Skeptic (standard/thorough):

Context: Creator's proposal (assumptions section focus)
Save to: check-skeptic.md

Sage (standard/thorough):

Context: Creator's proposal + Maker's diff + implementation summary
Save to: check-sage.md

Trickster (thorough only):

Context: Maker's diff only
Save to: check-trickster.md

Spawn all applicable reviewers in parallel (multiple Agent calls in one message). For each:

# Emit agent.start with parent = SEQ_DO_TO_CHECK
./lib/archeflow-event.sh "$RUN_ID" agent.start check <archetype> \
  '{"archetype":"<archetype>","prompt_summary":"<review focus>"}' "$SEQ_DO_TO_CHECK"

After each returns, emit review.verdict and save artifact.

3d. Phase Transition: Check to Act

Collect all verdict seq numbers for the parent array.

./lib/archeflow-event.sh "$RUN_ID" phase.transition act "" \
  '{"from":"check","to":"act"}' "<all_verdict_seqs>"

Record SEQ_CHECK_TO_ACT.

4. Act Phase

4a. Collect Verdicts

Read all check-*.md artifacts. Tally findings:

Count CRITICAL, WARNING, INFO per reviewer
Check for unanimous approval

4b. Escalation Check (Adaptation Rule A1)

If workflow is fast and Guardian found 2+ CRITICAL:

Set ESCALATED=true
Upgrade next cycle to standard (add Skeptic + Sage)
Emit decision event

4c. Branch: All Approved

If all reviewers approved (and completion criteria met, if defined):

Emit cycle.boundary:

./lib/archeflow-event.sh "$RUN_ID" cycle.boundary act "" \
  '{"cycle":<N>,"max_cycles":<M>,"exit_condition":"all_approved","met":true,"next_action":"complete"}' "$SEQ_CHECK_TO_ACT"

Pre-merge hook check:

# Read hooks config if it exists
if [[ -f ".archeflow/hooks.yaml" ]]; then
  PRE_MERGE_HOOKS=$(grep -A5 "pre-merge:" .archeflow/hooks.yaml || true)
  if [[ -n "$PRE_MERGE_HOOKS" ]]; then
    echo "Running pre-merge hooks..."
    # Execute hooks; abort merge if fail_action: abort
    # Hook execution is project-specific — see .archeflow/hooks.yaml
  fi
fi

Merge the Maker's worktree branch:

./lib/archeflow-git.sh merge "$RUN_ID" --no-ff

Post-merge test validation (using the auto-rollback script):

# Run tests and auto-revert if they fail
if ! ./lib/archeflow-rollback.sh "$RUN_ID"; then
  # Rollback script already reverted HEAD and emitted decision event
  # If cycles remain, cycle back with integration test failure feedback
  if [[ "$CYCLE" -lt "$MAX_CYCLES" ]]; then
    echo "Cycling back with integration test failure feedback..."
    # Build act-feedback.md with "integration test failure on main" as top finding
    # Continue to step 4d (Issues Found)
  else
    echo "Max cycles reached. Reporting failure to user."
    # Continue to step 4e (Max Cycles Reached)
  fi
fi

Clean up worktree:

./lib/archeflow-git.sh cleanup "$RUN_ID"

Proceed to Completion (step 5)

4d. Branch: Issues Found (cycles remaining)

If any reviewer rejected and CYCLE < MAX_CYCLES:

Build structured feedback using the Cycle Feedback Protocol from archeflow:orchestration:
- Extract findings from all check-*.md artifacts
- Route findings: Guardian/Skeptic issues → Creator, Sage issues → Maker
- Check convergence: same finding in 2 consecutive cycles → escalate to user
- Dedup cross-archetype findings
Save to .archeflow/artifacts/${RUN_ID}/act-feedback.md
Save applied fixes log (initially empty, populated during next Do phase):
```
touch .archeflow/artifacts/${RUN_ID}/act-fixes.jsonl
```

Emit cycle.boundary:

./lib/archeflow-event.sh "$RUN_ID" cycle.boundary act "" \
  '{"cycle":<N>,"max_cycles":<M>,"exit_condition":"all_approved","met":false,"next_action":"cycle_back"}' "$SEQ_CHECK_TO_ACT"

Archive current cycle artifacts:

mkdir -p .archeflow/artifacts/${RUN_ID}/cycle-${CYCLE}
cp .archeflow/artifacts/${RUN_ID}/plan-*.md .archeflow/artifacts/${RUN_ID}/cycle-${CYCLE}/
cp .archeflow/artifacts/${RUN_ID}/do-*.md .archeflow/artifacts/${RUN_ID}/do-*.txt .archeflow/artifacts/${RUN_ID}/cycle-${CYCLE}/ 2>/dev/null || true
cp .archeflow/artifacts/${RUN_ID}/check-*.md .archeflow/artifacts/${RUN_ID}/cycle-${CYCLE}/

Increment CYCLE, go back to Step 1 (Plan Phase)

4e. Branch: Max Cycles Reached

If CYCLE >= MAX_CYCLES and issues remain:

Report all unresolved findings to the user
Present the best implementation (on its branch, not merged)
Let the user decide: merge as-is, fix manually, or abandon
Emit cycle.boundary with "met": false, "next_action": "user_decision"

5. Completion

# Emit run.complete
./lib/archeflow-event.sh "$RUN_ID" run.complete act "" \
  '{"status":"completed","cycles":<N>,"agents_total":<count>,"fixes_total":<count>,"shadows":0,"artifacts":[<list>]}'

# Check for regressions from previously fixed findings
if ./lib/archeflow-memory.sh regression-check ".archeflow/events/${RUN_ID}.jsonl"; then
  echo "No regressions detected."
else
  echo "WARNING: Regressions detected — previously fixed findings have reappeared."
  echo "Review the regression output above and consider addressing them."
fi

# Generate report
./lib/archeflow-report.sh .archeflow/events/${RUN_ID}.jsonl

# Update run index
echo '{"run_id":"'$RUN_ID'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","task":"<task>","workflow":"<wf>","status":"completed","cycles":<N>}' \
  >> .archeflow/events/index.jsonl

Display the orchestration report to the user (see archeflow:orchestration report format).

Fix Tracking

When the Maker addresses review findings in cycle 2+, emit fix.applied for each:

./lib/archeflow-event.sh "$RUN_ID" fix.applied act "" \
  '{"source":"<reviewer>","finding":"<description>","file":"<path>","line":<n>}' "$SEQ_OF_REVIEW"

Also append to .archeflow/artifacts/${RUN_ID}/act-fixes.jsonl:

{"source":"guardian","finding":"SQL injection","file":"src/auth.ts","line":48,"fixed_in_cycle":2}

Dry-Run Mode

When --dry-run is specified:

Run only the Plan phase (Explorer + Creator)

Display:

Dry run for: "<task>"
  Workflow: <standard> (<N> cycles max)
  Agents per cycle: <count>
  Max agents total: <count * cycles>
  Plan phase result: see .archeflow/artifacts/<run_id>/plan-creator.md
  Creator confidence: <scores>
  Estimated phases: Plan (done) -> Do -> Check -> Act
  Proceed with full run? [y/n]

Do NOT emit run.complete — the run is paused, not finished
If user says yes, continue from --start-from do using the saved artifacts

Start-From Mode

When --start-from <phase> is specified:

Start from	Required artifacts in `.archeflow/artifacts/<run_id>/`
`plan`	None (equivalent to full run)
`do`	`plan-creator.md`
`check`	`plan-creator.md`, `do-maker.md`, `do-maker-files.txt`
`act`	All `check-*.md` files

Validate required artifacts exist. If missing, error:

Cannot start from <phase>: missing artifact <name>. Run the prior phase first.

When resuming, emit a run.start event with {"resumed_from":"<phase>"} in data.

Error Handling

Agent fails to return: Wait up to 5 minutes. If no response, emit agent.complete with "error": true, log the failure, and abort the run. Do not retry blindly.
Event emitter fails: Log a warning but do not block orchestration. Events are observation, not control flow.
Artifact write fails: This IS blocking. Artifacts are required for phase handoff. Abort and report.
Merge conflict: Do not force-resolve. Report the conflict, leave the branch intact, let the user decide.

Progress Display

Throughout the run, display live progress using the format from archeflow:using-archeflow:

━━━ ArcheFlow Run: <task> ━━━━━━━━━━━━━━━━━━━
Run ID: <run_id> | Workflow: <standard> | Cycle: 1/<max>

[Plan]  Explorer researching...        -> done (35s)
[Plan]  Creator designing proposal...  -> done (25s, confidence: 0.8)
[Do]    Maker implementing...          -> done (90s, 4 files, 8 tests)
[Check] Guardian reviewing...          -> APPROVED
[Check] Skeptic challenging...         -> APPROVED (1 INFO)
[Check] Sage reviewing...             -> APPROVED
[Act]   All approved — merging...      -> merged to main

━━━ Complete: 3m 10s, 1 cycle ━━━━━━━━━━━━━━━
Artifacts: .archeflow/artifacts/<run_id>/
Report: .archeflow/events/<run_id>.jsonl

24 KiB Raw Blame History