Skip to content

docs(unic-archon-dlc): reconcile Archon version + node schema (redesign step 00)#260

Open
orioltf wants to merge 1 commit into
developfrom
feature/archon-schema-prework
Open

docs(unic-archon-dlc): reconcile Archon version + node schema (redesign step 00)#260
orioltf wants to merge 1 commit into
developfrom
feature/archon-schema-prework

Conversation

@orioltf

@orioltf orioltf commented Jun 24, 2026

Copy link
Copy Markdown
Member

Why

Pre-work step 00 of the unic-archon-dlc workflow redesign (docs/redesign/PLAN.md). This step gates every other step — the redesign assumed it could refactor the 7 shipped workflows in place, but that assumption rested on a version and a schema that turned out to be wrong. We must lock the truth before touching workflow YAML.

What was found (empirically)

  • Installed Archon is v0.3.12. The brew tap formula caps there (brew … coleam00/archon/archon0.3.12 already installed); the "update → v0.4.1" notice is GitHub-Releases-only, not brew-installable. The AGENTS.md claim "Archon ≥ 0.10" was fictional — no such version line exists.
  • The shipped workflows use a schema the CLI does not honour. Archon is key-discriminated (each node has exactly one of command|prompt|bash|script|loop|approval|cancel); the shipped YAMLs use a type: discriminator + node-level fresh_context: + inputs:/{{ }} Jinja.
  • archon validate passes all 7 anyway — because the stray type: field is silently ignored and every node still carries a recognised content key. Validation success masks silent semantic failures:
Shipped (type:-style) Runs on v0.3.12 as Defect
type: interactive + fresh_context + prompt: plain prompt 🔴 HITL gate never pauses
type: loop + prompt: (no loop:/until:) single-shot prompt 🔴 loop never iterates
node-level fresh_context: true ignored 🔴 anti-cheat isolation never applied
inputs: + {{ inputs.slug }} literal passthrough 🔴 slug never substituted; paths break

This is a blocking migration, not a cosmetic mismatch — gates, loops, fresh-context, and slug substitution are all inert while the CLI reports success.

Changes (research + writing only — no workflow YAML touched)

  • Add ADR-0011 — version target (≥ 0.3.12, 0.4.1 forward-compatible-but-unverified) + key-discriminated node-schema conventions all redesign steps must follow.
  • PLAN.md pre-work Fix release workflow, document Gitflow, and close post-launch open points #1 rewritten — confirmed version, translation table, silent-failure finding, ⚠ blocking-migration flag, $ARGUMENTS-slug implication.
  • AGENTS.md (+CLAUDE.md symlink) — ≥ 0.10≥ 0.3.12 + ADR-0011 link.
  • ADR-0003 AcceptedSuperseded by ADR-0009 (Ralph-era spec format retired by 0009 but never reflagged) + ADR index updated + 0011 row added.

"Done when" — answered

Need Schema convention
HITL gate approval: node + workflow-level interactive: true
Loop loop: key (prompt/until/max_iterations)
Fresh-context node context: fresh (or loop.fresh_context)
Data passing $nodeId.output(.field); input via $ARGUMENTS; $ARTIFACTS_DIR; no inputs:/{{ }}

Verification

  • All 7 shipped workflows still archon validateok (no YAML touched).
  • Prettier clean on all edited Markdown. No lib/ changes → no typecheck/test.

🤖 Generated with Claude Code

…gn step 00)

Pre-work step 00 gates the workflow redesign. Establishes the truth the
refactor must build on:

- Installed Archon is v0.3.12 (brew formula caps there; 0.4.1 is GitHub-only
  and not brew-installable). The "Archon >= 0.10" claim was fictional.
- The CLI uses a key-discriminated node schema (one of command|prompt|bash|
  script|loop|approval|cancel), NOT the type:-style schema the 7 shipped
  workflows use. `archon validate` passes them anyway because the stray
  `type:` field is ignored — masking silent failures: HITL gates never pause,
  loops run once, fresh_context is ignored, {{ inputs.slug }} never substitutes.

Why this matters: it's a blocking migration, not a cosmetic mismatch — every
gate, loop, and slug reference is inert while validation reports success.

Deliverables (research + writing only; no workflow YAML touched):
- Add ADR-0011: version target (>=0.3.12) + node-schema conventions + the
  HITL/loop/fresh-context/data-flow answers all redesign steps depend on.
- PLAN.md pre-work #1 rewritten with the confirmed version, translation table,
  silent-failure finding, and blocking-migration flag.
- Correct ">= 0.10" -> ">= 0.3.12" in AGENTS.md (CLAUDE.md symlink).
- Fix ADR-0003 status: Accepted -> Superseded by ADR-0009 (Ralph-era spec
  format retired by 0009 but never reflagged); update ADR index + add 0011 row.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant