docs: replace String.raw with direct assignment in script node examples

[Wirasm]

Summary

• Problem: The canonical script-node example (dag-workflow.yaml) and bundled workflow builder template both demonstrate String.raw\$nodeId.output`to consume upstream node output. This pattern fails when the substituted value contains a backtick — common in AI-generated markdown,output_formatpayloads, or any content with inline code spans — producing a crypticExpected ";"` parse error.
• Why it matters: Users who copy the example from docs or the workflow builder get broken scripts without any warning. The failure is non-obvious because the error appears to be a JS syntax error in their script, not a substitution issue.
• What changed: Replaced String.raw + JSON.parse with direct assignment (const data = $nodeId.output;) in all example/template files, and added explicit warnings in all relevant documentation.
• What did not change: The runtime engine is unchanged. archon-release.yaml String.raw usages are intentional (deterministic machine-generated JSON, already commented as safe) and are explicitly out of scope per the plan.

UX Journey

Before

Workflow author reads dag-workflow.yaml example or workflow builder template
  → copies String.raw`$nodeId.output` pattern into their script node
  → upstream node returns AI markdown containing a backtick (e.g. `b286ad97`)
  → bun -e '<script>' fails at parse time
  → cryptic "Expected ';'" error in workflow logs
  → author has no idea the substitution caused it

After

Workflow author reads dag-workflow.yaml example or workflow builder template
  → copies `const data = $nodeId.output;` pattern into their script node
  → upstream node returns any valid JSON, including content with backticks
  → JS assigns the literal directly — executes cleanly
  → docs also explain *why* String.raw is fragile, so authors who already
    have the old pattern know to update it

Architecture Diagram

Before

dag-workflow.yaml (example)          archon-workflow-builder.yaml (template)
  extract-labels node                  script node snippet
  String.raw`$fetch-issue.output`      String.raw`$other-node.output`
  [no docs warning]                    [no docs warning]

After

dag-workflow.yaml (example)          archon-workflow-builder.yaml (template)
  extract-labels node                  script node snippet
  const issue = $fetch-issue.output;   const data = $other-node.output;
  [~] comment updated                  [~] comment updated

workflow-dag.md [~]                  parameter-matrix.md [~]
  + CAUTION bullet about String.raw    + Silent Failures item #14

script-nodes.md [~]                  variables.md [~]
  + caution aside (Starlight)          + String.raw hazard note

bundled-defaults.generated.ts [~]
  regenerated after template change

Connection inventory:

From	To	Status	Notes
dag-workflow.yaml	(runtime engine)	unchanged	Only comment + pattern changed
archon-workflow-builder.yaml	bundled-defaults.generated.ts	modified	Template updated, bundle regenerated
docs/guides/script-nodes.md	(Starlight site)	modified	Added caution aside
skills/archon/references/	(Claude skill context)	modified	Updated 3 reference files

Label Snapshot

• Risk: risk: low
• Size: size: XS
• Scope: docs, skills
• Module: docs:script-nodes, skills:archon

Change Metadata

• Change type: docs
• Primary scope: multi (docs-web + skill references + bundled defaults)

Linked Issue

• Closes docs/examples: String.raw $nodeId.output pattern is fragile when output contains backticks #1427

Validation Evidence (required)

bun run validate

• All checks passed: bundled check (36 commands / 20 workflows), type-check, lint (0 errors, 0 warnings), format, tests — all ✅
• bun run generate:bundled was run after editing archon-workflow-builder.yaml before validate

Security Impact (required)

• New permissions/capabilities? No
• New external network calls? No
• Secrets/tokens handling changed? No
• File system access scope changed? No

Compatibility / Migration

• Backward compatible? Yes — documentation and examples only; no runtime behaviour changed
• Config/env changes? No
• Database migration needed? No

Human Verification (required)

• Verified scenarios: all 7 modified files reviewed for correct pattern replacement
• Edge cases checked: archon-release.yaml intentional String.raw usages confirmed not in scope (already commented as safe for deterministic JSON); Starlight :::caution syntax verified against existing docs-web files
• What was not verified: live Starlight rendering of the new aside (no local docs build performed)

Side Effects / Blast Radius (required)

• Affected subsystems/workflows: skill reference files (Claude skill context), docs-web site, bundled workflow defaults
• Potential unintended effects: none — no runtime code changed
• Guardrails/monitoring for early detection: bun run check:bundled catches any stale bundled-defaults.generated.ts

