Source identity (from 02-design/technical-designs/TD-011-slider-autonomy-implementation.md):

ddx:
  id: TD-011
  depends_on:
    - FEAT-011
    - helix.workflow.artifact-hierarchy
    - ADR-001
  status: superseded
  superseded_by: helix.prd

SUPERSEDED — This technical design implemented the slider autonomy concept from the now-superseded FEAT-011. The current PRD (helix.prd) removes execution-loop autonomy controls, helix run, and runtime orchestration from HELIX’s scope. This document is retained for historical context only. Any runtime that wants an autonomy slider must author that in its own runtime-owned documentation with no dependency on this design.

TD-011: Slider Autonomy Implementation Design (Revised)

Context

This technical design specifies implementation details for the slider autonomy model that reduces HELIX from 15+ skills to 2 core capabilities while maintaining artifact stack coherence through automated graph traversal.

Key constraints:

• Must integrate with existing [[ID]] cross-reference pattern (no new storage format)
• Must maintain backward compatibility during deprecation period
• Must work within ADR-001 supervisory control model while shifting queue-drain execution ownership to ddx agent execute-loop and retaining HELIX wrappers only where they still add supervisory value

Requirements Summary

From FEAT-011:

1. Artifact graph traversal using existing [[ID]] cross-references
2. Two-activity impact detection (declared links + search fallback)
3. Physics-level vs resolvable conflict classification
4. Autonomy slider (low/medium/high) controlling flow behavior
5. Verification loop with failure triage and traceback
6. CLI simplification: helix input + ddx agent execute-loop, with any retained HELIX execution wrappers treated as transitional compatibility
7. Deterministic bead acceptance and success-measurement criteria so DDx-managed execution can land and close work without hidden human policy

Design Decisions

Decision 1: Graph Traversal Algorithm (Revised)

Approach: HELIX consumes DDx graph primitives to collect the impacted subgraph, then applies HELIX authority-order policy to that subgraph.

# Activity 1: Collect all impacted artifacts using DDx graph primitives
function collectImpactedSubgraph(startArtifact):
    visited = set()
    queue = [startArtifact]

    while queue not empty:
        current = queue.pop()
        if current in visited:
            continue
        visited.add(current)

        # DDx owns upstream/downstream neighbor lookup
        for neighbor in ddxGraphUpstreamNeighbors(current):
            if neighbor not in visited:
                queue.push(neighbor)
        for neighbor in ddxGraphDownstreamNeighbors(current):
            if neighbor not in visited:
                queue.push(neighbor)

    return visited

# Activity 2: HELIX orders the impacted set by authority tier
function orderByAuthority(artifacts):
    authorityTiers = {
        "vision": 0, "prd": 1,
        "feat": 2, "us": 3,
        "adr": 4, "architecture": 4,
        "sd": 5, "td": 6,
        "tp": 7, "tests": 8,
        "implementation_plan": 9,
        "code": 10
    }

    return sortBy(artifacts, key=lambda a: authorityTiers[getArtifactType(a)])

Boundary note: DDx owns [[ID]] indexing, reverse/dependent lookup, and graph collection. HELIX does not build a parallel graph engine; it applies workflow policy over DDx-provided graph results.

Authority ordering (aligned with workflows/artifact-hierarchy.md):

1. Product Vision
2. PRD
3. Feature Specifications and User Stories
4. Architecture and ADRs
5. Solution Designs and Technical Designs
6. Test Plans and Executable Tests
7. Implementation Plans
8. Source Code and Build Artifacts

Decision 2: Impact Detection Three-Activity System (Revised)

Activity 0: DDx graph index (authoritative)

• DDx indexes body [[ID]] links and frontmatter dependencies.
• DDx provides the authoritative upstream/downstream lookup used by HELIX.
• HELIX does not build or cache a separate reverse index outside the DDx substrate.

Activity 1: Declared links (primary)

