Verified package release

Package 0.5.1 is available. Protocol 0.2 remains provisional.

Canonical page: https://jg-plans.jesusgraterol.dev/examples/

---

# Examples

These examples use invented prose, identifiers, names, and paths. They are public protocol examples and synthetic conformance inputs, not copied project plans. Expected observations below are specified independently of the reference parser.

| Example                 | Source                                                                                                                                | Expected observations                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Small plan              | [plan.md](small/plan.md)                                                                                                              | Core fields and protocol 0.2, pending, revision 1, derived name search-feedback; AC-01 needs no milestones.                                                                                                                                                                                                                                                                      |
| Optional milestones     | [plan.md](with-milestones/plan.md), [milestones.md](with-milestones/milestones.md)                                                    | Two UUID-identified milestones: first done, second pending; overview agrees with markers; AC-01 is done and AC-02 pending.                                                                                                                                                                                                                                                       |
| Consumer extensions     | [plan.md](extensions/plan.md)                                                                                                         | Custom waiting-for-feedback status and nested project metadata remain intact; INVALID_STATUS diagnoses that custom status and criterion progress is null.                                                                                                                                                                                                                        |
| Partly deleted metadata | [plan.md](incomplete/plan.md)                                                                                                         | Markdown body remains useful; core metadata is absent, so preferred-writer conformance has findings.                                                                                                                                                                                                                                                                             |
| Orphan milestones       | [milestones.md](orphan/milestones.md)                                                                                                 | plan.md is deliberately absent; the remaining milestone is observable without recreating a plan or inferring permission.                                                                                                                                                                                                                                                         |
| Acceptance criteria     | [plan.md](criteria/plan.md), [milestones.md](criteria/milestones.md), [expected.json](criteria/expected.json)                         | A protocol 0.2 plan with three criteria, a medium priority, the one repository it changes, and the explicit codes 4100 and SEARCH_FILTER_INVALID it adds; derived name search-feedback-criteria. AC-01 is done through milestone 1; AC-02 and AC-03 are in progress through milestone 2. The fenced sample and the prose mention of AC-01 define nothing. The documents conform. |
| Invalid criteria        | [plan.md](criteria-invalid/plan.md), [milestones.md](criteria-invalid/milestones.md), [expected.json](criteria-invalid/expected.json) | A protocol 0.2 plan with five findings: the status "blocked", a second AC-01, the invalid ID AC-2, AC-03 covered by no milestone, and milestone 1 naming the undefined AC-07. AC-01 stays pending and AC-03 has no progress. The documents don't conform.                                                                                                                        |

Readers do not require every example to conform. The extensions example deliberately has a nonconforming custom status. The incomplete and orphan cases demonstrate useful inspection after ordinary user edits/deletion. The overview is optional and never the source of authority over marker status.

The two criteria examples also state their expected results as expected.json: whether the documents conform, the derived name, the priority, repositories, and error codes a plan declares, each criterion's ID, text, covering milestones and progress, and each diagnostic's code, document and line. Diagnostics are listed by document and line; readers may report them in another order.

The [protocol](../protocol/0.2/README.md) owns the format. These files can be read, copied, and edited directly. The [API](../api/README.md) and [CLI](../cli/README.md) explain reference operations.

## Runnable library example

[library.mjs](library.mjs) creates a plan with optional milestones, awaits a targeted update, inspects it, and performs an optional check. It prints a small JSON summary and removes only its own temporary root in finally. Run it with Node.js from a built checkout, or from its physical location inside an installed jg-plans package. The packed-consumer test executes this exact shipped file.