Rollback Plan (required)

• Fast rollback command/path: git revert <commit> — single commit, no migrations
• Feature flags or config toggles: none
• Observable failure symptoms: n/a (docs-only change)

Risks and Mitigations

• Risk: Starlight :::caution aside syntax may not render correctly if the docs site uses a different Starlight version
  • Mitigation: syntax matches existing caution asides in other docs-web files; risk is cosmetic only

Summary by CodeRabbit

• Documentation
  • Updated workflow script node guidance to recommend direct assignment of node outputs instead of String.raw wrapping patterns.
  • Added warnings about output containing backticks causing template literal breakage and cryptic parse errors.
  • Refreshed examples, workflow templates, and documentation references to clarify simpler, more reliable patterns for handling script substitutions.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9aaa9906-d4f1-40f0-94f3-077afb666763

📥 Commits

Reviewing files that changed from the base of the PR and between ef950ff and a1c14cb.

📒 Files selected for processing (7)

• .archon/workflows/defaults/archon-workflow-builder.yaml
• .claude/skills/archon/examples/dag-workflow.yaml
• .claude/skills/archon/references/parameter-matrix.md
• .claude/skills/archon/references/variables.md
• .claude/skills/archon/references/workflow-dag.md
• packages/docs-web/src/content/docs/guides/script-nodes.md
• packages/workflows/src/defaults/bundled-defaults.generated.ts

---

📝 Walkthrough

Walkthrough

This PR updates documentation, examples, and bundled workflow guidance to recommend a safer pattern for consuming upstream node output in inline scripts: direct assignment instead of wrapping with String.raw template literals, which break when output contains backticks.

Changes

Cohort / File(s)	Summary
Documentation References .claude/skills/archon/references/workflow-dag.md, .claude/skills/archon/references/variables.md, .claude/skills/archon/references/parameter-matrix.md	Updated script-node guidance to recommend direct assignment of $nodeId.output and documented the backtick failure mode when using String.raw wrapper pattern.
Workflow Examples .claude/skills/archon/examples/dag-workflow.yaml, .archon/workflows/defaults/archon-workflow-builder.yaml	Changed inline script examples from String.raw + JSON.parse to direct variable assignment (const data = $nodeId.output).
Public Documentation packages/docs-web/src/content/docs/guides/script-nodes.md	Added explicit warning section describing the backtick hazard with String.raw pattern and contrasting safe vs. fragile approaches with TypeScript examples.
Generated Bundled Defaults packages/workflows/src/defaults/bundled-defaults.generated.ts	Updated embedded archon-workflow-builder workflow YAML to use direct assignment pattern in script guidance.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related issues

• Workflow node failure messages dump entire script body — make errors actionable for self-correcting agents #1389 — Referenced in the linked issue as a contributing factor; error verbosity made the backtick-related parse failures harder to diagnose initially.

Possibly related PRs

• feat(workflows): add maintainer-standup workflow for daily PR/issue triage #1428 — Directly addresses the same String.raw backtick fragility issue with an identical corrective approach (moving to direct assignment).
• docs(script-nodes): dedicated guide + teach the archon skill #1362 — Modifies the same script-node documentation and example workflow files (extract-labels, archon-workflow-builder guidance).
• docs/skill: general hardening — fix inaccuracies, fill workflow/CLI/env gaps, add good-practices + troubleshooting #1363 — Updates related workflow-dag and script-node documentation for consistent handling of $nodeId.output substitution.

Poem

🐰 A backtick's bite broke the template raw,
So we ditched String.raw without a flaw.
Direct assignment, clean and tight,
JSON as JS—it just works right! ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch archon/task-fix-issue-1427

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Wirasm]

🔍 Comprehensive PR Review

PR: #1434 — docs: replace String.raw with direct assignment in script node examples
Reviewed by: code-review agent (error-handling / test-coverage / comment-quality / docs-impact: N/A — no source code changed)
Date: 2026-04-27

---

Summary

Pure documentation and example fix — the core pattern change is technically correct and complete. No blocking issues found.

Verdict: APPROVE (with two optional improvements below)

Severity	Count
🔴 CRITICAL	0
🟠 HIGH	0
🟡 MEDIUM	1
🟢 LOW	1

---

🟡 Medium — Rule 6 in generate-yaml prompt contradicts updated example

