# Project Packs A project pack is the reusable project-specific layer of this RFC workflow. It exists **after** the pre-pack suite-discovery workflow has fixed the RFC boundaries and turned them into scaffold-ready inputs. The repo-wide workflow defines neutral mechanics in `core/`, repo-level prompts, reviewer roles, and toolchain behavior. A pack under `projects//` 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//` holds reusable project-pack inputs that define what the workflow should run against. - `projects//runs//` 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//` says **what this project is about** and **which source material governs it**. - `projects//runs//` says **what happened during one concrete run**. There is no shared repo-wide `projects/runs/` namespace in this model. ## How `projects//` fits into the workflow Project packs sit between the discovery workflow and the drafting workflow: 1. `suite-discovery.contract.yaml` + `prompts/discover-rfc-suite-shape.md` inspect the real corpus and decide the smallest clean suite. 2. The resulting `pack-scaffold-inputs` block feeds `PROMPT-GENERATE-PROJECT-PACK.md`. 3. The generated pack under `projects//` preserves that suite decision as reusable project input for later drafting runs. 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 inherited from discovery. 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 downstream of a deliberate suite decision rather than a one-shot scaffold guess. ## Pack-local `runs/` area Each pack owns its own `runs/` subtree. The tracked `projects//runs/README.md` file is a placeholder and orientation note, not a generated run. Use one dedicated subdirectory per run: ```text projects//runs/ ├── README.md └── / ├── public/ ├── evidence/ ├── gates/ └── logs/ # optional ``` Placement rules: - Reusable pack inputs live under `projects//`. - Per-run outputs and intermediate artifacts live under `projects//runs//`. - 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 `/` 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//runs/README.md` and `projects//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: ```text projects/ └── / ├── README.md ├── suite-brief.md ├── corpus-brief.md ├── references.md ├── draft-metadata.md ├── briefs/ │ ├── .md │ └── .md ├── examples/ │ └── .md ├── references/ │ ├── README.md │ └── └── runs/ ├── README.md └── / ├── 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//runs//`, - 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//runs//`, not in a shared repo-level runs area and not in the reusable pack root. ## Using the scaffold prompts If the suite boundaries are still fuzzy, run the pre-pack discovery workflow first: 1. Read `../suite-discovery.contract.yaml` and `../schemas/suite-discovery-contract.schema.json`. 2. Load the discovery templates under `../templates/`. 3. Run `../prompts/discover-rfc-suite-shape.md` against the real source corpus. Its final `pack-scaffold-inputs` block should name the candidate documents, cross-document boundaries, dependency rules, clean-room capabilities, and explicit non-RFC topics before you scaffold anything. Then use `PROMPT-GENERATE-PROJECT-PACK.md` to create the new `projects//` skeleton. Fill it from the discovery output, 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 preserve the discovery-owned suite boundaries instead of re-inventing them? - Does the scaffold include `runs/README.md` so the pack inherits the per-project run-root shape? - Does the pack leave `core/`, the discovery contract, and the drafting contract 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.