# Delivery planning

Browser-rendered handoff of repository-authored Markdown. Source identity: `PLANNING.md`. Links and original summaries are shown; external source content is not redistributed.

    # Delivery planning

    This plan turns the phase roadmap into bounded, reviewable delivery units. The
    default assurance boundary is the local checkout: no remote CI, hosted build or
    GitHub Pages deployment runs unless the owner explicitly requests publication.

    ## Delivery cadence

    1. Select one bounded item from [TRACKING.md](TRACKING.md).
    2. Implement it on a focused feature branch with its documentation changes.
    3. Run `make validate` locally.
    4. Open a draft pull request and record the validation evidence.
    5. Review and merge without updating GitHub Pages unless the owner has made a
       separate, explicit publication request.

    For a change confined to the declared site-document dependency graph, step 3
    may instead use `BASE_REF=origin/main make validate-documentation-overlay`.
    The checker must prove the changed paths are limited to nominated or curated
    Markdown, their generated HTML and documentation publication manifests. It
    fails closed to `make validate` for code, corpus, semantic, schema or workflow
    changes.

    Changes to `main` remain pull-request-only by project policy. Server-side
    branch protection is now active after the owner separately authorized public
    visibility on 2026-08-09. The sole-developer rule requires pull requests and
    resolved conversations but zero approving reviews or remote status checks.

    ## Lockstep documentation

    Documentation changes ship in the same pull request as the change they
    describe. The minimum update set is:

    | Change | Required documentation |
    |---|---|
    | Any bounded delivery item | `TRACKING.md` and `CHANGELOG.md` |
    | Scope, sequencing or gate | `PLANNING.md`, `ROADMAP.md` and `REPOSITORY_STATUS.md` |
    | Authoring model or validation rule | `docs/authoring.md` and `AGENTS.md` |
    | Local command or dependency | `README.md`, `AGENTS.md`, `Makefile`, `pyproject.toml` and `uv.lock` as applicable |
    | Licence or source-use decision | `LICENSE_DECISIONS.md`, `NOTICE.md`, `source/rights-decisions.v1.yaml`, domain profile and affected source/evidence records |
    | Publication state | `TRACKING.md`, `REPOSITORY_STATUS.md`, `CHANGELOG.md` and release evidence |

    The pull-request description must explain either which documents changed or
    why a listed document is unaffected. Documentation follow-up is not deferred
    to a later pull request.

    ## Static-document publication fast path

    Repository-authored Markdown under `docs/` may declare the additive
    `okf-site-document-publication.v1` frontmatter contract. The generator renders
    safe static HTML, updates the generated published-document index and records
    source and output SHA-256 identities in
    `learn/documentation-manifest.json`. Nomination never authorises deployment.

    The frozen 1,814-file corpus remains the base layer. Site documents are part of
    the additive Explore overlay, so a documentation-only change neither rebuilds
    the corpus nor modifies semantic authority. Pull requests and merges remain
    publication-free; an owner-requested deployment must still name the exact
    protected-main commit and pass the real-browser verification gate. Rendered
    documents use the existing browser-safe HTML notice for their MIT and
    attribution boundary; the owner approved a bounded correction on 17 August
    2026 after Edge blocked the first deployment's extensionless `LICENSE` route.

    ## Near-term delivery units

    The owner approved `okf-domain-profile.v1` and the three fixture contracts on
    2026-08-07. All three slices and the licensing decisions are merged. The local
    Explorer remediation rerun passed: relationship and node provenance,
    browser-safe source handoffs, and the first-class licence/notice surface are
    verified. That bounded sample proposal was superseded by the later authorized
    population-complete preview.

    The owner separately authorized exhaustive link-only reference-family
    discovery on 2026-08-07. `INVENTORY-001` is complete with 142 external records,
    120 assessed coverage cells and 12 tracked gaps. This planning asset does
    not change the sample release gates or authorize snapshots, broad leaf
    acquisition, CI or publication.

    The original sample sequence is defined in the
    [three-slice review and publication plan](docs/review-and-publication-plan.md):

    The owner superseded that proposed sample on 2026-08-08 by authorising the
    population-complete corpus as a public preview. `SCOPE-001`, `CAND-001` and
    `PUB-001` are therefore complete for the preview. The first 1,549-file
    publication completed `PAGES-001` and `VERIFY-001`. `CAND-002` now freezes the
    rich-runtime correction as 1,814 exact files from reviewed data commit
    `c38f927…`; `PAGES-002` and `VERIFY-002` remain separate exact-merge deployment
    and cache-bypassed browser gates.

    The manual Pages enablement attempt failed with GitHub HTTP 422 because the
    current plan did not support Pages for the private repository. The owner made
    the repository public on 2026-08-09 and resolved that historical blocker. The
    current manual workflow accepts an exact protected-main merge commit, verifies
    the event and checkout identities against it, and transports only hashes in the
    reviewed manifest; later commits cannot be substituted implicitly.

    The owner resolved the blocker on 2026-08-09 by authorising public visibility
    for the existing repository. Manual run `31297841419` deployed the pinned unit;
    deployment `5815993749` and exact-browser verification passed. `PAGES-001` and
    `VERIFY-001` are complete. The published population preview is not release
    grade, and publication does not close the recorded Explorer UI findings.

    For the complete-corpus track, `CORPUS-001`, `ACQPOL-001` and `POP-001` are complete.
    The owner approved 293 named families, exhaustive-authority plus representative
    and exception local coverage, GSS and applicable ODS identifiers, manual
    link-only health acquisition, regulator-first private dependencies, sector
    redress and role-based specialist review. The
    [reference gaps](research/exhaustive-reference-gap-analysis.md) now have explicit
    population-gate dispositions. Remaining boundaries concern reviewed freshness,
    complete bilingual expression, optional future automation or external reviewer
    appointments rather than missing population records.
    The 293-family, seven-facet colour projection is complete and approved for
    local evaluation; it does not claim leaf-service completeness.

    The foundation and Explorer contract are complete. The three-slice migration,
    shared authority/source infrastructure, `PACK-001` family-beginnings,
    `PACK-002` learning-and-transition, `PACK-003` work-and-money, `PACK-004`
    home/place/transport, `PACK-005` enforcement/consumer/justice, `PACK-006`
    family/health/care, `PACK-007` civic/enterprise/creativity and `PACK-008`
    mobility/later-life/death corpora are locally complete and supply the proving
    fixtures, reusable identities and repeatable domain-register renderer for the
    whole contracted population. The renderer preserves richer vertical-slice
    dossiers when a later pack accounts for those approved identities.
    The complete-corpus sequence is complete through `ASSURE-001`. The frozen local
    candidate reconciles the 293 dossiers, 104 competency questions, source links,
    provenance and six representative browser journeys. No population item remains
    active. A later release-grade track may begin only with named reviewer
    acceptance and current re-observation of applicable legal, clinical and
    high-impact operational claims. The owner has separately authorized the frozen
    population preview for publication without changing that review boundary.

    `SEM-001` completed locally on 2026-08-12. The large-corpus generator now
    projects the existing 15,810 governed relationships into one shared OKF 0.2
    plus Bundle Wiki YAML-LD contract: absolute semantic identities and predicates,
    validated local routes, direct triples, evidence-bearing reified assertions,
    authority, derivation, freshness and rights. This is an interoperability and
    authoring-boundary improvement, not a new scope, release-grade decision or
    publication authorisation. The already frozen and verified Pages preview is
    unchanged by that migration itself. The owner subsequently authorised a bounded
    publication correction: its manifest freezes the `c38f927…` rich-runtime bytes,
    and it must pass the existing exact-merge and real-browser gates before the new
    public descriptor is labelled verified.

    The local producer and checker validate every semantic assertion and its
    runtime projection against the digest-pinned shared Draft 2020-12 schema.
    Validation receipts record the schema identity, local path, digest, checked
    counts and violation count; they cannot report conformance before that pass.

    The canonical 16-file Bundle Wiki v1 profile and vendor lock are local,
    byte-exact inputs. A separate digest-bound rich runtime exposes official and
    normalised active planes through bounded gzip shards and a SHA-256 route
    locator. Every route commits to the exact count and sorted-assertion digest for
    each incident plane. The merged Explorer strict reconciler is the acceptance
    authority for these producer surfaces.

    Population-complete permits a visible `specialist_review_required` state.
    Release grade separately requires named legal, clinical or service-owner
    acceptance for affected high-impact claims.

    The authorized publication scope is the population-complete educational
    preview without a formal CPSV-AP, Open Referral, OWL or SHACL conformance claim.
    It retains all 291 specialist-review warnings and does not claim release grade,
    official-service status or personalised advice.

    ## GitHub Pages publication

    GitHub Pages is the planned publication channel, but it is not an automatic
    deployment target. Pushes, merges and pull requests must not trigger hosted
    validation or Pages updates.

    A publication request is a separate owner decision that identifies a frozen
    candidate. The owner made that request for the population preview on
    2026-08-08. The project may now enable and invoke only the manual Pages
    deployment defined by the frozen publication manifest. Promotion must
    publish the frozen candidate without rebuilding it. The exact deployed site
    must then pass real-browser identity and journey checks before any public
    bundle link is shared.

    Before publication authorization, pull requests used this statement:

    > Publication status: local validation only. GitHub Pages was not updated.
    > Publication requires an explicit owner request.

    This authorized publication pull request instead records the owner request and
    frozen candidate. A follow-up evidence pull request must record the deployment
    and browser-verification result. A failed verification remains failed and the
    public link is withheld.

    The 2026-08-09 verification passed, so the exact landing, descriptor, manifest
    and Explorer URLs recorded in the publication evidence may now be shared.

    The local 2026-08-08 UI-efficiency review also establishes two Explorer
    follow-ups before question-answering acceptance can be claimed: bounded
    handling of conversational or inflected query terms, and a life-course-domain
    browse fallback when static search returns zero results.