📍 .archon/workflows/defaults/archon-workflow-builder.yaml — Rule 6 in generate-yaml node

The embedded code example was correctly updated to show direct assignment, but Rule 6's prose still says "parse with JSON.parse / json.loads, not shell interpolation". An LLM following these instructions may weight explicit rule text over the example and regenerate the old JSON.parse(String.raw\...`)` pattern in user workflows — defeating the purpose of this PR.

Python (uv) still needs json.loads; the fix should distinguish runtimes.

View suggested fix (3-line text change)

      6. Use `script` nodes for typed data transforms (TypeScript JSON parsing, Python with deps)
         — stdout is captured as output, stderr is forwarded as a warning.
         $nodeId.output is NOT shell-quoted in script bodies.
         - **TypeScript/bun**: assign directly — `const data = $nodeId.output;`
           (JSON is valid JS expression syntax; avoid String.raw — it breaks on backticks)
         - **Python/uv**: use json.loads — `import json; data = json.loads("""$nodeId.output""")`
         Never interpolate into shell syntax.

Options: Fix now (recommended — small change, same file already touched) | Defer to follow-up PR

---

🟢 Low — try/catch semantics are misleading after pattern change

📍 .claude/skills/archon/examples/dag-workflow.yaml — extract-labels node

With JSON.parse(raw), the try/catch was the correct mitigation for a SyntaxError. With const issue = $fetch-issue.output;, a malformed value causes a compile-time error before the try block runs. The catch now only covers runtime property-access errors on an unexpected object shape — worth a short comment to avoid misleading users who copy this example.

View suggestion

    script: |
      // $fetch-issue.output is substituted raw — it's always valid JSON from gh issue view,
      // so the assignment is safe. The try/catch covers runtime errors (e.g. unexpected shape).
      try {
        const issue = $fetch-issue.output;
        const labels = (issue.labels ?? []).map((l) => l.name);
        console.log(JSON.stringify({ labels, count: labels.length }));
      } catch {
        console.log(JSON.stringify({ labels: [], count: 0, error: "unexpected issue shape" }));
      }

---

✅ What's Good

• Technically sound: Direct assignment works for all valid JSON (objects, arrays, strings, numbers, booleans, null — all valid JS expression syntax). Fix is correct.
• Comprehensive doc coverage: Warnings added to all relevant surfaces — workflow-dag.md, parameter-matrix.md, variables.md, script-nodes.md. No gaps found.
• Bundled defaults regenerated correctly: bundled-defaults.generated.ts matches the updated YAML; check:bundled will pass.
• Scope discipline: archon-release.yaml String.raw usages correctly left untouched — those are safe (deterministic machine-generated JSON, documented as intentional).
• Clean commit message: No AI attribution; follows project conventions.

---

Reviewed by Archon comprehensive-pr-review workflow

[Wirasm]

⚡ Self-Fix Report (Aggressive)

Status: PARTIAL
Pushed: ✅ Changes pushed to archon/task-fix-issue-1427
Commit: a1c14cb
Philosophy: Fix everything unless clearly a new concern

---

Fixes Applied (1 total)

Severity	Count
🔴 CRITICAL	0
🟠 HIGH	0
🟡 MEDIUM	1
🟢 LOW	0 (blocked — see below)

View all fixes

• ✅ Rule 6 contradicts updated example (.archon/workflows/defaults/archon-workflow-builder.yaml) — Updated Rule 6 prose to explicitly distinguish TypeScript/bun (direct assignment: const data = $nodeId.output;) from Python/uv (json.loads), removing the stale JSON.parse reference that contradicted the already-updated embedded code example. Regenerated bundled-defaults.generated.ts.

---

Tests Added

(none — pure documentation/YAML change)

---

Blocked (1)

Finding	Reason
LOW: try/catch semantics misleading in dag-workflow.yaml	Write permission to .claude/skills/archon/examples/dag-workflow.yaml not granted. The fix would add a comment: // The try/catch covers runtime errors (e.g. unexpected shape), not parse errors (which are compile-time with direct assignment).

---

Suggested Follow-up

(none — the blocked LOW is a one-line comment; trivial to apply manually)

---

Validation

✅ Type check | ✅ Lint | ✅ Tests (all passed) | ✅ check:bundled | ✅ format:check

---

Self-fix by Archon · aggressive mode · fixes pushed to archon/task-fix-issue-1427