# Public project status feed: reference kit

A minimal, working example of the workflow in the FactSmith article
"No news is still news"
(https://www.factsmith.co.za/insights/public-project-status-feed/).

One record per project per update cycle, appended to a hash-chained log.
If nobody files an update by the cut-off, the system records
"no update received" itself. Missed updates, passed target dates and stale
site checks become flags, routed up the owner's own escalation ladder.

**All sample data is fictional.** The projects, departments and municipality
in `sample/` do not exist.

## What is in this download, and what is not

This kit is the open part: the format, the drafting prompt, and a worked
example of the inputs and the published outputs. That is everything a
department, a municipality or their IT supplier needs to build and adapt
their own version.

The engine that runs the daily build (validation, the automatic
"no update received" record, flags and the tamper check) is not in this
download. For the source repository, contact FactSmith:
https://www.factsmith.co.za/contact/

| File | What it is |
|---|---|
| `schema.json` | The format of one status record (JSON Schema). |
| `prompt.md` | Prompt for an AI assistant to draft a record from a site report. The AI drafts; a person approves. |
| `sample/projects.json` | Settings: projects, update rhythm, who may comment, escalation ladders. |
| `sample/drafts/` | Approved drafts, as an official would file them, plus one comment from a local municipality. |
| `sample/log.jsonl` | The history, one record per line, never edited. |
| `sample/public/` | What gets published: `index.json`, `latest/<project>.json` and `.txt`, `feed.xml` (Atom), `status.csv`, `flags.json`. |

## Rules any version should enforce

- Unknown fields, wrong types and over-long text are rejected.
- `update` and `correction` need a status, a summary and at least one source.
- A changed `target_date` needs a `target_change_reason`.
- Records cannot be back-dated; mistakes are fixed with a `correction` record.
- Nobody can file `no_update_received` by hand; only the daily build writes
  it, and it never repeats an old status as current.
- A `comment` comes from a body that does not own the project, such as the
  local municipality under a provincial or national project. It is published
  next to the owner's record but never changes the status, never counts as
  the owner's update and never clears a flag.
- Each record carries a hash of the one before, so a quiet edit to history
  shows up.

## Licence

MIT (see `LICENSE.txt`). Use it, change it, and ship it in your own systems,
including commercial ones.

## Known limits

- Calendar days only (no public holidays).
- No login or approval screen in the reference engine. A real pilot puts
  this behind the organisation's own sign-in and keeps the approver's name in
  the internal audit log.
- A "no change" record is the official's word, not proof of progress; the
  `NOT_VERIFIED_RECENTLY` flag limits how long that word can stand alone.