Playbook Catalog — Full Detail for Every Playbook

Scope: the complete catalog of Jijibora playbooks — purpose, who uses each one, inputs, flow, guard rails, evidence, rollout, and low-resource behavior — in one consistent format per playbook. Status: as of 2026-11-09. Blueprint sources: every brief below is quoted from its fragment source; evaluate/invent the rest from the fragment and its family README. Fragment sources are linked at the end of each card.

How to read this catalog

Every playbook card uses the same five headings, so a reader can compare any two playbooks directly:

1. Use & purpose — what city problem it solves, in plain words.
2. Who uses it — the people and roles who operate it (resident, technician, ward officer, administrator, auditor).
3. Flow — the numbered steps it follows, from trigger to closed evidence.
4. Guard rails — what it can never do (no auto-fine, no auto-certify, no auto-publish, no settlement from optimizers, and so on).
5. Evidence & rollout — what audit it leaves, its version, and whether it ships Soft-first or LIVE.

Master index (40 fragments)

The table groups by kind; each card below is one playbook. Sourcing/solving/optimizing participation per playbook is summarised in the optimization capability design.

Family 1 — Reflex rules (real-time reactions)

Reflex rules fire on events (building state deltas, sensor crossings, ticket intakes, rounds ticks). They are Tier-1: bounded depth, terminal-only actuation, configuration is data (values only) — endpoints consume config, they do not hardcode behavior.

1.1 Building reflex — "the building reacts to its own state"

• Use & purpose: when a space entity's state changes (a building, a drain, a road segment), the reflex evaluates registered rules and actuates the next step — paging the right desk, opening a case, or dispatching a crew. It is the platform's spinal-cord reflex for physical assets.
• Who uses it: facility managers and maintenance desks consume its outputs; city administrators enable/disable it per building; auditors read its fired notices.
• Flow:

1. A space-entity state delta arrives on the criteria plane.
2. The reflex evaluates matching rules (kind: criteria, engine: tgc), bounded by max_depth.
3. A fired notice carries causation (which event triggered it) to the next stage.
4. Only terminal stages may actuate (dispatch, notify, open case). Non-terminal stages only transform evidence.
5. The actuation is recorded as a PoCE step; the reflex chain terminates.

• Guard rails: SurrealDB is the system of record only — live evaluation runs in Camel/Kestra, never as embedded SQL in route handlers. Reflexes never invent thresholds; every number comes from a governed lookup. No fine, payout, or closure from a reflex alone.
• Evidence & rollout: fired notices + PoCE steps; version 1.0.0 via fragment building-reflex.rule.json. Ships Soft: rules exist as data, enablement is per-scope opt-in.
• Low-resource behavior: events arrive through the same NATS bus regardless of the reporter's channel (walk-in desk, USSD, WhatsApp, API). No smartphone dependency for the triggered play — only for staff consoles.
• Worked example: a market building's water storage drops below its declared band → reflex pages the facility desk with the causation chain → desk opens a maintenance case → technician verifies on site.

_Source: building-reflex.rule.json._

1.2 Community sourcing — "find the right hands for the job"

• Use & purpose: turns a staffing requirement (a crew, an inspector, a technician) into offers from qualified providers, shortlists them, and binds one — so the city never assigns work by guesswork. It is the sourcing bus the other playbooks wire into.
• Who uses it: dispatch desks (maintenance, inspections, SOS), procurement officers; citizens see only the outcome (a named crew), never the match mechanics.
• Flow:

1. A requirement is recorded (skill, location window, crew size).
2. The sourcing plane qualifies candidates against declared criteria (TGC) and solves the assignment (solver-gateway branch_and_bound 1.4.0).
3. Offers arrive as deltas; the shortlist ranks qualified providers.
4. A bind decision opens the assignment; infeasibility returns a terminal "infeasible" verdict instead of a fake match.

• Guard rails: qualification is never evaded — an unqualified provider cannot be shortlisted even if nearer or cheaper. Solver verdicts are gates, not approvals. No match means no assignment; the system says so explicitly.
• Evidence & rollout: requirement records, offer deltas, shortlist, bind/infeasible verdicts. Version 1.0.0 via community-sourcing.rule.json. Soft by default; promotes to a Flink job only on fan-out per the architecture decision.
• Low-resource behavior: providers subscribe by phone/USSD; offers do not require a smartphone app.
• Worked example: a ward needs two plumbers by Thursday → three qualified providers offer → the solver binds the pair that covers both sites at least cost → both are notified with window and materials.

_Source: community-sourcing.rule.json._

1.3 Geofence / SCE — "the city notices crossings"

• Use & purpose: reacts to proximity events — a vehicle, crew, or sensor crossing a registered boundary of a road/drain/asset — by evaluating the crossing against rules and notifying or opening a case.
• Who uses it: traffic and asset managers; ward officers; flood/urban-safety desks.
• Flow:

1. Boundary-crossing events arrive (sensing routes/SCE telemetry).
2. The reflex evaluates the predicate against mplace.predicate.v1 family subjects.
3. Terminal action: notify the owner desk or open a pattern case.

