feat(planning): compile trigger input into run briefs

[rtzll]

Add deterministic run-brief compilation, artifact persistence, and CLI dry-run
inspection so backend prompts execute against a normalized execution contract.

Agent Details

    __( O)>  ● resuming · codex gpt-5.4
   \____)    20260314_1 · /work/repo
     L L     goose is ready
=== CODEX PROVIDER DEBUG ===
Command: "/usr/local/bin/codex"
Model: gpt-5.4
Reasoning effort: high
Skip git check: false
Prompt length: 13409 chars
Prompt: You are a general-purpose AI agent called goose, created by Block, the parent company of Square, CashApp, and Tidal.
goose is being developed as an open-source software project.
# Suggestion

The user has 7 extensions with 16 tools enabled, exceeding recommended limits (5 extensions or 50 tools).
Consider asking if they'd like to disable some extensions to improve tool selection accuracy.

# Response Guidelines

Use Markdown formatting for all responses.

Human: <info-msg>
It is currently 2026-03-15 16:18:00
Working directory: /work/repo

Current tasks and notes:
Once given a task, immediately update your todo with all explicit and implicit requirements

</info-msg>
# Rascal Run Instructions

Run ID: run_7930e4e7314a9eac
Task ID: rtzll/rascal#162
Repository: rtzll/rascal
Issue: #162

## Task

feat(planning): compile trigger input into a structured run brief before agent execution

Related: #119

## Summary
Rascal currently accepts manual task text and GitHub-triggered feedback, then passes that input into run artifacts without a first-class planning layer that normalizes intent.

This issue adds a deterministic run-brief compiler that turns issue bodies, PR comments, review comments, and manual prompts into a structured execution brief the backend can follow more reliably.

## Outcome
Every run begins with a normalized `run-brief` artifact that captures the objective, constraints, acceptance criteria, relevant files, validation expectations, and follow-up context in a backend-neutral format.

## Goals
- Improve first-pass run quality by clarifying ambiguous trigger input.
- Separate raw trigger content from the normalized brief the agent should execute against.
- Make planning decisions inspectable in run artifacts.
- Keep the system deterministic and compatible with both supported backends.
- Compose cleanly with the context-pack work in #119.

## Non-goals
- Letting the model freely rewrite the user’s intent.
- Building a generic ticket-planning product.
- Implementing semantic search or repo-wide retrieval in this issue.
- Solving multi-agent orchestration here.

## Scope
Implement V1 run-brief compilation with the following pieces.

1. Input normalization
- Support the current Rascal trigger classes, including:
  - manual CLI/API task text
  - issue label / issue edit flows
  - PR comment feedback
  - PR review feedback
  - PR review comment feedback
- Normalize raw inputs into a shared intermediate model.
- Preserve original source text in artifacts for traceability.

2. Run brief schema
- Add explicit artifacts such as:
  - `run-brief.json`
  - `run-brief.md`
- The brief should capture at least:
  - primary objective
  - background/context summary
  - constraints and instructions
  - acceptance criteria
  - likely target files or paths when directly inferable
  - requested validation or follow-up behavior
  - unresolved ambiguities or assumptions
- Keep the schema compact and inspectable.

3. Deterministic extraction rules
- Add a deterministic extraction pass that can identify common structure from GitHub input, such as:
  - checkbox lists
  - fenced code blocks
  - quoted prior feedback
  - inline file/path references
  - explicit "do not" constraints
- Strip noise that should not dominate the brief, while preserving it in source artifacts.
- Avoid hidden prompt magic in V1.

4. Ambiguity handling
- If the trigger input is too vague, record that explicitly in the brief.
- Add conservative fallback behavior such as:
  - continue with a minimal brief and explicit assumptions
  - optionally fail fast for configuration-controlled trigger classes later
- The brief should never pretend the request was clearer than it was.

5. Dry-run visibility
- Add a CLI/debug path to inspect the compiled brief without running the backend, for example:
  - `rascal run --dry-run-brief`
  - `rascal brief issue OWNER/REPO#123`
- The output should show both the normalized brief and the raw source summary.

6. Prompt assembly integration
- Thread the compiled brief into the existing run artifact generation and prompt assembly flow.
- Keep backend-specific prompt formatting separate from the brief compiler itself.
- The backend should receive the normalized brief as the primary execution contract.

