# RFC Workflow

`rfc-workflow` is a reusable control pack for source-grounded RFC authoring.

It is designed to be **harness-neutral**. The repository defines the workflow, evidence discipline, review gates, and project-pack boundaries, but it does **not** ship runner-specific commands, plugins, or adapter files. A harness is expected to load the neutral assets and translate them into its own native execution primitives at runtime.

## What this repo is for

This repo packages the workflow pattern that was previously mixed together with one project's execution adapters.

The pattern has three stable ideas:

1. **Public RFC deliverables are separate from internal evidence artifacts.**
2. **Public claims enter the draft only after accepted evidence exists.**
3. **A run advances stage by stage, with gates, review lanes, recursive correction, and clean-room proof before final packaging.**

Those ideas are reusable across projects. The source corpus, references, document suite, and examples are not, so they live in project packs.

## Repository architecture

The repository is split into five surfaces.

### 1. Contract
- `workflow.contract.yaml`
- `schemas/workflow-contract.schema.json`

The contract is the canonical source of truth for:
- stage IDs and order,
- entry criteria,
- outputs,
- role visibility,
- backpressure and correction routing,
- and the public/evidence split.

If a prose file and the contract ever disagree about execution order or required outputs, follow the contract.

### 2. Neutral workflow rules
- `core/`

`core/` explains the reusable workflow semantics:
- controller behavior,
- source-authority rules,
- deliverable boundaries,
- style and provenance controls,
- validation gates,
- and context-engineering expectations.

These files describe **how the workflow works**, independent of any one source corpus.

### 3. Reusable operating materials
- `briefs/`
- `toolchains/`
- `templates/`

These files support execution without redefining the workflow:
- `briefs/` hold reusable role instructions.
- `toolchains/` hold reusable rendering or build mechanics.
- `templates/` hold standard evidence and packaging artifacts.

### 4. Project packs
- `projects/<name>/`

A project pack provides what the neutral workflow cannot:
- the source corpus boundary,
- project-specific references and terminology,
- the document suite or target scope,
- per-document briefs,
- and any source-specific example seeds or metadata.

A project pack answers **what to run the workflow against**. It should not redefine the workflow itself.

### 5. Harness-translation prompts
- `prompts/translate-workflow-for-harness.md`
- `prompts/run-selected-project.md`

These prompts replace checked-in adapter files. They tell a harness how to:
- map neutral workflow concepts into native primitives,
- preserve workflow semantics during that mapping,
- and execute one selected project pack.

## Deliberate non-features

This repo intentionally omits:
- harness-specific command stubs,
- plugin manifests,
- runner-specific workflow code,
- generated run directories,
- cached session output,
- final RFC artifacts,
- and source-specific rules in `core/`.

If a harness needs workers, tasks, jobs, subagents, staged prompts, or other runtime constructs, it should derive them from the neutral contract and prompts when the run starts.

## Workflow shape

A typical run follows this shape:

1. Define scope and target deliverables.
2. Load context and source-orientation material.
3. Gather and confirm source evidence.
4. Build claim/evidence and capability-coverage artifacts.
5. Draft from accepted evidence only.
6. Validate examples and mechanical consistency.
7. Run review lanes and reader-facing gates.
8. Apply recursive corrections to the earliest faulty artifact.
9. Run clean-room proof.
10. Package public outputs separately from evidence artifacts.

The exact stage IDs, gates, and outputs live in `workflow.contract.yaml`. The list above is the operator's mental model, not a substitute for the contract.

## Recommended start sequence

For a new operator or harness:

1. Read `README.md` for the repo model.
2. Read `AGENTS.md` for the operational load order.
3. Load `workflow.contract.yaml`.
4. Load the neutral docs under `core/`.
5. Load any reusable `briefs/`, `toolchains/`, and `templates/` needed for the selected scope.
6. Select exactly one project pack under `projects/`.
7. Read that pack's `README.md` plus its suite, corpus, references, metadata, document briefs, and examples.
8. Run `prompts/translate-workflow-for-harness.md` so the active harness maps the workflow into its own native primitives.
9. Run `prompts/run-selected-project.md` to execute the selected pack.

Do not skip the translation step. This repo is adapter-free by design.

## How to use this repo with any dynamic workflow harness

A compatible harness should be able to do four things well.

### Load files as operating instructions
The harness must be able to read the contract, neutral workflow docs, and one selected project pack.

### Allocate native execution units
The harness may call them tasks, jobs, workers, agents, lanes, or something else. The names can change; the responsibilities cannot.

### Preserve gates and correction behavior
The harness must preserve entry criteria, output requirements, review gates, and recursive correction routing rather than flattening the workflow into a single drafting pass.

### Keep reusable repo assets separate from run-local output
Run artifacts belong in a run-local workspace chosen by the operator or harness. The reusable repo surface should stay clean unless you are intentionally editing the workflow pack itself.

## Suggested operator mental model

Think of execution as:

> neutral contract + neutral workflow rules + selected project pack + runtime harness translation

That split makes it straightforward to add a new project later without forking the workflow or blessing one harness as canonical.

## Adding another project pack

To add a future non-Fossil project:

1. Create `projects/<new-project>/`.
2. Add a pack-local `README.md`.
3. Add only the source-specific materials that project needs: scope, corpus notes, references, metadata, document briefs, and examples.
4. Reuse the neutral contract and `core/` files unchanged unless the workflow semantics themselves actually need to change.
5. If the workflow semantics do change, update the neutral contract and supporting neutral docs instead of hiding the difference inside the project pack.

A new pack should plug different source material into the same workflow machine.

## Quick path map

```text
.
├── README.md
├── AGENTS.md
├── workflow.contract.yaml
├── schemas/
├── core/
├── briefs/
├── prompts/
├── toolchains/
├── templates/
└── projects/
    └── <project>/
```

## Rule of thumb for placing content

- Put it in `core/` when another project could use it unchanged.
- Put it in `briefs/`, `toolchains/`, or `templates/` when it supports execution but does not define project-specific behavior.
- Put it in `projects/<name>/` when it depends on one source corpus, one document suite, or one project's terminology and examples.
- Put it in `prompts/` when it helps a harness load or run the neutral workflow without becoming a checked-in harness adapter.