• Guard rails: subjects, predicates and thresholds are UNKNOWN-marked in the read set — they are declared values, never invented per-region. Partner channels never carry private payloads (scrubbed at publish).
• Evidence & rollout: crossing events + fired notices with provenance ids. Version 1.0.0 via geofence-sce.rule.json. Soft.
• Low-resource behavior: the sensing side is infrastructure (beacons, gateways); residents need no device.
• Worked example: a waste truck enters a restricted lane during school hours → crossing event → reflex notifies the traffic desk with the lane, time, and vehicle provenance.

_Source: geofence-sce.rule.json._

1.4 Mars ICE dispatch (SOS) — "emergency response, governed"

• Use & purpose: the emergency (SOS) signal for multi-agency response — water, power, road, hospital, flood. It converts a distress signal into a governed dispatch with proof of correct execution, so a response is never claimed without evidence.
• Who uses it: emergency desks, agency responders, city incident commanders; citizens trigger it through any channel.
• Flow:

1. SOS governance signal arrives.
2. Kestra dispatch + Camel actuation route the response; each step is PoCE-recorded.
3. Field completion produces the result claim; the session is sealed with a receipt.
4. Post-incident review consumes the sealed evidence.

• Guard rails: no dispatch without a deal/fill; PoCE failures never block the dispatch but are always recorded; no response is reported successful without field evidence.
• Evidence & rollout: PoCE session + result claims + sealed receipts. Version 1.0.0 via mars-ice-dispatch.rule.json. LIVE only after SOS governance review; until then Soft with rehearsal mode.
• Low-resource behavior: USSD/WhatsApp/SMS triggers; dispatch notices in EN/SW/FR narration packs; mobile-money-first for any responder payment, never cash-handled by playbooks.
• Worked example: a burst water main → SOS signal → engineering desk dispatched → photo+GPS completion → sealed PoCE receipt → the ward digest shows it tomorrow.

_Source: mars-ice-dispatch.rule.json._

1.5 Waste collection — "garbage management with recourse"

• Use & purpose: household accumulation signals become replanned collection routes; completion is a record, not a device ping; a missed collection is rescheduled, never silently dropped.
• Who uses it: residents (report/confirm), waste crews (route execution), ward sanitation managers (rounds and exceptions).
• Flow:

1. Accumulation signals (fill-level thresholds, overflow reports) arrive as values.
2. The route is replanned — nearby stops grouped, markets cleared before morning trade where declared.
3. The crew executes; a completion record closes each stop.
4. A missed stop re-schedules automatically with a notice to the resident.

• Guard rails: triggers are values-only (fill-level, report counts) from lookups — no count invented. A sensor signal alone never fines anyone.
• Evidence & rollout: route versions, stop records, reschedules. Version 1.0.0 via waste-collection.rule.json. Soft.
• Low-resource behavior: residents report by USSD/WhatsApp/walk-in; crews work from printed/simplified lists if needed; narration EN/SW/FR.
• Worked example: 12 overflow reports in one market block → route re-sequenced so the market clears before trading → completion records close every stop → one missed stop rescheduled next morning with notice.

_Source: waste-collection.rule.json._

1.6 Weather preparation — "prep is reversible, dispatch is not"

• Use & purpose: the rain/flood preparation ladder — rain-gauge triggers a pre-alert, sandbags and crews pre-position, then a post-event report closes the loop. Reversible prep happens automatically; consequential dispatch needs a human.
• Who uses it: flood/ward desks, residents (alerts), incident commanders (dispatch decisions).
• Flow:

1. Rain-gauge SEN trigger fires.
2. Pre-alerts go out in declared language packs (Kutuma/SMS).
3. Preposition checks run (sandbags, pumps, shelter readiness).
4. Post-event report is drafted; dispatch decisions escalate to a human.

• Guard rails: prep is reversible and automatic; dispatch (closing roads, evacuation) is consequential and needs approval. No household is fined from a weather signal.
• Evidence & rollout: gauge events, alert receipts, preposition checks, post-event reports. Version 1.0.0 via weather-prep.rule.json. Soft.
• Low-resource behavior: SMS/USSD alerts with EN/SW/FR; no smartphone required; radio-friendly message packs.
• Worked example: 40 mm gauge crossing → ward alert in Kiswahili → market desk checks sandbags → pumps prepositioned → dry-out report published; no road closed without the commander's sign-off.

_Source: weather-prep.rule.json._

1.7 Help-desk auto-route — "every report gets a desk, fast"

• Use & purpose: community ticket intake (free text, WhatsApp, USSD) is classified and assigned to the right desk category (maintenance, security, pest, cleanliness, other), graded within SLA by a human, and closed only with evidence.
• Who uses it: residents (report), desk agents (intake), graders (human confirmation), ward officers (escalation).
• Flow:

1. Intake in any channel; text classified.
2. Routed to a desk category; SLA clocks start per declared band.
3. A human grader confirms the classification and assignment.
4. Close-out requires field evidence; the intake agent cannot also be the closer (separation of duties).

• Guard rails: no close without evidence; no self-closing; SLA bands are lookup values, never invented; free text is never interpreted as a legal notice by the machine alone.
• Evidence & rollout: ticket chain + grader verdict + close-out evidence. Version 1.0.0 via helpdesk-auto-route.rule.json; claim type cns://claim/type/community/ticket. Soft.
• Low-resource behavior: USSD/WhatsApp-first intake, EN/SW/FR narration, pay-per-use friendly (no app install needed).
• Worked example: "streetlight dead near the school gate" → classified as maintenance → assigned to the ward electrician desk → grader confirms → crew fixes with photo → closed with receipt.