## Suggested implementation approach
1. Add a small internal planning package.
- Separate source loading, normalization, extraction, and rendering.
- Model a stable `RunBrief` type with explicit provenance.

2. Keep extraction heuristics shallow and deterministic.
- Prefer regex/tokenization/markdown-structure parsing over opaque model-based rewriting.
- If later model-assisted planning is added, it should layer on top of this deterministic base.

3. Preserve provenance.
- Each field in the brief should be traceable to a raw source or a deterministic derivation.
- Ambiguous derived fields should carry an explanation.

4. Integrate cleanly with #119.
- The run brief describes what needs to be done.
- The context pack describes what repo guidance should accompany it.
- Do not collapse the two concerns into one artifact.

5. Make failures explicit.
- If source loading from GitHub fails, surface that as a planning error with a clear reason.
- Avoid silently compiling partial briefs that look authoritative.

## Acceptance criteria
- Rascal can compile raw trigger input into a normalized run brief for all current trigger classes.
- The brief is persisted as explicit JSON and Markdown artifacts in the run directory.
- The compiled brief preserves provenance and ambiguity notes.
- Operators can inspect the brief without starting a backend run.
- Backend prompt assembly uses the run brief as a first-class input.
- Tests cover manual tasks, issue-driven runs, PR feedback runs, ambiguity handling, and artifact rendering.

## Suggested test plan
- Unit tests for markdown extraction and path/reference detection.
- Unit tests for trigger-specific brief compilation.
- Integration tests for issue/comment/review payloads producing stable `run-brief.json` output.
- Regression tests for noisy GitHub comments that include quoted text or code fences.
- CLI tests for dry-run brief inspection.

## Implementation notes
- The brief compiler should clarify intent, not invent it.
- Keep the initial schema small enough that humans will actually read it during debugging.
- A dependable deterministic planner is more valuable here than a clever but unstable one.


## Constraints

- Do not ask for interactive input.
- Do not require MCP tools.
- Keep changes minimal and scoped to the requested task.
- Run `make lint` and `make test` before finishing if those targets exist.
- If one of those commands does not exist or cannot run, explain exactly why and run the closest equivalent checks instead.
- If you make changes, write /rascal-meta/commit_message.txt using a conventional commit title on the first line.
- Optionally add a commit body after a blank line in /rascal-meta/commit_message.txt.

## Additional Context

Triggered by label 'rascal' on issue #162

# Rascal Run Instructions

Run ID: run_8eb3f7257e3d893c
Task ID: rtzll/rascal#162
Repository: rtzll/rascal
Issue: #162

## Task

feat(planning): compile trigger input into a structured run brief before agent execution

Related: #119

## Summary
Rascal currently accepts manual task text and GitHub-triggered feedback, then passes that input into run artifacts without a first-class planning layer that normalizes intent.

This issue adds a deterministic run-brief compiler that turns issue bodies, PR comments, review comments, and manual prompts into a structured execution brief the backend can follow more reliably.

## Outcome
Every run begins with a normalized `run-brief` artifact that captures the objective, constraints, acceptance criteria, relevant files, validation expectations, and follow-up context in a backend-neutral format.

## Goals
- Improve first-pass run quality by clarifying ambiguous trigger input.
- Separate raw trigger content from the normalized brief the agent should execute against.
- Make planning decisions inspectable in run artifacts.
- Keep the system deterministic and compatible with both supported backends.
- Compose cleanly with the context-pack work in #119.

## Non-goals
- Letting the model freely rewrite the user’s intent.
- Building a generic ticket-planning product.
- Implementing semantic search or repo-wide retrieval in this issue.
- Solving multi-agent orchestration here.

## Scope
Implement V1 run-brief compilation with the following pieces.

1. Input normalization
- Support the current Rascal trigger classes, including:
  - manual CLI/API task text
  - issue label / issue edit flows
  - PR comment feedback
  - PR review feedback
  - PR review comment feedback
- Normalize raw inputs into a shared intermediate model.
- Preserve original source text in artifacts for traceability.

2. Run brief schema
- Add explicit artifacts such as:
  - `run-brief.json`
  - `run-brief.md`
- The brief should capture at least:
  - primary objective
  - background/context summary
  - constraints and instructions
  - acceptance criteria
  - likely target files or paths when directly inferable
  - requested validation or follow-up behavior
  - unresolved ambiguities or assumptions
