Repository Instructions

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

# Repository Instructions

This repository publishes **A Life in the UK**, a citizen-centred Open
Knowledge Format bundle about public services, rights, responsibilities and
life events from before birth to death and bereavement.

## Working rules

- Treat Markdown and files under `source/` as authored source of truth.
- Keep links as browser-compatible Markdown links. Do not use Obsidian-only
  wikilinks.
- Every non-index OKF concept must declare non-empty `type`, `title` and
  `description` frontmatter.
- Preserve official source identity, jurisdiction, observation time,
  derivation and limitations. Similar labels never establish identity.
- Distinguish `official`, `normalized`, `inferred` and `editorial-example`
  assertions. Never present generated relationships as official claims.
- Give each implemented slice semantic regression checks for exact authorities,
  jurisdictions, approved sources, assertion status and required journey links.
- Do not encode real personal data. Personas and service episodes must be
  synthetic and clearly labelled.
- Do not turn the bundle into a personalised eligibility, medical or legal
  decision engine. Link readers to the current authoritative service.
- Model UK-wide, England, Scotland, Wales, Northern Ireland and local variants
  explicitly. A GOV.UK route is not evidence that one process applies
  uniformly across all four nations.
- Do not edit `generated/`, `large/`, `okf-bundle.json`, `okf-explorer.json`
  or release evidence by hand; rebuild them from authored inputs.
- Do not add `.DS_Store`, Word lock files, `_site/`, virtual environments,
  caches or temporary output to Git.
- Preserve unrelated work and use focused feature branches and pull requests
  after the reviewed initialization commit.
- Keep implementation and its planning, tracking, status, changelog and
  authoring documentation in the same pull request, following `PLANNING.md`.
- Keep remote CI disabled unless the owner explicitly changes the local-only
  evaluation policy or requests publication.
- Never create remotes, push, publish, enable CI or spend money implicitly.
- Apply MIT only to repository-authored code, documentation and ontology
  terms. Source content remains linked and summarized, not redistributed;
  enforce the dated decisions in `source/rights-decisions.v1.yaml`.
- Implement the 293-family population only in the eight governed packs in
  `profiles/life-course-population-contract.v1.yaml`. Every family must remain
  mapped to an enclosing process, and population completion must stay separate
  from specialist-reviewed release grade.

## Required checks

If OKF Markdown changes, run:

```sh
uv run --locked python scripts/render_life_course_packs.py
uv run --locked python scripts/render_life_course_packs.py --check
uv run --locked python scripts/build_browser_handoff.py
uv run --locked python scripts/build_browser_handoff.py --check
uv run --locked python scripts/build_okf_bundle.py
uv run --locked python scripts/build_okf_bundle.py --check
uv run --locked python scripts/check_okf.py
uv run --locked python scripts/check_contracts.py
uv run --locked python scripts/check_sources.py
uv run --locked python scripts/check_inventory.py
uv run --locked python scripts/check_service_denominator.py
uv run --locked python scripts/check_corpus_policy.py
uv run --locked python scripts/check_population_contract.py
uv run --locked python scripts/check_domain_registers.py
uv run --locked python scripts/check_life_course_dossiers.py
uv run --locked python scripts/check_authority_registry.py
uv run --locked python scripts/check_rights.py
uv run --locked python scripts/build_large_corpus.py
uv run --locked python scripts/build_large_corpus.py --check
uv run --locked python scripts/check_large_projection.py
uv run --locked python scripts/check_search_acceptance.py
uv run --locked python scripts/build_population_assurance.py
uv run --locked python scripts/build_population_assurance.py --check
uv run --locked python scripts/check_population_assurance.py
uv run --locked python scripts/prepare_pages_publication.py
uv run --locked python -m unittest discover -s tests
```

A change confined to the declared static-document publication graph may use:

```sh
BASE_REF=origin/main make validate-documentation-overlay
```

The dependency-graph check must pass before this replaces `make validate`. It
permits only curated or frontmatter-nominated Markdown, their generated HTML,
the documentation manifest and the additive Explore manifest. Any other path
fails closed and requires the full checks above. This shortcut never rebuilds
or republishes corpus and semantic authority.

Before any publication change, also validate the approved domain profile,
source inventory, rights decisions, evaluation journeys and frozen candidate.

Never provide a public bundle URL until that exact deployed URL passes a
real-browser identity and journey check. A failed public verification is
reported as failed and the link remains labelled unverified; it does not
silently trigger a release rebuild.

Local checks are the default and only evaluation environment. Pull requests,
pushes and merges must not trigger remote CI or GitHub Pages updates. After
every pull request, state that GitHub Pages was not updated and requires an
explicit owner publication request, unless that pull request records such a
request and its deployment and browser-verification evidence.

## Modelling priority

Implement three vertical slices before expanding the corpus:

1. missed rubbish collection;
2. learning to drive through a speeding or parking exception; and
3. death and bereavement through Tell Us Once and estate administration.

These slices must exercise ordinary paths, exceptions, evidence, time,
jurisdiction, authority, required private-sector dependencies and redress.

