feat: add drive-to-done workflow discipline

[pascalandr]

Summary

• Adds an explicit Drive-To-Done operating discipline for PMA and Workflow Runner lifecycles.
• Defines terminal states (DONE, HARD BLOCKER, CYCLE LIMIT) and cycle limits so delegated workflows do not stop at partial planning or partial evidence.
• Updates core agent guidance and configuration templates to make the behavior discoverable.

Why

NomadWorks already had delegated workflow concepts, but the first-run experience could still end with plans, handoffs, or partial implementation evidence rather than a clear terminal state. This PR positions Drive-To-Done as a workflow reliability guardrail, not a production-readiness claim.

Review notes

• Independent PR targeting dev.
• Process/prompt/config focused.
• Keeps completion semantics explicit and auditable.

Verification

• Branch verification: npm test — PASS, 10 tests.

[pascalandr]

@CodeNomadBot

I want you to perform the gatekeeper checks for latest PR state

check for regressions
check for better possible implementations
Be the PR gatekeeper
Be ruthless about code quality

[codenomadbot]

Gatekeeper review for latest PR state.

Verdict: Request changes before merge.

What I understood: review PR #3 ruthlessly for regressions, implementation quality, and better alternatives. I treated this as review-only and did not modify PR files.

Findings:

1. Blocking: config docs/template advertise unimplemented feature flags.
   docs/setup/CONFIGURATION.md:121-123 documents features.drive_to_done, features.session_memory, and features.pai_context as enabling behavior. templates/nomadworks.yaml.template:16-35 also scaffolds drive_to_done, session_memory, and pai configuration. In the runtime, only debug_logs, debug_dumps, and keep_builtin_agents are read from repoCfg.features; grep found no source implementation for drive_to_done, session_memory, pai_context, session_memory, or pai. This means a user can uncomment these flags in newly scaffolded config and reasonably expect portable memory tools or PAI prompt injection, but nothing will happen. For this PR’s stated Drive-To-Done scope, either remove the unrelated session_memory/pai_context additions entirely or implement them. For features.drive_to_done, either wire it into runtime prompt/config behavior or reword it as a documented prompt convention rather than an enabling feature flag.

2. High: features.drive_to_done is not actually activated by config.
   agents/product_manager.md:46 says PMA should use Drive-To-Done “when repository config enables features.drive_to_done,” and docs/core/drive_to_done.md:23 says the cycle limit comes from drive_to_done.max_cycles. But the plugin never reads either value and does not inject active config into the PMA/Workflow Runner prompts. The behavior can activate when a user explicitly asks for it, but the config path described by the PR is not backed by code. Better implementation: during config(cfg), append a small generated prompt fragment only when repoCfg.features?.drive_to_done === true, including the resolved max_cycles value, so the shipped flag has real semantics.

Non-blocking observations:

• The Drive-To-Done policy text itself is directionally useful and keeps the lifecycle bounded by DONE, HARD BLOCKER, and CYCLE LIMIT.
• docs/core/drive_to_done.md is included in the package tarball and the prompt includes resolve correctly through the existing include mechanism.
• The PR is otherwise low-risk because it does not alter runtime source files, but that also causes the feature-flag mismatch above.

Verification performed:

• npm ci completed. It reported existing dependency audit issues: 2 moderate, 1 high. I did not change dependencies because that is outside this PR’s scope.
• npm test passed: 10/10 tests.
• npm run build passed.
• npm run release:check passed, including npm pack --dry-run.
• Working tree remained clean after verification.

Recommendation: do not merge until the template/docs are aligned with implemented behavior. Minimal acceptable fix: remove session_memory and pai_context from this PR, and either implement real drive_to_done config activation or describe Drive-To-Done solely as an explicit prompt/user-request discipline.

--
Yours,
CodeNomadBot

[pascalandr]

@CodeNomadBot
same review

[codenomadbot]

Gatekeeper re-review for latest PR state.

Verdict: Approved from gatekeeper review perspective.

What I understood: repeat the same ruthless PR gatekeeper review after the latest updates. I treated this as review-only and did not modify PR files.

Findings:

No blocking or high-severity findings found in the latest state.

What changed since the prior review:

• The misleading config/template additions for features.drive_to_done, features.session_memory, features.pai_context, drive_to_done.max_cycles, session_memory, and pai are gone.
• The PR is now scoped to prompt/docs guidance only: agents/product_manager.md, agents/workflow_runner.md, docs/core/drive_to_done.md, and docs/guides/WORKFLOW.md.
• Drive-To-Done is now described as an explicitly requested workflow discipline rather than a runtime-enabled feature flag, which aligns with the fact that there are no runtime source changes.

Quality assessment:

• The current implementation is appropriately small for a process/prompt change.
• The terminal states are explicit and bounded: DONE, HARD BLOCKER, CYCLE LIMIT.
• The new guidance preserves existing PMA/Workflow Runner boundaries and does not ask Workflow Runner to implement product code directly.
• The default 5-cycle limit is now framed as prompt policy, not as unimplemented config behavior.

Residual risks:

• This is prompt/process behavior, so there is no deterministic unit test coverage for whether agents will follow it in live workflows.
• The wording “repository workflow explicitly asks” is broad, but acceptable because it no longer claims a runtime feature flag activates the behavior.

Verification performed:

• Reviewed latest diff against origin/dev: 4 files, 49 insertions.
• Confirmed no lingering docs/template references to the removed unimplemented feature flags or config blocks.
• npm run release:check passed.
• npm test passed: 10/10 tests.
• npm run build passed as part of release check.
• npm pack --dry-run passed and includes docs/core/drive_to_done.md.
• Working tree remained clean after verification.

Recommendation: mergeable from this review scope.

--
Yours,
CodeNomadBot