• Use DDx graph lookups to resolve explicitly declared artifact relationships first.
• This is the authoritative impact surface for normal traversal.

Activity 2: Search fallback (supplemental)

# Extract key terms from input text or change diff
if [ -n "$INPUT_TEXT" ]; then
  echo "$INPUT_TEXT" | rg -oP '\b(?:postgres|sqlite|database|api|auth|login|[A-Z][a-z]+)\b'
elif [ -n "$GIT_DIFF" ]; then
  git diff HEAD~1 -- docs/helix/ | grep "^+" | rg -oiP '\b[a-z]{4,}\b'
fi | sort -u | head -20

# Search for term matches in artifact titles and content
for term in terms; do
  rg "$term" docs/helix/ --glob "*.md" --heading-line-number
done

Precedence: Declared DDx graph links always take precedence. Search results only supplement traversal when the declared graph is incomplete or under-linked.

Decision 3: Conflict Classification Rules (Revised)

Physics-level detection heuristic:

1. Authority-tier precedence first: If same constraint appears at different tiers, higher authority wins
2. Structured field analysis only: Only analyze ## Constraints or ## Requirements sections, not free text
3. Explicit contradiction patterns: Look for direct negations in structured fields (e.g., “must use X” vs “must NOT use X”)
4. Default to resolvable: If unclear, classify as resolvable and escalate via bead

Decision 4: Slider Config Schema (Revised)

# .helix/slider-config.yaml
autonomy_level: "medium"  # low | medium | high

bead_size_target: "small"  # small | medium | large
question_threshold: 0  # reserved for future/custom modes; ignored by current low/medium/high semantics
escalation_mode: "bead"  # reserved for future/custom modes; current low/medium/high semantics take precedence

speculative_allowed: true  # allow speculative work with marking
speculation_label: "kind:speculative"

conflict_handling:
  resolvable: "escalate"  # reserved for future/custom modes; current low/medium/high semantics take precedence
  physics_level: "block"  # block only option

graph_traversal:
  max_depth: 10  # prevent infinite traversal
  cycle_detection: true
  authority_ordering: true

verification:
  auto_traceback: true
  failure_triage: "automatic"  # automatic | manual

Environment overrides: HELIX_AUTONOMY=high, HELIX_SPECULATIVE=false

Autonomy precedence rule: The low/medium/high autonomy semantics in FEAT-011 override the generic defaults in conflict_handling, question_threshold, and escalation_mode whenever they conflict. In particular:

• low autonomy asks immediately and does not defer user confirmation through question_threshold
• medium autonomy asks when ambiguity/conflict blocks deterministic progress
• high autonomy does not block on resolvable conflicts even if generic config would otherwise ask or block

Note on conflict_handling.resolvable: Even when set to auto-resolve, an escalation bead MUST be created for traceability. The auto-resolve only determines whether execution blocks while waiting for human review in autonomy modes that permit such blocking.

Decision 5: CLI Implementation

New Command: helix input

# Usage
helix input "<natural language request>" [--autonomy low|medium|high]

# Examples
helix input "design a CRM with lead capture"
helix input "use postgres instead of sqlite" --autonomy high
helix input "the login button is broken" --autonomy medium

Autonomy behavior contract:

• low: ask before any first action and before each graph/artifact step (ask-first)
• medium: proceed with automated traversal and creation, then ask on ambiguity/conflicts
• high: run “until blocked” by physics-level constraints; ordinary DDx preserve outcomes end the current bounded attempt and return control to HELIX for interpretation, but do not by themselves stop the supervisory workflow or redefine the conflict class

Implementation flow:

1. Parse natural language, extract key terms and intent
2. Load slider config (file + env overrides)
3. Run impact detection (declared links + search)
4. Traverse graph to identify all affected artifacts
5. For each artifact layer and each downstream artifact candidate:
   • If autonomy=low: ask user before proceeding at each step and before creating each downstream artifact
   • If autonomy=medium: create deterministic non-conflict artifacts, but pause for user input when ambiguity or conflict blocks progress on an affected artifact
   • If autonomy=high: create downstream artifacts without interactive prompts unless blocked by physics-level
   • Detect conflicts, classify as resolvable/physics-level
   • Create beads for work needed