The three slices are complete. The owner authorized staged implementation of
all 293 families on 2026-08-08. New families follow
`life-course-family.v1`, the 48-process navigation denominator and the existing
link-only, jurisdiction, privacy, review and publication boundaries.

Author each population pack in the compact domain registers under
`source/domain-registers/`, then run `render_life_course_packs.py`. The renderer
owns the corresponding dossier, service-family narrative and domain narrative;
do not hand-edit those rendered files. Every pack contributes at least 13
natural-language competency questions and body-free link receipts before its
local review can pass. When a pack includes one of the six richer vertical
slices, mark that family `preserve_existing: true`; validation requires the
existing dossier and narrative and the renderer must not replace them.

The eight packs and local population-assurance gate are complete. Treat
`evaluation/candidates/population-complete-candidate.v1.yaml` as the authored
freeze boundary and `generated/assurance/` as rebuild-only evidence. Population
completion does not imply specialist-reviewed release grade or authorize
publication.

The owner authorized a public population-complete preview on 2026-08-08. The
manual-only Pages workflow may promote only the files and hashes in
`publication/pages-file-manifest.json`; it must not rebuild the corpus during
deployment. Keep the non-release-grade and specialist-review warnings visible.
Do not change repository visibility to obtain Pages without a separate owner
decision. Record the exact deployment and real-browser result before labelling
or sharing the public URL as verified.

<!-- okf-semantic-contract:start -->
## OKF 0.2 and semantic relationship contract

- Read `okf.semantic.json` before changing Markdown, ontology, semantic, relationship, bundle, or Reader-facing files. It records this repository's authored inputs, generated outputs, exact build/check commands, delivery mode, and current migration limitations.
- Keep the intentionally small OKF 0.2 Markdown core separate from the additive Bundle Wiki YAML-LD profile. Unknown OKF fields remain forward-compatible; profile requirements must never be described as universal OKF core.
- Treat the declared YAML-LD/JSON-LD graph or authored Markdown YAML-LD frontmatter as semantic authority. Explorer JSON, shards, adjacency, registries, checksums and sites are generated projections and must not be hand-edited.
- Every new material directed relationship must retain a stable assertion ID, validated local runtime `source` and `target`, absolute `source_iri` and `target_iri`, an absolute predicate IRI, a governed relationship kind, preferred and inverse labels, assertion status and scope, authority, derivation, observation time, evidence and rights. Semantic reification maps the same identities to RDF subject and object. Confidence never upgrades authority.
- Keep the direct semantic triple and its evidence-bearing `okf:RelationshipAssertion` synchronized, or generate both deterministically from one assertion source. Do not infer domain predicates from Markdown links.
- Validate every generated semantic assertion—not merely a sample—against the pinned local shared Draft 2020-12 schema before writing a conformant receipt. Cross-repository sampling is a regression signal, not a substitute for producer validation.
- A repository that claims the canonical Bundle Wiki v1 profile URI must vendor all 16 Explorer v0.6.0 profile files byte for byte with the adjacent `profiles/bundle-wiki/v1.vendor-lock.json`. Never edit that mirror locally. From a sibling repository, use `uv run --project ../okf-explorer --locked python ../okf-explorer/scripts/reconcile_okf_repositories.py --repo . --sync-profile` to install missing canonical files; add `--replace-profile` only after reviewing the divergent or extra files it reports. A relationship schema that retains the canonical `$id` must have the canonical bytes; a deliberately different schema must use its own absolute `$id`. Direct readers to the canonical published profile at `https://chris-page-gov.github.io/okf-explorer/profile/bundle-wiki/v1/` for explanatory material because the opaque vendored `index.md` retains Explorer-relative documentation links.
- Canonicalize authority, evidence/resource and rights source links as credential-free HTTP(S) URLs. Percent-encode query values and reject missing hosts, literal whitespace, quotes, malformed escapes, credentials, unsafe delimiters, non-web schemes and ports outside 1–65535 before generating projections.
- For a large sharded rich graph, publish a digest-bound `relationship_runtime` manifest and SHA-256 route locator. Each route must commit per plane to its exact incident assertion count and sorted assertion-ID digest; keep historical/rejected planes out of `default_planes` and obey the Reader's aggregate chunk, row, compressed-byte and retained-text ceilings.
- Resolve only pinned local contexts during builds. The Reader parses bounded YAML-LD safely but does not fetch or reason over arbitrary remote contexts; it consumes explicit route-bearing nodes and assertion rows.
- Preserve official, normalized, inferred, model-derived, synthetic and historical planes. Never collapse presentation grouping, similarity or route adjacency into semantic identity.
- Run any declared `tooling.setup` commands before the build/check commands when the repository environment is absent. Then run `uv run --project ../okf-explorer --locked python ../okf-explorer/scripts/reconcile_okf_repositories.py --repo .` after semantic changes when the sibling Explorer checkout is available, followed by every local command in `okf.semantic.json` and this repository's existing validation/release guidance.
<!-- okf-semantic-contract:end -->