Project Packs

A project pack is the reusable project-specific layer of this RFC workflow.

The repo-wide workflow defines neutral mechanics in core/, repo-level prompts, reviewer roles, and toolchain behavior. A pack under projects/<name>/ adds the subject-matter context those neutral mechanics need for one concrete RFC suite or document family: source corpus boundaries, authoritative references, terminology ownership, draft defaults, and per-document drafting briefs.

Within each pack namespace, keep two surfaces distinct:

• projects/<name>/ holds reusable project-pack inputs that define what the workflow should run against.
• projects/<name>/runs/<run-id>/ holds per-run artifacts: generated drafts, evidence packets, gate/status records, and optional logs for one execution.

In short:

• core/ and the top-level workflow say how the workflow runs.
• projects/<name>/ says what this project is about and which source material governs it.
• projects/<name>/runs/<run-id>/ says what happened during one concrete run.

There is no shared repo-wide projects/runs/ namespace in this model.

How projects/<name>/ fits into the workflow

A harness or human operator should be able to load a project pack before drafting and get the minimum project context needed to work correctly:

1. suite-brief.md sets the suite charter, document list, scope boundaries, and cross-document rules.
2. corpus-brief.md defines the authoritative source corpus, informative material, observed-byte or runtime evidence surfaces, and section-to-source routing.
3. references.md records the authoritative, versioned reference pool plus terminology and dependency ownership.
4. draft-metadata.md provides shared draft/front-matter defaults.
5. briefs/*.md add document-specific scope, required sections, exclusions, and edge cases.
6. examples/ seeds example capture or anomaly checks when the suite benefits from them.
7. references/ is the sibling support-only staging area for local working material. The default projects/*/references/* ignore rule matches the whole directory, including references/README.md; already-tracked placeholders stay versioned, but a newly scaffolded placeholder or other staged file must be explicitly added/promoted if you want it tracked.
8. runs/README.md preserves the pack-local run-root shape so every pack has a documented place for repo-local executions.

That layering lets the workflow stay reusable while each pack remains small, explicit, and project-authored.

Pack-local runs/ area

Each pack owns its own runs/ subtree. The tracked projects/<name>/runs/README.md file is a placeholder and orientation note, not a generated run.

Use one dedicated subdirectory per run:

projects/<name>/runs/
├── README.md
└── <run-id>/
    ├── public/
    ├── evidence/
    ├── gates/
    └── logs/            # optional

Placement rules:

• Reusable pack inputs live under projects/<name>/.
• Per-run outputs and intermediate artifacts live under projects/<name>/runs/<run-id>/.
• Keep the public/evidence split inside every run directory; do not collapse them into one mixed artifact area.
• Treat run directories as run-owned workspaces: stages may create, overwrite, and retain files there without changing reusable pack content.
• Do not treat the bare runs/ directory as the run root; the run root is the per-execution <run-id>/ child.

Versioned ignore policy for run artifacts and staged references

The repo's versioned Fossil ignore policy lives in .fossil-settings/ignore-glob.

It intentionally covers two project-pack conventions:

• projects/*/runs/* for pack-local run-owned output trees
• projects/*/references/* for sibling support-only staged material under each pack's references/ directory

That keeps generated run artifacts and newly added staged support material out of version control by default while still preserving already-tracked placeholders that explain each directory's purpose, such as projects/<name>/runs/README.md and projects/<name>/references/README.md. Because projects/*/references/* also matches references/README.md, a newly created pack's placeholder must be explicitly added/promoted if you want it versioned.

Recommended pack layout

A complete pack will usually look like this:

projects/
└── <name>/
    ├── README.md
    ├── suite-brief.md
    ├── corpus-brief.md
    ├── references.md
    ├── draft-metadata.md
    ├── briefs/
    │   ├── <doc-a>.md
    │   └── <doc-b>.md
    ├── examples/
    │   └── <seed-or-example-file>.md
    ├── references/
    │   ├── README.md
    │   └── <ignored staged support files>
    └── runs/
        ├── README.md
        └── <run-id>/
            ├── public/
            ├── evidence/
            ├── gates/
            └── logs/            # optional

Not every pack needs the same number of briefs or example files, but the top-level documents should exist so the workflow has a stable place to find each kind of project context.

What each pack file does

README.md

Pack-local orientation. Explain the suite or document family, summarize the pack contents, and state any pack-specific boundaries that a new contributor should know before loading the detailed briefs.

corpus-brief.md

The source-corpus contract.

Use it to answer:

• What implementation, specification, repository, archive, observed-byte corpus, or runtime surface is authoritative?
• What material is only informative?
• When sources disagree, which surface wins?
• Which source areas govern which draft sections?
• What evidence shapes are acceptable for normative claims?

This file should make it hard for a drafter to confuse orientation material with source authority.

references.md

The curated authoritative reference, terminology, and dependency map for the pack.

Use it to record:

• the normative reference pool,
• the informative reference pool,
• internal document dependencies,
• terminology ownership,
• citation hygiene notes.

This file is canonical for the pack's references and vocabulary relationships. If a local staged note or copied excerpt disagrees with references.md, the staged file loses.

references/ staged support material

A local workbench for support-only material such as copied source excerpts, manifests, API snapshots, reference bundles, scrape output, or temporary comparison notes.

Important distinction:

• references.md is the authoritative, versioned curated pack document.
• references/README.md is the placeholder boundary note when it is already tracked; the default projects/*/references/* glob matches it too, so a newly created pack's placeholder must be explicitly added/promoted if you want it versioned.
• other files under references/ are ignored by default support material for local work unless you explicitly add/promote them.

Staged files can help a run, but they are not the canonical statement of project references, terminology, or scope. Keep them ignored rather than canonical whenever they are copied from elsewhere, bulky, transient, or only useful as local evidence-gathering aids.

suite-brief.md

The suite charter.

Use it to define:

• intended RFC documents,
• implementability or interoperability goals,
• cross-document structure,
• suite-wide constraints,
• deliverable boundaries,
• editorial bias that applies across the suite.

If the pack covers one document instead of a suite, this file can still state the charter and non-goals for that single deliverable.

draft-metadata.md

Shared front-matter and draft defaults.

Use it for items such as:

• title defaults,
• intended status or category,
• deliverable forms,
• abstract anchors,
• authorship/provenance boundaries,
• document-specific front-matter defaults.

Keep workflow-neutral mechanics out of this file. It should say what the project wants in draft metadata, not how a harness should build or render drafts.

briefs/*.md

Document-specific drafting briefs.

Each file under briefs/ should cover one target RFC or related deliverable and state:

• exact scope,
• required sections and capabilities,
• exclusions,
• cross-references it depends on,
• tricky edge cases or review traps,
• anything that must be preserved for clean-room implementability.

These briefs are where project context becomes concrete for one document.

examples/

Optional example seeds, anomaly probes, observed-byte notes, or example-capture checklists.

Use this directory when the project benefits from explicit reminders about:

• examples that must come from implementation output,
• rendered-example traps,
• anomalies that require confirmation before promotion into public text,
• scenarios that reviewers should re-check.

Treat these files as review aids. They are not a substitute for the normative source corpus.

runs/README.md

Tracked placeholder and local orientation for pack-owned run roots.

Use it to record:

• that repo-local executions for this pack live under projects/<name>/runs/<run-id>/,
• that each run keeps the standard public/, evidence/, gates/, and optional logs/ split,
• and that the file exists even before any actual run directories are created.

This file documents the shape without turning generated run output into canonical pack content.

Building project-specific reference and context material

A good pack does not merely list files. It explains which materials matter and why. The easiest way to get there is to build the pack in the following order.

1. Identify the authoritative source corpus

Decide what the workflow is actually specifying.

Examples:

• implementation source files,
• a reference repository or dataset,
• protocol traces or observed bytes,
• standards documents that define the canonical behavior,
• runtime inspection surfaces or official exported artifacts.

Name the authoritative corpus in corpus-brief.md, and be explicit about any boundary such as "implementation wins over lagging prose" or "spec text wins over convenience tooling output."

2. Collect normative and informative references separately

Do not blur references with equal weight.

• Normative references are required for a correct reading or interoperable implementation.
• Informative references help orientation, history, background, examples, or non-binding explanation.

Record both pools in references.md. Keep the list curated: include what the suite actually needs, not every adjacent document you found.

3. Map terminology ownership and document dependencies

If the pack covers multiple RFCs, decide which document owns each important concept.

Record in references.md:

• which document defines each core term,
• which documents depend on other documents,
• where cross-references should replace duplicated explanations.

This prevents three common failures: duplicated vocabulary, inconsistent definitions, and documents that quietly smuggle in dependencies they never name.

4. Stage support-only material under references/

When a project needs local working material beyond the canonical pack docs, place it under references/.

Typical staged items:

• copied source excerpts,
• manifests or sample payloads,
• reference snapshots,
• scrape/export results,
• temporary manifests of where evidence lives,
• local notes that help source scouting.

These files support the workflow; they do not define it. If a staged file becomes stable, reusable, and authoritative, promote its conclusions into corpus-brief.md, references.md, or another pack document rather than treating the staged file itself as the lasting source of truth.

5. Keep staged source files ignored rather than canonical

Copied source files, bulky exports, and local support bundles should normally be ignored from version control rather than checked in as the authoritative pack content.

Recommended practice:

• keep references/README.md checked in when it is already tracked, and explicitly add/promote a new pack's placeholder because the default glob matches it too,
• keep transient staged material under references/,
• rely on the repo's default projects/*/references/* ignore convention for newly added staged files there,
• promote only the stable conclusions into the canonical pack docs.

That keeps the repository small and the pack legible while still giving local authors a place to collect working evidence.

Authoring guidance

• Keep pack docs source-agnostic enough to be reusable, but concrete enough that a drafter knows exactly where authority lives.
• Prefer explicit boundaries over implicit culture. Write down what is out of scope.
• Use the pack to document project knowledge, not harness behavior.
• If the pack covers multiple documents, centralize shared facts in the top-level pack docs and keep briefs/*.md focused on per-document differences.
• If a fact matters to more than one brief, put it in suite-brief.md, corpus-brief.md, references.md, or draft-metadata.md instead of duplicating it.
• Put generated drafts, evidence packets, gate/status files, and optional logs under projects/<name>/runs/<run-id>/, not in a shared repo-level runs area and not in the reusable pack root.

Using the scaffold prompt

PROMPT-GENERATE-PROJECT-PACK.md is the reusable harness prompt template for creating a new projects/<name>/ skeleton. Fill in the project-specific inputs, ask your harness to scaffold the pack, then review the generated pack against this README:

• Is authority clearly separated from support-only staging?
• Do the top-level docs say what governs the project?
• Do the document briefs express scope and edge cases concretely?
• Does the scaffold include runs/README.md so the pack inherits the per-project run-root shape?
• Does the pack leave core/ and repo-wide workflow semantics alone?

Use projects/template-ietf/ as the reusable shape reference. It should carry the same tracked runs/README.md placeholder so cloned packs inherit the per-project run layout.

If the answer is yes, the pack is ready to support drafting work.