6. Output summary of created beads and assumptions

Primary Queue-Drain Command: ddx agent execute-loop

ddx agent execute-loop
ddx agent execute-loop --once
ddx agent execute-loop --harness codex --model gpt-5.4

execute-loop is the primary queue-drain surface for execution-ready work. It claims the next ready bead, runs ddx agent execute-bead, closes merged work with evidence, and leaves preserved or failed attempts open for later HELIX interpretation.

Role of helix run and helix build

• helix run becomes a compatibility wrapper and orchestration surface while DDx queue-drain parity is being validated.
• helix build remains relevant only when HELIX needs a single bounded action that is not yet expressible as a direct execute-loop or execute-bead invocation.
• Neither surface should own a separate claim/execute/close loop once execute-loop satisfies the required HELIX-visible contract.
• Direct ddx agent run remains valid for planning, review, alignment, and other non-managed prompts where no bead should be auto-claimed or auto-closed.
• If helix align remains as a public surface, it should be implemented as a bead-governed prompt launcher: acquire or create the kind:planning,action:align bead, then run the stored prompt and file ordered follow-on beads.

Decision 5b: DDx Handoff Model

HELIX delegates managed implementation and verification execution to DDx. The handoff is explicit: HELIX owns workflow selection, bead shaping, and result interpretation, while DDx owns managed execution, close-with-evidence mechanics, and runtime evidence.

Stage stance decision

HELIX should keep stage-specific behavior, but not as a new first-class workflow configuration knob.

Implementation contract:

• keep stage stance in HELIX-owned prompts and workflow wording, not in a separate profile manifest or --personality-style CLI flag
• planning stages (input, frame, design, evolve, triage, polish) use an exploratory, ambiguity-surfacing authoring stance
• managed execution stages (build, measure) use a bounded, contract-following stance that resists feature creep
• review uses an adversarial, findings-first stance
• alignment uses a top-down drift-audit stance
• supervisory stages (check, report) use a concise, state-oriented stance

Boundary rules:

• HELIX may map a stage to abstract execution needs such as smart vs cheap, or to harness-family constraints, but it must not encode concrete model versions as part of the stage stance
• DDx remains responsible for resolving the actual harness/model policy
• direct non-managed prompts (ddx agent run, direct agent use) should reuse the same HELIX-authored stage stance so behavior stays consistent across managed and unmanaged execution surfaces
• no new public configuration surface is needed beyond the existing stage entrypoints and any future DDx tier-policy integration

Handoff Flow

1. HELIX prepares execution context
   • Select bead ID and workflow scope
   • Determine autonomy behavior (low / medium / high)
   • Assemble governing artifact context, constraints, conflict notes, and deterministic success criteria
2. HELIX chooses the execution surface
   • Use ddx agent execute-bead <bead-id> [--from <rev>] [--no-merge] for one bounded attempt
   • Use ddx agent execute-loop when HELIX wants DDx to drain the current execution-ready queue for one project
   • Use direct ddx agent run only for non-managed prompts such as planning, review, or alignment
3. DDx executes and verifies
   • Run the bead or queue in a managed git context
   • Capture transcript, runtime evidence, and execution results
   • Run graph-discovered required executions and evaluate metric ratchets
   • Return merge/preserve outcomes with supporting evidence and close merged work when queue delegation is used
4. HELIX interprets the outcome
   • If merged: continue to the next workflow step or the next queue item
   • If preserved: treat this as the end of the current DDx-managed attempt, then escalate, ask for input, or revise prompts/workflow wording
   • If required execution failed or ratchets regressed: create follow-on beads or route to the appropriate supervisory action