_Source: helpdesk-auto-route.rule.json._

1.8 Complaints ladder — "escalation by the clock"

• Use & purpose: every complaint has an explicit escalation path — acknowledge by class, then urge, then escalate, then ward office — driven by SLA clocks, not by who knows whom.
• Who uses it: complainants (visibility), desk officers (time-bound action), ward offices (final escalation).
• Flow:

1. A complaint enters with a class and an acknowledge-by clock.
2. Unacknowledged complaints hit the urge step; un-actioned ones escalate.
3. The ward office receives the escalated case with full history.
4. Resolution returns through the same chain with evidence at each step.

• Guard rails: ladder thresholds are values-only from lookups. No fine amounts anywhere in the ladder. Escalation never skips evidence.
• Evidence & rollout: escalation log per complaint. Version 1.0.0 via complaints-ladder.rule.json. Soft.
• Low-resource behavior: the complainant needs only the original channel (USSD/SMS/WhatsApp); the ladder is clock-driven and visible as status codes.
• Worked example: a drainage complaint unacknowledged in 48 h → urge fires → 72 h with no action → escalates to the ward office with the service history attached.

_Source: complaints-ladder.rule.json._

1.9 Route watch — "patterns, not fines"

• Use & purpose: three or more similar unresolved complaints in the same block within a declared window open a pattern case — the systemic signal that a street, drain, or fixture is failing repeatedly. It routes like any other case; it never fines anyone automatically.
• Who uses it: ward officers (pattern review), maintenance planners (re-planning), residents (their reports stay anonymous patterns, never accusations).
• Flow:

1. Similar unresolved complaints accumulate per block within the window.
2. At the threshold, a pattern case opens.
3. The case routes via the sourcing bus to a solver route verdict; re-planning proposes, the guard authorizes.
4. The underlying crews and routes are replanned; the pattern closes when the recurrence stops.

• Guard rails: detector stays criteria-only; no identification of accused individuals; no auto-fine from a pattern; thresholds are lookup values.
• Evidence & rollout: pattern cases with report counts, windows, and re-plan verdicts. Version 1.0.0 via route-watch.rule.json. Soft.
• Low-resource behavior: works purely from report counts — no sensors needed; USSD/WhatsApp reports feed it.
• Worked example: four "drain blocked" reports in one week on the same lane → pattern case → drainage crew re-routed to that lane first → recurrence stops → pattern auto-closes with evidence.

_Source: route-watch.rule.json._

1.10 Patch rounds — "preventive maintenance by the clock"

• Use & purpose: recurring preventive ticks for streetlights, manholes, and public furniture — each due occurrence emits an expected-visit plus a record step via the sourcing bus to a solver route verdict. A missed round re-schedules by the same guard.
• Who uses it: ward maintenance planners, technician crews, facility managers.
• Flow:

1. The rounds tick fires per schedule values.
2. Expected-visit + record step emitted via the sourcing bus.
3. Solver produces the route verdict; the guard authorizes the round.
4. Completion is recorded; a miss re-schedules rather than dropping the round.

• Guard rails: the round is proposed by the optimizer, authorized by the guard; no settlement or closure from the optimizer alone. Schedules are lookup values.
• Evidence & rollout: expected-visits, verdicts, completion/miss records. Version 1.0.0 via patch-rounds.rule.json. Soft.
• Low-resource behavior: crews execute from the issued round list; verification can be a supervisor's tap or an SMS code — not necessarily an app.
• Worked example: monthly streetlight round → 14 expected-visits → solver sequences them into one route → 13 completed, 1 missed → re-scheduled notice issued to the ward.

_Source: patch-rounds.rule.json._

1.11 Payments meters (dues ladder) — "arrears handled politely"

• Use & purpose: public dues/fees follow a polite ladder — reminder, notice, grace, escalate — with lifeline-degrade rules as values. Arrears degrade politely and never hard-block life-safety services.
• Who uses it: revenue desks, residents (reminder recipients), ward finance officers.
• Flow:

1. A dues event is assessed (billable event).
2. Payment closes it; otherwise the ladder starts: reminder → notice → grace → escalate.
3. Lifeline services degrade per declared values only.
4. Escalation hands to a human with full payment history.

• Guard rails: no hard-block of life-safety (water/electricity minimums); no invented fee amounts; ladder steps are values; settlement happens only through the financial desk with a receipt.
• Evidence & rollout: assessment, ladder steps, payments, degradations. Version 1.0.0 via public-payments-meters.rule.json. Soft.
• Low-resource behavior: mobile-money-first payments; USSD pay codes; reminders by SMS/pay-per-use channels in EN/SW/FR.
• Worked example: a market stall fee unpaid → SMS reminder → formal notice → grace with the stall still trading → escalation to the finance desk with the full record.

_Source: public-payments-meters.rule.json._

1.12 School zones — "safer roads around schools"

• Use & purpose: time-windowed movement governance around schools: calendar windows restrict through-traffic to safer flow near school gates, crossing guards are rostered, and parent/caretaker advisories subscribe to the safety state.
• Who uses it: school principals and crossing guards, traffic wardens, parents/caretakers, the ward education desk.
• Flow:

