Summary

This PR tightens Atlas's execution contract around plan mutation and /start-work handoff, while also making Atlas treat Prometheus task metadata as the default execution contract instead of pure ad hoc reclassification.

It fixes the concrete contract inconsistencies described in:

• Fixes [Bug]: Atlas execution contract is internally inconsistent about plan mutability and post-verification behavior #2601
• Addresses [Feature]: Atlas should treat Prometheus execution metadata as authoritative instead of re-planning category and parallelization at runtime #2600 at the prompt / reminder contract layer

What changed

1. Tighten Atlas plan-mutation rules

Atlas prompts and reminders now say explicitly:

• Atlas MAY update checkbox / status markers after verification
• Atlas MUST NOT rewrite task wording
• Atlas MUST NOT add/remove/reorder tasks
• Atlas MUST NOT change dependencies or acceptance criteria

Files:

• src/agents/atlas/default.ts
• src/agents/atlas/gpt.ts
• src/agents/atlas/gemini.ts
• src/hooks/atlas/system-reminder-templates.ts
• src/hooks/atlas/verification-reminders.ts

2. Remove commit instructions from the Atlas reminder flow

The Atlas reminder flow no longer tells Atlas to COMMIT ATOMIC UNIT directly.

This keeps the execution contract coherent with Atlas's orchestrator role and avoids mixing plan-state tracking with direct git instructions in the same reminder path.

Files:

• src/hooks/atlas/verification-reminders.ts
• src/hooks/atlas/index.test.ts

3. Prefer planner metadata over Atlas re-planning

Atlas prompts now explicitly treat existing plan metadata as the default execution contract when the current task block already includes fields such as:

• Parallel Execution Graph
• Delegation Recommendation
• Recommended Agent Profile
• Parallelization
• Depends On
• Blocked By

The dynamic decision matrix is now framed as fallback guidance rather than the primary execution authority.

Files:

• src/agents/atlas/default.ts
• src/agents/atlas/gpt.ts
• src/agents/atlas/gemini.ts
• src/agents/atlas/prompt-section-builder.ts

4. Preserve Atlas handoff in /start-work

/start-work already updates the session agent to Atlas, but follow-up events can still lose that handoff if the outgoing message is not stamped consistently.

This PR stamps the outgoing message with the Atlas display name so downstream orchestration logic sees the same handoff.

Files:

• src/hooks/start-work/start-work-hook.ts
• src/hooks/start-work/index.test.ts

5. Remove dead Atlas auto-commit reminder plumbing

This branch also removes the Atlas-hook plumbing that only existed to thread start_work.auto_commit into the old reminder text.

That parameter no longer changed runtime behavior once the direct commit instructions were removed, so keeping it in the Atlas reminder path would just leave dead wiring in the PR.

For config compatibility, the existing start_work.auto_commit schema field is left in place but treated as legacy compatibility rather than active Atlas reminder behavior.

Files:

• src/hooks/atlas/atlas-hook.ts
• src/hooks/atlas/tool-execute-after.ts
• src/hooks/atlas/types.ts
• src/plugin/hooks/create-continuation-hooks.ts
• src/config/schema/start-work.ts

6. Add regression coverage

This adds focused tests to lock in:

• planner-metadata-first prompt language
• fallback-only decision matrix framing
• status-only plan mutation reminder behavior
• /start-work handoff message stamping

Files:

• src/agents/atlas/atlas-prompt.test.ts
• src/hooks/atlas/index.test.ts
• src/hooks/atlas/verification-reminders.test.ts
• src/hooks/start-work/index.test.ts

Why this matters

Before this change, Atlas behavior was internally inconsistent in a few important ways:

• plan mutation rules were underspecified
• reminder flow still pushed Atlas toward direct commit behavior
• Prometheus could emit structured execution metadata, but Atlas still defaulted to re-planning
• /start-work session handoff was updated in state but not reflected on the outgoing message

The result was a fuzzier planner / executor boundary than the architecture implies.

This PR makes the runtime contract more coherent without introducing a new parser or changing the plan file format.

Scope / non-goals

This PR does not implement a fully structured runtime parser for Prometheus execution metadata.

Issue #2600 is addressed here at the contract layer:

• Atlas now defaults to planner metadata when present
• Atlas only uses the decision matrix as fallback guidance

But a future, stronger implementation could still parse task metadata into typed execution state rather than relying on prompt / reminder compliance alone.

Verification

Focused tests run locally:

bun test src/agents/atlas/atlas-prompt.test.ts src/hooks/atlas/verification-reminders.test.ts src/hooks/atlas/index.test.ts src/hooks/start-work/index.test.ts

These passed on the dev-based replay branch.