- Keep the schema compact and inspectable.

3. Deterministic extraction rules
- Add a deterministic extraction pass that can identify common structure from GitHub input, such as:
  - checkbox lists
  - fenced code blocks
  - quoted prior feedback
  - inline file/path references
  - explicit "do not" constraints
- Strip noise that should not dominate the brief, while preserving it in source artifacts.
- Avoid hidden prompt magic in V1.

4. Ambiguity handling
- If the trigger input is too vague, record that explicitly in the brief.
- Add conservative fallback behavior such as:
  - continue with a minimal brief and explicit assumptions
  - optionally fail fast for configuration-controlled trigger classes later
- The brief should never pretend the request was clearer than it was.

5. Dry-run visibility
- Add a CLI/debug path to inspect the compiled brief without running the backend, for example:
  - `rascal run --dry-run-brief`
  - `rascal brief issue OWNER/REPO#123`
- The output should show both the normalized brief and the raw source summary.

6. Prompt assembly integration
- Thread the compiled brief into the existing run artifact generation and prompt assembly flow.
- Keep backend-specific prompt formatting separate from the brief compiler itself.
- The backend should receive the normalized brief as the primary execution contract.

## Suggested implementation approach
1. Add a small internal planning package.
- Separate source loading, normalization, extraction, and rendering.
- Model a stable `RunBrief` type with explicit provenance.

2. Keep extraction heuristics shallow and deterministic.
- Prefer regex/tokenization/markdown-structure parsing over opaque model-based rewriting.
- If later model-assisted planning is added, it should layer on top of this deterministic base.

3. Preserve provenance.
- Each field in the brief should be traceable to a raw source or a deterministic derivation.
- Ambiguous derived fields should carry an explanation.

4. Integrate cleanly with #119.
- The run brief describes what needs to be done.
- The context pack describes what repo guidance should accompany it.
- Do not collapse the two concerns into one artifact.

5. Make failures explicit.
- If source loading from GitHub fails, surface that as a planning error with a clear reason.
- Avoid silently compiling partial briefs that look authoritative.

## Acceptance criteria
- Rascal can compile raw trigger input into a normalized run brief for all current trigger classes.
- The brief is persisted as explicit JSON and Markdown artifacts in the run directory.
- The compiled brief preserves provenance and ambiguity notes.
- Operators can inspect the brief without starting a backend run.
- Backend prompt assembly uses the run brief as a first-class input.
- Tests cover manual tasks, issue-driven runs, PR feedback runs, ambiguity handling, and artifact rendering.

## Suggested test plan
- Unit tests for markdown extraction and path/reference detection.
- Unit tests for trigger-specific brief compilation.
- Integration tests for issue/comment/review payloads producing stable `run-brief.json` output.
- Regression tests for noisy GitHub comments that include quoted text or code fences.
- CLI tests for dry-run brief inspection.

## Implementation notes
- The brief compiler should clarify intent, not invent it.
- Keep the initial schema small enough that humans will actually read it during debugging.
- A dependable deterministic planner is more valuable here than a clever but unstable one.


## Constraints

- Do not ask for interactive input.
- Do not require MCP tools.
- Keep changes minimal and scoped to the requested task.
- Run `make lint` and `make test` before finishing if those targets exist.
- If one of those commands does not exist or cannot run, explain exactly why and run the closest equivalent checks instead.
- If you make changes, write /rascal-meta/commit_message.txt using a conventional commit title on the first line.
- Optionally add a commit body after a blank line in /rascal-meta/commit_message.txt.

## Additional Context

Triggered by label 'rascal' on issue #162


