# ✂ docujoint template — the tracker's weekly report. SHIPPED UNARMED.
#
# WHY THIS FILE IS NOT AT THE ROOT, AND WHAT ARMING IT MEANS
#
# A host reads exactly three surface names beside format.yaml: `dashboard.yaml`
# (the app), `report.yaml` (this — the linear, print-shaped, page-headed
# document) and `intake.yaml` (the form). Holding a file at one of those names
# IS the declaration: the first push of a new knowledge base adopts them, every
# later change goes through `PUT /api/:org/:kb/format`, and from then on the KB
# bakes and publishes that surface on every push.
#
# So this template ships the report ONE DIRECTORY OVER. Nothing reads
# `surfaces/`. A KB scaffolded from this template bakes exactly what it baked
# before the report existed — no artifact, no url, no bake time, not one byte
# in the dashboard — and the three views it places (vault/views/burndown.yaml,
# flow.yaml, cycle-summary.yaml) sit in the library unplaced, which costs the
# bake nothing. Nobody gets a report they did not ask for.
#
#   ARM IT — one line, and it is the only line:
#
#       cp surfaces/report.yaml report.yaml
#
#   (an existing cloud KB instead PUTs this file's text as `reportYaml`, which
#   is the same declaration through the door that owns control-plane state.)
#
#   RENDER IT WITHOUT ARMING IT — the local half needs no host at all:
#
#       dj report --surface surfaces/report.yaml --out report.html
#
# WHAT IT DRAWS. Three sections, three named views, four marks over ONE thing:
# the operational event log of the `issues` block. Nothing here counts what
# your issues say now — the dashboard already does that. These count what they
# SAID, day by day, which is the only way a burndown can be honest.
#
# Where there is no event log in reach — a self-contained export, a local
# render, a KB whose host has not wired its history door — every chart renders
# a note saying what it reads and why it is empty. An empty chart that looks
# like a real zero is the failure this refuses to ship.

surface: report

report:
  title: Weekly tracker story
  subtitle: What the issues did — not what they say now

sections:
  - label: Delivery
    notes: |
      **Burndown** is the open group at the end of each day; **burnup** is what
      reached Done, with a second line for total scope. Scope rising while the
      burndown stays flat is arriving work, not slow work — the two lines exist
      so the difference cannot be argued about.
    place: [burndown]

  - label: Where the work sits
    notes: |
      One band per declared status, in the order `format.yaml` declares them.
      A band that widens week over week is a queue: issues enter that status
      faster than they leave it.
    place: [flow]

  - label: How long it takes
    notes: |
      Days from a started status to Done, over the same twelve weeks. Read the
      exclusion footnote under the chart before quoting the median: issues
      whose passage began before the window, whose baseline came from a
      wholesale migration, or that reached Done without ever being open are
      left out **and counted**, rather than guessed at.
    place: [cycle-summary]