# WTF-P portable project protocol v1

This directory defines the host-neutral data model stored by a WTF-P project. Runtime adapters may render friendly Markdown views, but the JSON records defined here are the interoperable source of truth.

## Logical resources

Logical URIs identify project data without exposing a workstation path or a runtime-specific directory:

| Logical URI | Conventional project-relative location | Record |
|---|---|---|
| `project://manifest` | `.planning/project.json` | Project identity and artifact index |
| `project://config` | `.planning/config.json` | User-visible workflow policy |
| `project://state` | `.planning/state.json` | Current lifecycle and progress |
| `project://decisions` | `.planning/decisions.json` | Locked, deferred, and discretionary decisions |
| `project://structure/outline` | `.planning/structure/outline.json` | Argument and section structure |
| `project://sections/{section}` | `.planning/sections/{section}/section.json` | Section status, claims, and artifact links |
| `project://sources/{source}` | `.planning/sources/{source}.json` | Bibliographic or data-source identity |
| `project://evidence/{evidence}` | `.planning/evidence/{evidence}.json` | Claim-level interpretation of a source |
| `project://checkpoints/{checkpoint}` | `.planning/checkpoints/{checkpoint}.json` | Orchestrator-managed interaction gate |
| `project://validations/{validation}` | `.planning/validations/{validation}.json` | Read-only verification result |

The conventional locations are adapter mappings, not absolute paths embedded in records. Adapters must reject URI traversal segments and must not resolve a logical URI outside the project root.

## Authored artifact resources

The JSON records above are the interoperable source of truth, while research and manuscript artifacts retain the format in which an author works. These logical URIs identify the portable artifact vocabulary used by workflows:

| Logical URI pattern | Conventional project-relative location | Purpose |
|---|---|---|
| `project://materials/{artifact}` | author-selected path inside the project root | Existing notes, data, figures, bibliographies, or prior drafts discovered during mapping |
| `project://paper/{artifact}` | `paper/{artifact}` | Manuscript source, normally Markdown, LaTeX, or another author-selected text format |
| `project://sections/{section}/context` | `.planning/sections/{section}/context.md` | Author-approved section guidance |
| `project://sections/{section}/research` | `.planning/sections/{section}/research.md` | Evidence-grounded research synthesis |
| `project://sections/{section}/plans/{plan}` | `.planning/sections/{section}/plans/{plan}.md` | Immutable executable writing or revision plan |
| `project://sections/{section}/reviews/{review}` | `.planning/sections/{section}/reviews/{review}.md` | Detailed review notes linked to a validation record |
| `project://sections/{section}/summary` | `.planning/sections/{section}/summary.md` | Concise handoff from completed section work |
| `project://sections/{section}/handoff` | `.planning/sections/{section}/handoff.md` | Narrative session-continuity note linked to a checkpoint |
| `project://deliverables/{kind}/{artifact}` | `deliverables/{kind}/{artifact}` | Slides, posters, LaTeX exports, and other rendered outputs |
| `project://archives/{archive}/{artifact}` | `.planning/archives/{archive}/{artifact}` | Immutable milestone snapshot and delivery manifest |

`project://archives/checkpoints/{checkpoint}` stores an immutable, hashed portable-state snapshot. `project://archives/recovery/{artifact}` stores a verified pre-mutation recovery copy for an approved restore or major edit. Neither archive kind is implemented with Git state: adapters must not stage, commit, tag, check out, reset, or move a branch to create or restore one.

`{section}`, `{source}`, `{evidence}`, and other placeholders stand for one path-safe stable identifier, not an arbitrary path. `{artifact}` may contain contained path segments when an action deliberately selects a file. Contracts may use `*` or `**` only to declare a bounded set; persisted records always contain concrete logical URIs.

## Workflow execution rules

- Resolve logical URIs through the active adapter. A workflow must never send a literal logical URI to a shell command or reconstruct an adapter's physical path.
- Read and validate the JSON record before mutation. Preserve stable identifiers, reject unknown fields, advance `revision` and timestamps where the schema requires them, and replace a record atomically.
- Keep the manifest's `materials`, `manuscripts`, `deliverables`, and `archives` indexes synchronized with authored artifacts. Section records retain immutable plan/review history arrays, their current handoff, and linked checkpoints instead of hiding those relationships in prose.
- Keep authored prose, context, research, plans, reviews, summaries, handoffs, and deliverables in their native format. Link those artifacts from the relevant record instead of treating a Markdown control document as project state.
- Reconcile state from records and verified artifacts. Never infer lifecycle status from legacy `PROJECT.md`, `ROADMAP.md`, or `STATE.md` files.
- A workflow must not initialize a repository, create or switch branches, stage, commit, merge, push, or publish as an incidental side effect. An action that declares a `vcs.*` or external effect must preview the exact operation and cross a separate user gate immediately before that effect. Otherwise it may return only a non-executed handoff.

## Invariants

- Every record carries a versioned `schema` discriminator and a stable project or record identifier.
- Unknown object properties are rejected. Protocol evolution uses a new schema version instead of silently accepting misspelled fields.
- Source records establish identity and provenance. Evidence records separately state what a source supports, contradicts, or contextualizes.
- Author-controlled decisions are explicit data. Locked decisions cannot be silently weakened; deferred decisions stay out of active work.
- Interaction checkpoints record input requested by a workflow, but specialists do not conduct interaction themselves.
- A `state-snapshot` checkpoint is non-blocking and points to an immutable archive plus the logical URI, revision, and SHA-256 digest of every captured resource. Restores require a separate gate and a verified recovery archive.
- Validation records report findings and never imply that a mutation was applied.
- Timestamps use RFC 3339 date-time strings. Dates use ISO 8601 calendar dates.

`templates/` contains minimal valid examples and `schemas/` contains JSON Schema 2020-12 contracts. The examples are safe fixtures for adapter and conformance tests; they are not prose-writing templates.