1. Calendar windows (declared values) mark school arrival/dismissal periods.
2. During a window, the zone rule annotates the corridor as restricted — signage, guard presence, and routing guidance for crews.
3. Crossing guards are roster-assigned per window.
4. Parent advisories publish the zone state; incidents open cases.

• Guard rails: windows are policy values, never inferred from GPS alone; no fine is issued from a zone annotation; advisory content is values-only.
• Evidence & rollout: zone schedules, guard rosters, advisories, incidents. Version 1.0.0 via school-zones.rule.json. Soft.
• Low-resource behavior: guards work rosters on paper or SMS; parents get advisories by SMS/USSD in EN/SW/FR; no phone app needed.
• Worked example: a primary school's 06:30–08:00 window marks the gate corridor restricted → two crossing guards rostered → advisory to parents → a speeding report opens a traffic case (never a fine by itself).

_Source: school-zones.rule.json._

1.13 Traffic incidents — "cor WIP: patterns before penalties"

• Use & purpose: road-incident/accident pattern detection: three or more reports on the same corridor open a pattern case; jam-measure triggers and traffic-light flow playbooks respond to quantified signals.
• Who uses it: traffic desks, ward engineers, emergency dispatch for multi-vehicle events.
• Flow:

1. Incident reports (police, crew, public) land on the corridor.
2. At the pattern threshold, a corridor case opens.
3. Jam measures (rerouting guidance, signal plans) are proposed by the solver; the guard authorizes deployment.
4. The case closes when the quantified signal clears.

• Guard rails: thresholds are values-only; uncertain values are UNKNOWN-marked; no penalty from a pattern; emergency cases bypass the queue via SOS, never the pattern detector.
• Evidence & rollout: pattern cases with signal counts; measure verdicts. Version 1.0.0 via traffic-incident.rule.json. Soft.
• Low-resource behavior: reports come from any channel; traffic wardens carry the playbook on SMS confirmations.
• Worked example: three jam reports on one market approach → corridor case → signal plan proposed → deployed by the guard → reports cease → case closes with the signal history.

_Source: traffic-incident.rule.json._

1.14 Civic reporting boards — "publish the work, with approval"

• Use & purpose: aggregates closed civic work (faults fixed, rounds completed, dues collected) into monthly board digests per ward. The AI drafts; a human approves; only then does it publish. There is no auto-publish anywhere.
• Who uses it: ward information officers (publish), residents (read), auditors (compare digests to receipts).
• Flow:

1. Closed-work telemetry (verified closures only) feeds the digest builder.
2. The AI drafts the ward digest from the canonical story.
3. A human approves or amends; approval is recorded.
4. The approved digest publishes in EN/SW/FR value packs.

• Guard rails: no auto-publish; only verified closures count; no resident personal data in public digests; UNKNOWN values stay visibly unknown.
• Evidence & rollout: draft, approval, publication record per digest. Version 1.0.0 via civic-reporting-boards.rule.json. Soft.
• Low-resource behavior: publication via noticeboards and SMS summaries is a first-class channel.
• Worked example: a ward closed 142 tickets in a month → digest drafted from receipts → officer approves → published Friday in three languages with the receipt count quoted.

_Source: civic-reporting-boards.rule.json._

1.15 Mall tenancy — "multi-tenant facility operations"

• Use & purpose: stall, board, and occupancy tracking on existing storefront entities; a security incident ladder from ward security to the emergency desk; booking/deck reservations for weekly community use; revenue hooks into metering.
• Who uses it: mall/estate facility managers, tenants (occupancy, bookings), security officers, community groups (bookings).
• Flow:

1. Occupancy events maintain stall/board state on the space entities.
2. A security incident opens the ladder: ward security → emergency desk.
3. Booking requests reserve decks/slots per declared windows.
4. Revenue events flow into metering with values-only rates.

• Guard rails: rates are lookup values only — no invented prices; security escalation never skips the emergency desk; occupancy changes are recorded, never silently edited.
• Evidence & rollout: occupancy log, incident ladder, bookings, revenue events. Version 1.0.0 via mall-tenancy.rule.json. Soft.
• Low-resource behavior: tenant notices by SMS/USSD; booking via desk or USSD; mobile-money hooks for stall fees.
• Worked example: a stall vacancy is recorded → community booking takes the deck for Friday prayers → a theft report escalates ward security → emergency desk → all three events visible in one facility history.

_Source: mall-tenancy.rule.json._

1.16 Public-space rounds — "parks and playgrounds on a schedule"

• Use & purpose: public furniture, park, and playground maintenance rounds wired to the same rounds tick as patch rounds: each due occurrence emits an expected-visit and a record step via the sourcing bus to a solver route verdict; a missed round re-schedules.
• Who uses it: parks/estates managers, playground safety officers, ward crews.
• Flow: schedule tick → expected-visit emitted → sourcing bus + solver verdict → guard authorizes the round → completion recorded by photo or supervisor tap → miss re-schedules.
• Guard rails: optimizer proposes, guard authorizes; no closure by optimizer; schedules are values; playground safety items escalate to the ward officer if missed twice.
• Evidence & rollout: expected-visits, verdicts, completions/misses. Version 1.0.0 via public-space.rounds.rule.json. Soft.
• Low-resource behavior: printed round lists work; supervisor tap-by-SMS acceptable as completion evidence.
• Worked example: weekly playground inspection → expected-visits emitted → crew completes, one swing reported broken → remedy case opens from the same truck roll.

