harness-tools/docs/adr/0001-workflow-architecture-24AUG2026.md

status, superseded-by

status	superseded-by
superseded	0006-skill-led-development-workflow-04SEP2026.md

Build workflow around persisted policy gates

Superseded by ADR 0006. Retained as the legacy custom-engine decision.

workflow will be a new extension rather than an activation or rename of _workflows. It will expose one command-style tool backed by atomic revisioned snapshots, Markdown Agent Profiles, deterministic eligibility followed by planner selection, a mandatory feature pipeline, and restricted feature or read-only analysis scripts. Every feature run receives a distinct exclusive worktree. Concurrency defaults to 8 under an immutable process-wide maximum of 32. Non-trivial UI work requires at least three structurally distinct prototypes and explicit user acceptance. Before implementation, the user chooses a fresh plan-seeded session, compaction of the current session that prefers smart_compact and falls back to normal Pi compaction when unavailable, or unchanged current context. Review uses a fresh session and excludes every Agent Profile that mutated the reviewed diff.

This keeps the caller interface small while making approval, prototype, recovery, and reviewer-independence rules enforceable in one workflow engine. We rejected unrestricted custom graphs because they could bypass policy, a general registry architecture because it adds speculative extension points, and event-sourced persistence because revisioned snapshots already provide the required recovery and audit data with less machinery.

Consequences

• Child agents inherit the existing nono sandbox; the restricted script process remains defense in depth for model-authored JavaScript.
• Project Agent Profiles and project configuration are loaded only for trusted projects.
• Potentially mutating interrupted Assignments require explicit recovery and are never replayed automatically.
• A versioned plan.md is the implementation handoff source for fresh-session and compacted-context transitions. Durable Gate-bound intents and callbacks keep implementation blocked until session replacement or compaction completes; normal Pi compaction is permitted only after the host confirms smart_compact is inactive, while an actual execution failure remains visible.
• Fresh-session replacement rotates the run lease to the new active parent session inside withSession; historical parent sessions may inspect but cannot mutate the run.
• The extension creates one exclusive worktree per feature run on feature/<feature-name>, where the validated feature name describes the feature without a numeric or run-ID suffix. Any existing branch rejects a new start and, when persisted state maps it to a Workflow Run, directs the caller to continue through inspect or decide; otherwise it directs the caller to choose another descriptive name. The extension does not merge, commit, reset, or remove the worktree automatically in the first version.
• _workflows remains inactive until migration or removal is approved separately.