Preserved outcomes are execution results, not physics-level conflicts. They stop the current bounded DDx attempt and hand control back to HELIX without redefining the autonomy conflict model.

Ownership Boundary

Decision 5c: Bead Success-Measurement Contract

Execution-ready beads must carry success criteria that a DDx-managed execution lane can evaluate without hidden human policy.

Required shape:

• name the concrete command, check, or execution doc that proves success
• name the observable repository state that should exist after success
• avoid vague words such as “works”, “correct”, or “complete” without a check
• align acceptance text with any required execution docs or ratchets that execute-bead will evaluate

Good:

• bash tests/helix-cli.sh passes and git diff --check passes
• docs/helix/02-design/contracts/CONTRACT-001-ddx-helix-boundary.md names ddx agent execute-loop as the queue-drain primitive and skills/helix-triage/SKILL.md requires deterministic success criteria for execution-ready beads

Bad:

• Queue draining works
• The docs are aligned

On the currently shipped DDx surface, execute-loop closes a bead when execute-bead reports success and records evidence. HELIX therefore must shape execution-ready beads so the success conditions that drive that outcome are explicit in the bead contract, the governing docs, and the discovered validation surface.

Decision 6: Verification Loop Integration (Revised)

Traceability metadata format:

# TP-036-list-mcp-servers.md
**User Story**: [[US-036-list-mcp-servers]]
**Technical Design**: [[TD-036-list-mcp-servers]]

## Test Cases

### TC-001: List MCP servers returns array
**Spec Reference**: TD-036 §3.2 API Response Format

Test file metadata (for code tests):

// tests/mcp-servers.test.js
/**
 * @spec-ref TD-036
 * @requirement TC-001
 */
test('list MCP servers returns array', async () => {
  // ...
});

Failure traceback algorithm (integrated with helix measure/report):

# Runs as part of helix measure activity after build completes
function traceBackFromFailure(failingTest, testOutput):
    # Step 1: Extract spec reference from test metadata
    specRef = parseTestMetadata(failingTest).spec_ref
    
    if not specRef:
        return createBuildBead("Missing spec ref", failingTest.path)
    
    # Step 2: Load spec and check for upstream conflicts
    spec = loadArtifact(specRef)
    upstreamRefs = parseCrossReferences(spec).upstream_dependencies
    
    conflict = detectUpstreamConflict(spec, upstreamRefs)
    if conflict:
        return createEscalationBead(
            "Spec conflict detected",
            specRef,
            details=conflict
        )
    
    # Step 3: Default triage - assume implementation bug unless evidence suggests otherwise
    # This is conservative and safe; helix report can refine if pattern emerges
    return createBuildBead(
        "Implementation does not meet spec",
        specRef,
        testOutput=testOutput
    )

Integration with existing HELIX workflow:

• Runs during helix measure activity (after build, before report)
• Uses existing ddx bead create for failure triage output
• Results feed into helix report for follow-on bead creation

Component Architecture

┌─────────────────────────────────────────────────────────────┐
│  helix input "<request>"                                     │
└──────────────────────┬──────────────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Input Parser                                                │
│  • Extract intent and key terms                              │
│  • Load slider config                                        │
└──────────────────────┬──────────────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Impact Detector                                             │
│  Activity 0: Build reverse index (cached)                      │
│  Activity 1: Parse [[ID]] cross-references                     │
│  Activity 2: Search fallback for term matches                  │
└──────────────────────┬──────────────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Graph Traverser                                             │
│  • Bidirectional BFS to collect subgraph                    │
│  • Topological sort by authority tier                       │
│  • Conflict classification                                   │
└──────────────────────┬──────────────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Bead Creator                                                │
│  • Request beads                                             │
│  • Escalation beads (resolvable conflicts)                  │
│  • Gap beads (missing artifacts)                            │
│  • Speculative beads (high autonomy assumptions)            │
└──────────────────────┬──────────────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  ddx agent execute-loop                                      │
│  Drains execution-ready queue and closes merged work        │
└─────────────────────────────────────────────────────────────┘

