$schema: ./schemas/workflow-contract.schema.json
contract_id: neutral-rfc-workflow
contract_version: 1.1.0
name: Neutral RFC workflow canon
summary: >-
Canonical, source-agnostic workflow for deriving publishable RFC-style
specifications from source-grounded evidence while preserving a separate,
auditable proof chain.
governing_rules:
- id: source-grounding
rule: Public technical claims and normative requirements enter the public track only from accepted claim records or explicit design decisions recorded in the evidence track.
- id: notes-before-prose
rule: Source notes, claim records, and required capability rows are created before public prose that depends on them.
- id: public-evidence-separation
rule: Public artifacts contain the specification; evidence artifacts retain source anchors, validation results, review findings, and correction history.
- id: earliest-artifact-correction
rule: When a gate fails, repair the earliest artifact that introduced the defect and then re-run only the affected downstream stages.
- id: provenance-containment
rule: Public artifacts must not reveal prompt text, tool traces, reviewer identities, hidden notes, or source-navigation mechanics unless a project pack explicitly approves publication.
- id: observed-examples
rule: Public examples are validated from rendered public output and are treated as observed or reproducible artifacts, never as predicted filler.
artifact_families:
public:
publishable: true
description: Reader-facing specification materials intended for review, implementation, and promotion.
must_exclude:
- source locators and internal evidence identifiers
- source-discovery query text or retrieval traces
- prompt text and controller instructions
- tool transcripts and agent identities
- review arguments, correction history, and escalation notes
evidence:
publishable: false
description: Internal proof materials that justify, validate, and repair the public specification.
must_include:
- stable artifact identifiers
- explicit status or disposition markers
- source references or design-decision references
may_include:
- minimal quoted source text
- validation commands or reproduction steps
- reviewer findings, uncertainty notes, and escalation records
visibility_classes:
public:
description: Safe for publication candidates and for public-text-only review roles.
readable_by:
- controller
- context-builder
- source-scout
- draft-author
- evidence-reviewer
- readability-reviewer
- cleanroom-reviewer
- release-owner
- public-reader
evidence-shared:
description: Internal proof material shared across drafting, review, and release roles.
readable_by:
- controller
- context-builder
- source-scout
- draft-author
- evidence-reviewer
- release-owner
evidence-restricted:
description: Internal material withheld from public-only reviewers because it leaks source navigation, hidden context, or local execution details.
readable_by:
- controller
- context-builder
- source-scout
- release-owner
roles:
controller:
purpose: Owns stage progression, correction routing, review isolation, and release readiness.
can_read: [public, evidence-shared, evidence-restricted]
context-builder:
purpose: Assembles orientation context, vocabulary, and discovery starting points without authorizing public claims by itself.
can_read: [public, evidence-shared, evidence-restricted]
source-scout:
purpose: Performs bounded source reads or observations to answer explicit gaps, contradictions, and high-risk questions.
can_read: [public, evidence-shared, evidence-restricted]
draft-author:
purpose: Turns accepted claims and validated examples into public specification prose.
can_read: [public, evidence-shared]
evidence-reviewer:
purpose: Reviews grounding, completeness, examples, security, provenance containment, and prose-risk findings against supplied evidence.
can_read: [public, evidence-shared]
readability-reviewer:
purpose: Reviews newcomer on-ramp quality from rendered public text alone.
can_read: [public]
cleanroom-reviewer:
purpose: Verifies implementability from the permitted public packet alone.
can_read: [public]
release-owner:
purpose: Decides what is promoted and retains the evidence packet needed for later audit.
can_read: [public, evidence-shared, evidence-restricted]
public-reader:
purpose: Represents downstream readers and implementers of the public specification.
can_read: [public]
artifact_types:
run-brief:
family: evidence
visibility: evidence-shared
description: Objective, scope, exclusions, required public deliverables, and named work area for one run.
context-packet:
family: evidence
visibility: evidence-shared
description: Compact orientation packet listing vocabulary, constraints, open questions, and source-backed starting context.
source-map:
family: evidence
visibility: evidence-shared
description: Source-discovery output naming source units, retrieval handles, contradictions, and unresolved coverage gaps.
source-scout-report:
family: evidence
visibility: evidence-shared
description: Narrow source-reading or observation report that separates direct evidence, inference, and uncertainty.
claim-ledger:
family: evidence
visibility: evidence-shared
description: Stable claim records with authority class, evidence anchors, status, and public-section impact.
capability-matrix:
family: evidence
visibility: evidence-shared
description: Required implementer capabilities mapped to accepted claims, public sections, and examples.
section-map:
family: evidence
visibility: evidence-shared
description: Working section structure that maps public sections to claims, capabilities, and example slots.
public-draft-source:
family: public
visibility: public
description: Editable source form of the public specification in the chosen authoring format.
public-rendered-output:
family: public
visibility: public
description: Rendered review or release form of the public specification.
example-report:
family: evidence
visibility: evidence-shared
description: Observed or otherwise validated example records with inputs, expected behavior, rendered extraction notes, actual results, and disposition.
mechanical-report:
family: evidence
visibility: evidence-shared
description: Structural and toolchain validation report for the current public draft.
review-report:
family: evidence
visibility: evidence-shared
description: Findings, severity, and disposition across grounding, completeness, examples, security, provenance, and ambiguity lanes.
reader-report:
family: evidence
visibility: evidence-shared
description: Cold-reader on-ramp findings captured from one rendered public document viewed in isolation.
prose-report:
family: evidence
visibility: evidence-shared
description: Voice and prose-risk audit focused on clarity, definition order, and tell-cluster reduction without changing semantics.
correction-log:
family: evidence
visibility: evidence-shared
description: Record of failed gates, root artifacts, rerun boundaries, changed artifacts, and final dispositions.
escalation-log:
family: evidence
visibility: evidence-shared
description: Record of issues that require an explicit human decision rather than unilateral workflow repair.
cleanroom-packet:
family: evidence
visibility: public
description: Public-only review packet assembled for clean-room proof, containing only the artifacts the clean-room reviewer is permitted to see.
cleanroom-report:
family: evidence
visibility: evidence-shared
description: Clean-room proof result showing whether a fresh implementer can recover the intended behavior from the permitted public packet.
public-manifest:
family: public
visibility: public
description: Publishable inventory of the public artifacts and their promotion status.
evidence-manifest:
family: evidence
visibility: evidence-shared
description: Audit inventory of retained evidence artifacts and the proof chain they preserve.
source_profile_hooks:
required_sections:
- profile-metadata
- corpus
- authority-order
- context-sources
- discovery-procedure
- example-procedure
- validation-procedure
- review-focus
- packaging-procedure
hook_points:
scope-bootstrap:
stage: scope
purpose: Declare the selected corpus, intended deliverables, authority order, and explicit exclusions for the run.
must_provide:
- corpus identifiers or stable source-unit handles
- intended public deliverable set
- authority ranking for primary and secondary sources
- explicit exclusions or out-of-scope areas
may_provide:
- release target labels
- known blocking risks
context-assembly:
stage: context-packet
purpose: Supply orientation material that gives the run shared vocabulary, constraints, and open questions without replacing source evidence.
must_provide:
- curated terminology or glossary entries
- known constraints and caveats
- open question seed list
- context source inventory
may_provide:
- prior section outlines
- preferred reader on-ramp notes
source-discovery:
stage: source-map
purpose: Supply stable source identifiers and the procedure for locating primary evidence.
must_provide:
- source unit identifiers
- discovery or query procedure
- contradiction markers, staleness markers, or equivalent caveats when available
- source areas that require narrow follow-up reads
may_provide:
- relationship data
- fixture or corpus-observation pointers
example-validation:
stage: example-lab
purpose: Define how examples are observed, reproduced, or otherwise validated against the selected corpus.
must_provide:
- example generation or observation procedure
- expected result capture rules
- rendered-text extraction rule
- reproducibility notes
may_provide:
- reusable fixtures
- environment assumptions
mechanical-validation:
stage: mechanical-validation
purpose: Define the required render, structure, reference, and separation checks for the public draft.
must_provide:
- required checks and failure conditions
- render targets or build products
- interpretation rules for warnings versus blockers
may_provide:
- cache or dependency notes
- alternate local and remote validation paths
review-focus:
stage: review-gauntlet
purpose: Define mandatory specialist review lenses and project-specific risk surfaces.
must_provide:
- required review lanes
- blocker definitions
- project-specific risk list
may_provide:
- recommended reviewer prompts
- severity taxonomy notes
packaging:
stage: final-packaging
purpose: Define which public formats are promotable, what evidence is retained, and where the packet is handed off.
must_provide:
- promotable public formats
- evidence retention policy
- promotion target description
may_provide:
- handoff checklist
- publication naming rules
stage_order:
- scope
- context-packet
- source-map
- source-scout
- claim-ledger
- capability-matrix
- draft-skeleton
- example-lab
- mechanical-validation
- review-gauntlet
- reader-onramp
- prose-audit
- correction-loop
- clean-room-proof
- final-packaging
stage_graph:
start_stage: scope
terminal_stages:
- final-packaging
default_failure_stage: correction-loop
pass_edges:
scope: [context-packet]
context-packet: [source-map]
source-map: [source-scout, claim-ledger]
source-scout: [source-scout, claim-ledger]
claim-ledger: [capability-matrix]
capability-matrix: [draft-skeleton]
draft-skeleton: [example-lab]
example-lab: [mechanical-validation]
mechanical-validation: [review-gauntlet]
review-gauntlet: [reader-onramp]
reader-onramp: [prose-audit]
prose-audit: [clean-room-proof]
correction-loop: []
clean-room-proof: [final-packaging]
final-packaging: []
dynamic_routes:
correction-loop: route-by-root-artifact-type
stages:
scope:
id: scope
title: Define objective and public deliverable boundary
owner_role: controller
support_roles: [draft-author, release-owner]
depends_on_artifacts: []
may_consume_artifacts: []
source_profile_hooks: [scope-bootstrap]
entry_criteria:
- A source profile has been selected for the run.
- The public deliverable target and intended audience are known.
- The run has an explicit objective or issue to resolve.
outputs: [run-brief]
next_stages: [context-packet]
repeatable: false
context-packet:
id: context-packet
title: Assemble bounded orientation context
owner_role: context-builder
support_roles: [controller, draft-author]
depends_on_artifacts: [run-brief]
may_consume_artifacts: []
source_profile_hooks: [context-assembly]
entry_criteria:
- The run brief names the objective, exclusions, and target deliverables.
- Orientation sources are known but are not yet treated as authoritative public evidence.
- Vocabulary, constraints, and open questions can be summarized compactly.
outputs: [context-packet]
next_stages: [source-map]
repeatable: true
source-map:
id: source-map
title: Map primary evidence sources and coverage gaps
owner_role: context-builder
support_roles: [controller, source-scout]
depends_on_artifacts: [run-brief, context-packet]
may_consume_artifacts: []
source_profile_hooks: [source-discovery]
entry_criteria:
- The run objective is stable enough to target specific source areas.
- The authority order for the selected corpus is known.
- Unresolved questions, likely contradictions, or coverage gaps are explicit.
outputs: [source-map]
next_stages: [source-scout, claim-ledger]
repeatable: true
source-scout:
id: source-scout
title: Resolve narrow source questions
owner_role: source-scout
support_roles: [controller]
depends_on_artifacts: [source-map]
may_consume_artifacts: [context-packet]
source_profile_hooks: [source-discovery]
entry_criteria:
- The source map names a bounded gap, contradiction, or high-risk question.
- The requested read or observation can be answered from a narrow source slice.
- The scout can report direct evidence, inference, and uncertainty separately.
outputs: [source-scout-report]
next_stages: [source-scout, claim-ledger]
repeatable: true
claim-ledger:
id: claim-ledger
title: Admit and classify candidate claims
owner_role: draft-author
support_roles: [controller, evidence-reviewer]
depends_on_artifacts: [run-brief, context-packet, source-map]
may_consume_artifacts: [source-scout-report]
source_profile_hooks: []
entry_criteria:
- Candidate claims can be tied to source evidence or explicit design decisions.
- Open questions and contradictions are visible rather than hidden in prose.
- Claim records exist before the public prose that depends on them.
outputs: [claim-ledger]
next_stages: [capability-matrix]
repeatable: true
capability-matrix:
id: capability-matrix
title: Map required implementer capabilities to accepted claims
owner_role: draft-author
support_roles: [controller, evidence-reviewer]
depends_on_artifacts: [claim-ledger]
may_consume_artifacts: [source-scout-report]
source_profile_hooks: []
entry_criteria:
- Accepted claims exist for the current scope.
- The workflow knows which reader-visible or implementer-visible capabilities the public document must deliver.
- Every required capability can be marked covered, open, scoped out, or blocking.
outputs: [capability-matrix]
next_stages: [draft-skeleton]
repeatable: true
draft-skeleton:
id: draft-skeleton
title: Build section map and public draft from accepted claims
owner_role: draft-author
support_roles: [controller]
depends_on_artifacts: [claim-ledger, capability-matrix]
may_consume_artifacts: [correction-log]
source_profile_hooks: []
entry_criteria:
- Accepted claims cover the required public sections.
- Capability rows identify which sections, algorithms, and examples they affect.
- Terminology and exclusions are stable enough to draft without guessing.
outputs: [section-map, public-draft-source]
next_stages: [example-lab]
repeatable: true
example-lab:
id: example-lab
title: Validate examples against observed or reproducible behavior
owner_role: draft-author
support_roles: [source-scout, evidence-reviewer]
depends_on_artifacts: [claim-ledger, capability-matrix, public-draft-source]
may_consume_artifacts: [section-map, source-scout-report]
source_profile_hooks: [example-validation]
entry_criteria:
- The draft names examples or example slots that affect public understanding.
- Each example can be tied to accepted claims.
- A validation or observation procedure exists for every required example.
outputs: [example-report]
next_stages: [mechanical-validation]
repeatable: true
mechanical-validation:
id: mechanical-validation
title: Run structural and toolchain validation
owner_role: draft-author
support_roles: [controller]
depends_on_artifacts: [section-map, public-draft-source, example-report]
may_consume_artifacts: []
source_profile_hooks: [mechanical-validation]
entry_criteria:
- The current public draft is coherent enough to render or lint.
- Example expectations have been recorded.
- Required validation commands or services are known.
outputs: [public-rendered-output, mechanical-report]
next_stages: [review-gauntlet]
repeatable: true
review-gauntlet:
id: review-gauntlet
title: Run specialist reviews over evidence and public text
owner_role: evidence-reviewer
support_roles: [controller, draft-author]
depends_on_artifacts: [claim-ledger, capability-matrix, example-report, public-draft-source, public-rendered-output, mechanical-report]
may_consume_artifacts: [source-scout-report, escalation-log]
source_profile_hooks: [review-focus]
entry_criteria:
- Grounding, completeness, example, security, ambiguity, and provenance lanes are defined for the run.
- Reviewers have the smallest evidence packet needed for their lane.
- Blocking findings will be routed to the earliest faulty artifact rather than sanded over in prose.
outputs: [review-report, escalation-log]
next_stages: [reader-onramp]
repeatable: true
reader-onramp:
id: reader-onramp
title: Run cold-reader newcomer on-ramp review
owner_role: readability-reviewer
support_roles: [controller]
depends_on_artifacts: [public-rendered-output]
may_consume_artifacts: []
source_profile_hooks: []
entry_criteria:
- The rendered public draft exists.
- The review packet can be limited to one public document at a time.
- The reviewer can judge first-loss point, unearned jargon, opening arc, and abstract-standalone quality from public text alone.
outputs: [reader-report]
next_stages: [prose-audit]
repeatable: true
prose-audit:
id: prose-audit
title: Run public-prose risk and voice audit
owner_role: evidence-reviewer
support_roles: [controller, draft-author]
depends_on_artifacts: [public-draft-source, public-rendered-output]
may_consume_artifacts: [reader-report, review-report]
source_profile_hooks: []
entry_criteria:
- The current public prose is stable enough for a wording-only audit.
- Reviewer findings can distinguish wording defects from upstream definition or example defects.
- Legitimate spec punctuation and structurally necessary lists will be dispositioned rather than auto-failed.
outputs: [prose-report, cleanroom-packet]
next_stages: [clean-room-proof]
repeatable: true
correction-loop:
id: correction-loop
title: Repair the earliest faulty artifact and propagate forward
owner_role: controller
support_roles: [draft-author, context-builder, source-scout, evidence-reviewer]
depends_on_artifacts: [review-report, reader-report, prose-report]
may_consume_artifacts: [cleanroom-report, correction-log, escalation-log]
source_profile_hooks: []
entry_criteria:
- A failed gate or unresolved blocker names the root artifact that introduced the defect.
- The affected downstream artifacts are known.
- The controller can re-run only the necessary stages after repair.
outputs: [correction-log, escalation-log]
next_stages: []
repeatable: true
clean-room-proof:
id: clean-room-proof
title: Prove implementability from the permitted public packet
owner_role: cleanroom-reviewer
support_roles: [controller]
depends_on_artifacts: [cleanroom-packet]
may_consume_artifacts: []
source_profile_hooks: []
entry_criteria:
- Blocking specialist-review findings are resolved or explicitly dispositioned.
- The public newcomer-facing gates have passed or every soft-fail has an explicit disposition.
- The clean-room packet contains only artifacts visible to a public-text-only reviewer.
- The clean-room reviewer did not participate in drafting or scouting for the same scope.
outputs: [cleanroom-report]
next_stages: [final-packaging]
repeatable: true
final-packaging:
id: final-packaging
title: Freeze public outputs and retained evidence
owner_role: release-owner
support_roles: [controller, draft-author]
depends_on_artifacts: [public-draft-source, public-rendered-output, claim-ledger, capability-matrix, example-report, mechanical-report, review-report, reader-report, prose-report, cleanroom-report]
may_consume_artifacts: [correction-log, escalation-log]
source_profile_hooks: [packaging]
entry_criteria:
- The public deliverables are complete for the selected promotion target.
- Every retained evidence artifact needed to reconstruct the proof chain is present.
- Any unresolved human decisions are either captured in the escalation log or removed from the public dependency chain.
outputs: [public-manifest, evidence-manifest]
next_stages: []
repeatable: true
correction_policy:
rule: Repair the earliest faulty artifact, then regenerate or re-review only the affected downstream artifacts.
route_by_root_artifact:
run-brief: scope
context-packet: context-packet
source-map: source-map
source-scout-report: source-scout
claim-ledger: claim-ledger
capability-matrix: capability-matrix
section-map: draft-skeleton
public-draft-source: draft-skeleton
example-report: example-lab
mechanical-report: mechanical-validation
review-report: correction-loop
reader-report: correction-loop
prose-report: correction-loop
correction-log: correction-loop
escalation-log: correction-loop
cleanroom-packet: prose-audit
cleanroom-report: correction-loop
public-manifest: final-packaging
evidence-manifest: final-packaging
rerun_scope: affected-downstream-stages-only
unresolved_blockers_stop_promotion: true