_Source: public-space.rounds.rule.json._

1.17 Resident options (dweller upsells) — "offer, never force"

• Use & purpose: optional services for residents (blocks/units registered with no personal data): the playbook surfaces relevant add-ons and the resident chooses. No forced enrolment, no auto-charge.
• Who uses it: residents (choose), estate managers (offer), billing desks (record only what was chosen).
• Flow:

1. Resident context (block/unit) is registered without personal data.
2. Relevant optional services are surfaced per declared bands.
3. The resident opts in or declines — both are recorded.
4. Only chosen options enter the billing meters.

• Guard rails: suggestion only; no auto-charge; no dark patterns; decline is final and penalty-free.
• Evidence & rollout: offers surfaced, choices recorded. Version 1.0.0 via dweller-upsells-options.rule.json. Soft.
• Low-resource behavior: opt-in via USSD/SMS; decline needs no justification.
• Worked example: a block is offered optional water-tank cleaning → residents opt in by USSD → only opted-in units are billed → the cleaning crew's list matches the opts.

_Source: dweller-upsells-options.rule.json._

1.18 Relief cases (emergency housing) — "under the SOS ceiling"

• Use & purpose: evacuation placements and short-term subsistence evidence after a disaster or eviction. Relief is a child of SOS: it inherits the parent ceiling and may only tighten it — never widen scope.
• Who uses it: relief desks, ward disaster committees, displaced residents.
• Flow:

1. An SOS parent session opens for the event.
2. Relief cases attach placements (school, hall, host) with subsistence evidence.
3. Each case is bounded by the parent scope; widening is refuse-by-design.
4. Closure requires placement + subsistence evidence per person.

• Guard rails: scope can only narrow; every placement carries evidence; no cash handling by playbooks — mobile-money where money moves at all.
• Evidence & rollout: placement records, subsistence evidence, closure verdicts. Version 1.0.0 via relief-cases.rule.json. Soft.
• Low-resource behavior: registration at walk-in desks and USSD; headcount without smartphones.
• Worked example: flood displaces a street → SOS session → school hall placements recorded per family → subsistence evidence attached → cases close as families return, each within the parent scope.

_Source: relief-cases.rule.json._

1.19 Social housing queue — "allocation by declared bands"

• Use & purpose: housing allocation queues: application → needs scoring by declared bands → ranked queue → offers. Eligibility resolves by key from governed lookups with values only; individual enumeration is forbidden.
• Who uses it: housing committees (band owners), applicants (apply, track position), auditors (verify the queue order).
• Flow:

1. Applications are scored against declared needs bands (household size, vulnerability, wait time).
2. The ranked queue is published as order + rationale, never as personal data.
3. Offers go to the head of the queue; refusal reasons are recorded.
4. Allocation to a unit closes only with a human confirmation.

• Guard rails: no allocation by reflex without human confirmation; bands are lookups, not code; no individual data in public queues; appeal path exists.
• Evidence & rollout: applications, score breakdowns, queue snapshots, offers. Version 1.0.0 via social-housing-queue.rule.json. Soft.
• Low-resource behavior: application and position checks via USSD/SMS and walk-in desks.
• Worked example: 210 applications scored → top-ranked family offered a two-room unit → human officer confirms → tenancy recorded.

_Source: social-housing-queue.rule.json._

1.20 Rent/lease register — "occupancy with a memory"