Assistant: 
Image files: 0
============================
{"type":"message","message":{"id":null,"role":"assistant","created":1773592895,"content":[{"type":"text","text":"I’m implementing the run-brief compiler and threading it through the existing run flow. First I’m mapping the current trigger, artifact, and prompt-assembly code so the change stays minimal and lands in the right seams.\n\nI’ve located the main seams: CLI run entrypoints in `cmd/rascal`, webhook-triggered run creation in `cmd/rascald`, and artifact/prompt setup under `internal/worker`. Next I’m reading those paths closely to see where raw trigger text currently flows straight into execution.\n\nThe current path is straightforward: `RunRequest` stores only `Instruction` and `Context`, then `writeRunFiles` emits `context.json` plus `instructions.md`. I’m reading those constructors now so I can introduce a first-class brief without widening the surface more than necessary.\n\nI have enough context to outline the implementation shape:\n\n1. Add `internal/planning` with a compact `RunBrief` schema, normalized source model, shallow markdown/path extraction, JSON/Markdown rendering, and a compiler from trigger input to brief.\n2. Extend `RunRequest` and run-file generation to persist `run-brief.json` and `run-brief.md`, while keeping existing `instruction/context` fields for compatibility.\n3. Compile briefs at creation sites: manual CLI/API runs, issue-backed runs, and webhook PR feedback flows, with source provenance and explicit ambiguity notes.\n4. Thread the brief into prompt assembly by making `instructions.md` render from the compiled brief rather than raw instruction/context text.\n5. Add dry-run inspection on the CLI, most likely `rascal run --dry-run-brief` for manual and `--issue` flows, plus tests around compilation, rendering, and CLI output.\n6. Finish with repo checks and the required `/rascal-meta/commit_message.txt`.\n\nI’m moving into the planning package and run-creation edits now.\n\nI’m at the point of adding the new planning layer and artifact writers. The next edits create the compiler package, then I’ll wire it into run creation and the CLI dry-run path.\n\nThe compiler package is in place. I’m wiring it into the orchestrator now so every run gets a compiled brief and the existing `instructions.md` starts rendering from that normalized brief instead of raw task text alone.\n\nI’ve finished the server-side brief compilation path. The remaining major piece is the operator-facing inspection flow in `rascal run --dry-run-brief`, then I’ll add tests around both the compiler and the new artifacts.\n\nThe run flow and CLI dry-run wiring are in place. I’m formatting and compiling next to catch integration mistakes before I add the test coverage this feature needs.\n\nThe first compile pass didn’t surface output, which usually means it’s still chewing through the full package graph. I’m narrowing to targeted package builds now so I can get actionable errors faster instead of waiting on the whole repo.\n\nThe code compiles across the touched packages now. I’m adding focused tests for the new compiler behavior, artifact writing, and the CLI dry-run path before I run the full repo checks.\n\nI’ve got focused tests passing on the new code paths. The last step is the repo-level verification the task asked for: `make lint` and `make test`, then I’ll write the conventional commit message file.\n\nImplemented a deterministic planning layer and threaded it through run creation.\n\n- Added `internal/planning` to normalize trigger input, extract shallow markdown structure, detect file/path references, record ambiguities/assumptions, and render JSON/Markdown briefs in [`internal/planning/compile.go`](/work/repo/internal/planning/compile.go#L13) and related files.\n- Every run now writes `trigger-input.json`, `run-brief.json`, and `run-brief.md`, and `instructions.md` is rendered from the normalized brief before agent execution in [`internal/orchestrator/runs.go`](/work/repo/internal/orchestrator/runs.go#L16).\n- API/manual runs, issue-backed runs, and webhook PR feedback flows now compile richer source-aware briefs before queuing runs in [`internal/orchestrator/api.go`](/work/repo/internal/orchestrator/api.go#L48) and [`internal/orchestrator/webhook.go`](/work/repo/internal/orchestrator/webhook.go#L96).\n- Added operator inspection endpoints plus `rascal run --dry-run-brief` in [`cmd/rascal/main.go`](/work/repo/cmd/rascal/main.go#L900), and updated the run help snapshot at [`cmd/rascal/testdata/help/run.golden`](/work/repo/cmd/rascal/testdata/help/run.golden).\n\nTests were added/updated in [`internal/planning/compile_test.go`](/work/repo/internal/planning/compile_test.go), [`cmd/rascal/main_test.go`](/work/repo/cmd/rascal/main_test.go), and [`cmd/rascald/main_test.go`](/work/repo/cmd/rascald/main_test.go). Verification passed with `make lint` and `make test`.\n\nThe required commit message was written to [`/rascal-meta/commit_message.txt`](/rascal-meta/commit_message.txt)."}],"metadata":{"userVisible":true,"agentVisible":true}}}
{"type":"complete","total_tokens":11364737}

Closes #162

---

Rascal run run_8eb3f7257e3d893c completed in 22m 59s · 11.36M tokens