Integration with Existing HELIX Components

ADR-001 Supervisory Control Model

helix input is a new entrypoint that feeds the supervisory model:

• helix input creates beads → ddx agent execute-loop executes execution-ready work
• HELIX wrappers may still orchestrate planning, review, and check/alignment decisions
• Companion commands (design, polish, align, check) remain HELIX-owned subroutines

Artifact Hierarchy Compatibility

Uses existing patterns:

• [[ID]] cross-references for graph metadata
• Standard artifact naming (FEAT-XXX, TD-XXX, etc.)
• Directory structure under docs/helix/

DDx Bead Tracker Integration

New bead labels:

• kind:escalation - resolvable conflicts needing human review
• kind:speculative - assumptions made in high autonomy mode
• activity:frame, activity:design, etc. - existing activity labels preserved

Testing Strategy

Unit Tests

• Graph traversal with fixture artifacts (known input → known output)
• Conflict classification test cases (resolvable vs physics-level examples)
• Impact detection accuracy (declared links + search coverage)
• Reverse index correctness (ID resolution, downstream mapping)

Integration Tests

• End-to-end helix input flow with sample requests
• Bead creation verification (correct types, labels, dependencies)
• Verification loop traceback with failing tests

Acceptance Test Fixtures

Create minimal HELIX project with:

docs/helix/01-frame/
  prd.md [[FEAT-001]]
  features/
    FEAT-001-test-feature.md [[US-001, US-002]]
    user-stories/
      US-001-first-story.md
      US-002-second-story.md
docs/helix/02-design/
  solution-designs/
    SD-001-test-solution.md [[FEAT-001, TD-001]]
  technical-designs/
    TD-001-first-design.md [[US-001, TP-001]]
docs/helix/03-test/
  test-plans/
    TP-001-first-tests.md [[TD-001]]

Test: helix input "change US-001 acceptance criteria" should produce beads for TD-001, TP-001, and tests.

Migration Path

Activity 1: Planning (Current)

• FEAT-011 feature spec approved
• TD-011 technical design approved
• Implementation beads created

Activity 2: Core Implementation

• Graph traversal module
• Impact detection (declared links + search)
• Conflict classification logic
• Slider config loader

Activity 3: CLI Integration

• helix input command implementation
• Bead creator integration with DDx tracker
• execute-loop queue-drain adoption path and compatibility wrappers
• Verification loop traceback

Activity 4: Bead-Contract Hardening

• Triage/polish guidance requires execute-loop-friendly success criteria
• Measurement and acceptance conventions align with DDx close-with-evidence semantics
• Queue-ready beads can be evaluated without hidden wrapper logic

Activity 5: Testing and Validation

• Unit tests for all components
• Integration tests with fixture projects
• Acceptance criteria validation

Activity 6: Deprecation Period (v0.4.x)

• Decide which HELIX CLI surfaces remain first-class vs compatibility-only
• Add deprecation warnings to thin execution wrappers if DDx parity holds
• Document migration path
• Monitor usage patterns

Activity 7: Full Release (v1.0)

• Remove deprecated commands (optional, can keep as aliases)
• Update all documentation
• Training materials for new model

Risks and Mitigations

Open Questions

1. Should helix input support batch mode (multiple requests at once)?
2. How do we handle multi-repo scenarios where artifacts span repositories?
3. Should speculation beads auto-expire if not reviewed within N days?
4. What’s the exact format for test-to-spec traceability in code files?
5. Which HELIX CLI surfaces still add durable value once DDx owns queue draining?

References

• FEAT-011: Slider Autonomy Control
• Artifact Hierarchy
• ADR-001: Supervisory Control Model

This technical design is in PROPOSED status. Requires review and approval before implementation begins.