• Use & purpose: lease registration/renewal events maintain the occupancy register; use-change events append use-change history per parcel (the entity's recorded life).
• Who uses it: land/ward registries, landlords and tenants (registration), auditors (history).
• Flow:

1. A lease event (new/renewed/terminated) registers against the parcel entity.
2. The register state updates; the history appends a use-change entry.
3. Unregistered occupancy is flagged (refused silently is not an option — it is surfaced).
4. Arrears handling is explicitly out of scope (UNKNOWN) and routes to the payments meters.

• Guard rails: registration is append-only history on the canonical parcel; no deletion of history; arrears logic stays out of this rule.
• Evidence & rollout: register state + use-change history. Version 1.0.0 via rent-lease-register.rule.json. Soft.
• Low-resource behavior: registration at walk-in desks with printed receipts; no app needed.
• Worked example: a shop unit changes from retail to office use → use-change event appended to the parcel history → the register reflects it next quarter.

_Source: rent-lease-register.rule.json._

1.21 Valuation disclosure — "comparables with provenance"

• Use & purpose: market valuation comparison: similar parcels' evidence becomes transparency findings. Evidence-based only; no automated gouge projection; every finding carries its provenance. Comp prices are UNKNOWN until sourced.
• Who uses it: valuation officers, buyers/sellers (transparency), land registries.
• Flow:

1. Comparable parcels' recorded evidence is gathered.
2. A comparison is computed and recorded with sources.
3. Findings publish with provenance (which comps, which dates).
4. Any use of the finding cites the finding id, not a price the system invented.

• Guard rails: no automated price projection; no comp without provenance; UNKNOWN stays unknown.
• Evidence & rollout: comp sets, comparisons, findings. Version 1.0.0 via valuation-disclosure.rule.json. Soft.
• Low-resource behavior: findings readable on noticeboards and SMS summaries.
• Worked example: a parcel sale is compared against three recorded comparables → finding published with all three provenances → the buyer sees exactly what the number rests on.

_Source: valuation-disclosure.rule.json._

Family 2 — Scenario packs (staged cases with verdicts)

Scenario packs are multi-step governed cases: intakes flow through stages with guard checks and terminal verdicts, sealed with PoCE. They are the right shape whenever a process needs due process, quorums, or expert sign-off.

2.1 Civic maintenance tick — "the recurring civic round"

• Use & purpose: recurring civic checklist rounds in standing-order style: fault reported → fair sourcing of a crew → scheduling/routing → photo-or-arrival-point proof → verified disbursement. The everyday engine of ward maintenance.
• Who uses it: residents (report), dispatch desk (source/schedule), crews (execute), finance (verified disbursement), auditors (the sealed round).
• Flow:

1. A fault (or scheduled check) opens the round.
2. Fair sourcing matches a qualified crew (distance, skill, availability).
3. Scheduling/routing produces the route; the guard authorizes it.
4. Completion proof (photo or arrival point) is attached.
5. Disbursement is verified against the proof; the round seals.

• Guard rails: sourcing never evades qualification; disbursement only against proof; no partial "close enough" — a round is proved or it stays open.
• Evidence & rollout: round record, sourcing verdict, route, proof, disbursement seal. Version 1.0.0 via civic-maintenance-tick.scenario.json. Soft.
• Low-resource behavior: crews execute from issued lists; photo proof can be a supervisor tap or SMS code when devices are scarce.
• Worked example: a burst pipe report → qualified plumber crew sourced → route issued → photo proof attached → disbursement released against the seal.

_Source: civic-maintenance-tick.scenario.json._

2.2 Civic inspection cycle — "inspect, score, remedy"

• Use & purpose: public facility inspection as a staged case: open → inspect (photo+GPS stamped) → score against the open checklist rubric (values) → remedy ladder (minor fix / re-inspect / escalate) → close with a PoCE seal.
• Who uses it: inspection officers, remedy crews, ward officers (escalation), the public (published outcomes).
• Flow:

1. An inspection case opens for a facility.
2. The inspector records photo+GPS-stamped evidence item by item.
3. Scoring applies the open rubric as values (no hidden weights).
4. The remedy ladder decides: minor fix, re-inspect, or escalate.
5. Closure requires a sealed PoCE receipt.

• Guard rails: checklist weights are published values; no score invented; closure without the seal is impossible; remedy escalation moves up, never around.
• Evidence & rollout: inspection record, stamped evidence, scores, remedy, seal. Version 1.0.0 via civic-inspection-cycle.scenario.json. Soft.
• Low-resource behavior: inspectors can work from the printed checklist and sync stamps later; SMS confirmations acceptable as stamped evidence where declared.
• Worked example: a public toilet block inspection → 11/12 checklist items pass → one remedy (tap replacement) → re-inspect passes → sealed closure published.

_Source: civic-inspection-cycle.scenario.json._

2.3 Public reporting digest — "the publication desk"

• Use & purpose: weekly/monthly digests of closed work per ward rendered from the canonical story into EN/SW/FR value packs. Advisory draft → approved; never auto-publish. It consumes closed-work telemetry, so upstream verdicts are rendered as gates, not recalculated.
• Who uses it: communications officers (draft/approve), residents (read), auditors (verify counts against receipts).
• Flow:

1. Closed-work telemetry is collected per ward.
2. A digest builder renders the canonical story into language packs.
3. A human approves; the approval is recorded.
4. Publication goes out by the declared channels.

• Guard rails: never auto-publish; never render upstream verdicts as its own; only verified closures are counted.
• Evidence & rollout: draft, approval, publication record. Version 1.0.0 via public-reporting-digest.scenario.json. Soft.
• Low-resource behavior: noticeboards, SMS summaries, and community radio scripts are first-class channels.
• Worked example: a ward's month is rendered into three language packs → officer approves the Kiswahili and English versions with one correction → published with the receipt count quoted.

_Source: public-reporting-digest.scenario.json._

2.4 Zoning permit — "permission with due process"

• Use & purpose: permit application → zoning check (values only) → quorum decision → deed record on the land-parcel entity. Unknown or ambiguous parcels refuse; open conflict tickets pause the flow.
• Who uses it: applicants (apply, track), zoning officers (check), the quorum panel (decide), land registries (record).
• Flow:

1. An application is filed against a parcel identity.
2. The zoning check evaluates declared land-use values.
3. The quorum decides on the complete evidence.
4. The decision records as a deed on the land-parcel entity.

• Guard rails: unknown/ambiguous parcels refuse (fail closed); open conflicts pause; public event names are provisional, registration pending; no permit from a reflex.
• Evidence & rollout: application, check verdict, quorum decision, deed record. Version 1.0.0 via zoning-permit.scenario.json. Soft.
• Low-resource behavior: applications at walk-in desks with printed status receipts; USSD status checks.
• Worked example: a shop fit-out permit → zoning values checked → quorum approves 3/3 → deed recorded on the parcel → the parcel history shows the grant forever.

_Source: zoning-permit.scenario.json._

2.5 Encroachment notice — "evidence first, notice second"

• Use & purpose: suspected structures on land: evidence attached → neighbor + owner notified (due process) → review (quorum if disputed) → resolution/receipt. Child states inherit parent limits and never widen them.
• Who uses it: land officers (evidence), neighbors and owners (noticed parties), review quorums, courts (receipt consumers).
• Flow:

1. A suspected encroachment is reported with evidence.
2. Neighbor and owner are notified — due process is a stage, not a courtesy.
3. Review proceeds; disputes go to quorum.
4. The resolution issues with a receipt.

• Guard rails: no action before notice; child states narrow only; no demolition or fine from the scenario itself.
• Evidence & rollout: report, evidence, notices, review, resolution. Version 1.0.0 via encroachment-notice.scenario.json. Soft.
• Low-resource behavior: notices by hand delivery with signed receipt; SMS follow-ups.
• Worked example: a fence crosses a parcel boundary → evidence attached → both owners notified → quorum review finds a boundary error → resolution orders correction with a costed receipt.

_Source: encroachment-notice.scenario.json._

2.6 Building compliance inspection (property) — "certify only with an expert"

• Use & purpose: building hygiene / fire / accessibility inspections ending in certificate issuance — but only with expert sign-off. Export a compliance packet. No auto-certification, no auto-fine.
• Who uses it: building inspectors, licensed experts (sign-off), building owners (certificates), insurers/banks (packets).
• Flow:

1. An inspection is scheduled for a building entity.
2. The inspector records hygiene/fire/accessibility evidence.
3. A licensed expert signs off (mandatory, non-skippable).
4. The certificate issues; the compliance packet exports.
5. Expiry watches re-schedule the next inspection.

• Guard rails: expert sign-off is mandatory — no path around it; no auto-certify; no auto-fine; event names provisional.
• Evidence & rollout: inspection record, sign-off, certificate, packet. Version 1.0.0 via building-compliance-inspection.scenario.json. Soft.
• Low-resource behavior: paper checklists with later sync; printed certificates for owners without connectivity.
• Worked example: a three-storey block → fire/accessibility evidence recorded → expert signs → certificate issues with 12-month expiry → packet exported to the insurer.

_Source: building-compliance-inspection.scenario.json._

2.7 Building safety inspections (facilities) — "large buildings, full packet"

• Use & purpose: the facilities-flavored sibling: large-building compliance inspections (fire, accessibility, hygiene) ending in expert sign-off, certificate issuance, and a compliance-packet export for big managed buildings.
• Who uses it: facility managers, experts, building owners, tenants (safety visibility).
• Flow: schedule → evidence (fire/accessibility/hygiene) → expert sign-off → certificate + packet export → expiry watch.
• Guard rails: identical to 2.6 — expert sign-off mandatory, no auto-certify, no auto-fine.
• Evidence & rollout: inspection, sign-off, certificate, packet. Version 1.0.0 via building-safety-inspections.scenario.json. Soft.
• Low-resource behavior: same as 2.6; tenants can verify certificates by USSD code.
• Worked example: a shopping mall → inspection evidence → expert sign-off → certificate with expiry → packet shared with insurers and the ward.

_Source: building-safety-inspections.scenario.json._

Family 3 — Starter packs (bundled go-lives)

A starter pack is a bundle of playbooks, lookups, and policies that a ward can open on Day 1. Each pack below lists what it contains, who opens it, and what stays out of scope until expanded.

3.1 Ontology pack — "the shared list of names"

• Use & purpose: establishes the shared entity spine every other playbook depends on: land/parcel/space hierarchy, entity identities, and lifecycles. No pack works until the names agree.
• Who uses it: city administrators (seed names), every desk (consume names).
• Contents: entity-type catalog, parcel/space hierarchy seeds, lifecycle rules, alias/mint conventions.
• Guard rails: no bespoke tables — everything maps to canonical claim/resource/integration primitives. Renames are lifecycle events, never silent edits.
• Rollout: the first pack opened anywhere; all other packs bind to it.
• Evidence: entity registrations + lifecycle history.
• _Source: ontology.pack.json._

3.2 Maintenance desk pack — "report → dispatch → verified"

• Use & purpose: the JMII-style maintenance entry: WhatsApp/USSD intake, classify, nearest certified vendor proposal, one-tap approval, photo+GPS verification, PoCE receipt, escrow-until-proof.
• Who uses it: residents (report), vendor crews (execute), ward managers (approve), finance (escrow release).
• Contents: intake, classification, vendor sourcing, approval, verification, PoCE receipt, escrow-until-proof.
• Guard rails: escrow releases only against proof; approval is one human tap by a named manager; no vendor can self-approve.
• Rollout: pilot-able in a single ward within days.
• Evidence: intake chain, PoCE receipt per job.
• _Source: maintenance-desk.pack.json._

3.3 Financial desk pack — "dues, fines and payables, accounted"

• Use & purpose: FIN-native ledger per community: accounts, AR/AP, period close; dues, fines, service charges, vendor payables; scheduled reminders; monthly statement + dashboard.
• Who uses it: community treasurers, ward finance officers, vendors (payables), auditors.
• Contents: chart of accounts, receivables/payables, period close, scheduled Kutuma reminders, monthly statements, dashboard bindings by key.
• Guard rails: reminders are scheduled, amounts are lookup values; closing a period is a quorum act; no ledger mutation by reflex.
• Rollout: opens after the maintenance desk (jobs create payables).
• Evidence: ledger entries, period closes, statements.
• _Source: financial-desk.pack.json._

3.4 Community desk pack — "announcements, gates, visits"

• Use & purpose: community desks: announcements, gate passes, visitor logs, polling — the daily social fabric of an estate or ward.
• Who uses it: residents, gate/security staff, estate managers.
• Contents: announcements, gate passes, visitor logs, polls.
• Guard rails: visitor logs minimize personal data; polls are advisory, not binding; registration pending — no SKU issued yet (provisional expansion bundle).
• Rollout: provisional; expand when the estate-desk gaps are sourced.
• Evidence: announcements, passes, logs, poll results.
• _Source: community-desk.pack.json._

3.5 Emergency guard pack — "the safety pairing"

• Use & purpose: the community guard pairing inside the safety stack: guard roster, incident reporting, and escalation into the emergency desk.
• Who uses it: guard teams, estate managers, the emergency desk.
• Contents: guard roster, incident intake, escalation hooks into SOS.
• Guard rails: whether this equals the Estate Safe community-guard pack is UNKNOWN (sourced as uncertain); guard actions never escalate beyond their scope.
• Rollout: provisional until identity is confirmed.
• Evidence: rosters, incident records.
• _Source: emergency-guard.pack.json._

3.6 Civic maintenance full pack — "the complete round"

• Use & purpose: the full lifecycle expansion of the civic maintenance tick: report → dispatch → verified disbursement, end to end, as one bundle.
• Who uses it: ward maintenance teams, finance, auditors.
• Contents: report-to-dispatch chain, verification, disbursement, reporting.
• Guard rails: contents/buyers/exclusions UNKNOWN as a separate bundle in the cited sources; registration pending, no SKU issued.
• Rollout: provisional expansion; the base tick (2.1) ships first.
• Evidence: sealed rounds.
• _Source: civic-maintenance-full.pack.json._

3.7 Zoning parcel ops pack — "the parcel's daily operations"

• Use & purpose: parcel-centric operations: registrations, use changes, valuations, and permits bound to the parcel entity — the working surface for the property-compliance family.
• Who uses it: land officers, property owners, valuation officers.
• Contents: parcel registry hooks, permit scenario, valuation disclosure, encroachment scenario.
• Guard rails: inherits the scenario guards (due process, quorum, expert sign-off); registration pending.
• Rollout: provisional; binds to the ontology pack.
• Evidence: parcel histories.
• _Source: zoning-parcel-ops.pack.json._

Family 4 — Governance rules (the law of the platform)

4.1 Scope rules — "who may act where"

• Use & purpose: scope-governance family (s142 + s165): one default scope template and the delegation-chain shape (root → delegate → carry). Declarative values only; no person enumeration. Seeded before first bind.
• Who uses it: platform administrators (seed), scope owners (delegate), every playbook (check).
• Guard rails: delegation chains are bounded; cascade revoke works; scope checks precede every consequential act.
• Evidence & rollout: scope registry, delegation records. Version 1.0.0.
• _Source: scope-rules.json._

4.2 Compliance policies — "the evidence each action demands"

• Use & purpose: compliance-gate family: per action (approve/finalize/disburse) the required evidence fields, SoD constraints, and threshold-band references. Lookups supply numbers where they exist.
• Who uses it: compliance officers (own the gates), every desk (pass the gates), auditors.
• Guard rails: a gate that cannot be satisfied blocks the action — fail closed; bands are lookup values.
• Evidence & rollout: gate evaluations per action. Version 1.0.0.
• _Source: compliance-policies.json._

4.3 Spatial jurisdiction — "which rules govern this place"

• Use & purpose: spatial-rule family: space entities bound to governing rule sets, plus boundary-crossing event declarations. Zone subjects UNKNOWN-marked where unsourced.
• Who uses it: city administrators (bind rules to places), ward officers, every reflex (jurisdiction check).
• Guard rails: a place with no governing rule set refuses consequential actions; fan-out uses the playbook pattern, not code forks.
• Evidence & rollout: spatial bindings + crossing events. Version 1.0.0.
• _Source: spatial-jurisdiction.json._

4.4 AI personas — "AI proposes, people decide"

• Use & purpose: advisory-persona family: assistant definitions that may summarize, draft, and suggest — but never approve, settle, disburse, close, or auto-advance.
• Who uses it: residents (ask), officers (receive drafts), AI administrators (tune personas).
• Guard rails: persona capabilities are allowlisted; every AI output that matters needs a human verdict; personas are versioned and retunable.
• Evidence & rollout: persona definitions + draft/decision pairs. Version 1.0.0.
• _Source: ai-personas.json._

Cross-cutting guarantees

• Zero bespoke tables: every entity above maps to canonical claim/resource/integration primitives. If a playbook cannot be expressed there, the design stops and asks.
• Declarative first: thresholds, bands, schedules, and ladders are data (NATS KV lookups), never hardcoded JavaScript.
• Fail closed: missing or unknown values refuse the action; the refusal is the evidence.
• Sourcing/solve/optimize: every playbook that needs hands wires the sourcing bus; solver verdicts are gates, never approvals; optimizers propose while the claim gate authorizes (see the optimization capability design).
• Low-resource ready: every playbook in this catalog has a working path on USSD/WhatsApp/SMS/walk-in — no smartphone dependency for residents.

How these playbooks are authored and wired: the playbook building design. Stakeholder view: the playbook registry. Developer contracts: the playbook designs.