LeanZero Management

09The Iron-Clad successor rule

The single dependency rule the whole scheduler is built on: a successor starts on the next working day after its latest predecessor's due date, and nothing is allowed to sit anywhere else.

LeanZero Management schedules with exactly one dependency rule, called the Iron-Clad rule in the code. A dependency says "A blocks B". The rule says B must start on the next working day strictly after A's due date. It is not a suggestion the engine tries to honour — it is enforced on every cascade, on the issue you just edited as well as on everything downstream of it.

The rule, exactly

requiredStart(successor)
  = MAX over all predecessors P that have a dueDate of:
      lag(P->successor) = 0 : getNextWorkingDay( P.dueDate + 1 calendar day )
      lag(P->successor) = N : that same base, advanced N further WORKING days

getNextWorkingDay(d) = d itself if d is a working day, otherwise
                       the first working day after d

successor.startDate = requiredStart
successor.dueDate   = addWorkingDays(requiredStart, duration)
                    = requiredStart advanced (duration - 1) working days

Why each part is written that way

+ 1 calendar day, then next working day

The predecessor's due date is a day of work, not a handover moment, so the successor cannot share it. Adding one calendar day and then snapping forward lands on Monday when the predecessor finishes on a Friday, and skips any holiday in between (date-utils.js getRequiredSuccessorStart, mirrored by working-days/calculator.js getRequiredSuccessorStart).

MAX over all predecessors

A merge point (an issue with two or more predecessors) waits for the LATEST of them. Taking the maximum of the per-link required starts — rather than the maximum predecessor due date — is what makes per-link lag work correctly: with all lags at zero the two are identical, because the +1-working-day offset is monotonic (cascade-core.js requiredStartFromPreds).

Predecessors with no due date are skipped

requiredStartFromPreds ignores any predecessor that has no dueDate, and any whose date string does not parse. An undated predecessor constrains nothing, and a successor whose predecessors are all undated is never moved.

What happens when you try to break the rule

Any edit to an issue that has predecessors re-checks that issue's start. If the resulting start is not the required start, the engine overwrites it with the required start, rebuilds the due from the issue's duration, and raises a violation. This fires in BOTH directions — too early and too late are equally rejected.

Violation messages you will actually see

Violations are buffered for 100 ms and then shown as a single warning toast, so a burst of edits does not produce a burst of toasts. A single cascade raises at most one violation — the one on the issue you edited — so the plural message only appears when several edits land inside that window (PlanView.jsx onViolation).

10Working days, holidays and the plan calendar

Every date the engine produces is a working day; how the working-day pattern and holiday list are chosen, and what happens when you change them.

All scheduling maths runs on a working-day context: a set of weekday numbers (0 = Sunday … 6 = Saturday) and a set of holiday dates as YYYY-MM-DD strings. A day is a working day when its weekday is in the set AND its date is not in the holiday set. Dates are handled as UTC midnight throughout — the frontend parses with Date.UTC, the backend with a 'T00:00:00Z' suffix — so no timezone can shift a bar by a day.

Where the calendar comes from

Holidays on a plan

Holidays are added to a plan's own schedule as { date, name } entries, kept sorted by date and de-duplicated on the date. A date must match YYYY-MM-DD exactly or the addPlanHoliday resolver rejects it with "Date must be YYYY-MM-DD". On the timeline a holiday column is drawn with a diagonal amber hatch (a -45° repeating gradient in rgba(251,191,36,…)) and a tooltip carrying the holiday's name, or "Holiday: YYYY-MM-DD" when it has none; weekends are drawn as a single repeating background layer per row rather than one element per day.

The frontend working-day primitives, and their exact semantics

getNextWorkingDay(date)

INCLUSIVE. If the date is already a working day it is returned unchanged. Otherwise it steps forward one day at a time, up to 30 steps.

addWorkingDays(start, N)

Returns the date N working days from start, counting start as day 1 — it advances N-1 working days. So addWorkingDays(Mon, 1) = Mon and addWorkingDays(Mon, 5) = Fri (Mon–Fri, no holidays), both verified. N <= 0 returns the start unchanged. Guarded at 5000 iterations.

workingDaysBetween(start, due)

INCLUSIVE count of working days from start to due. Mon→Fri = 5. Returns 0 when due is before start, and null when either date is missing.

Snapping

Nothing is ever left on a non-working day. In a full recompute (cascadeAll) the engine first sweeps every issue: if its start falls on a non-working day the start moves forward to the next working day and the due is rebuilt from the duration; if only the due falls on a non-working day the due moves forward and the duration is recomputed from the new span. Verified against the engine: an issue starting Sat 06 Jun with duration 2 settles to Mon 08 Jun → Tue 09 Jun.

11Duration semantics, and how a missing duration is recovered

Duration is a 1-indexed count of working days, why duration 1 means start equals due, and the exact ladder the engine uses when Jira has no duration to give it.

Duration is the number of WORKING days an issue occupies, counted inclusively from its start. It is 1-indexed: duration 1 means the issue starts and finishes on the same day (start === due), duration 5 starting Monday finishes Friday. Duration 0 is not "no duration" — it is the declaration of a milestone (see the milestones section).

The conversions each engine uses

FRONTEND (authoritative — its output is what Apply writes)
  due      = addWorkingDays(start, duration)   // advances duration - 1 working days
  duration = workingDaysBetween(start, due)    // inclusive, 1-indexed

BACKEND (src/services/working-days/calculator.js)
  due      = calculateDueFromStartAndDuration(start, duration)
             = start when duration === 1, else addWorkingDays(start, duration - 1)
  duration = calculateDuration(start, due)
             = max(1, calculateWorkingDaysBetween(start, due) + 1)
  start    = calculateStartFromDueAndDuration(due, duration)
             = due when duration === 1, else subtractWorkingDays(due, duration - 1)

When an issue has no stored duration

Duration is read from a single Jira custom field (default customfield_11581, configurable) — issue-transformer.js reads it from nowhere else. A Jira project that never configured that field indexes EVERY issue with duration: null. Falling back to "1" in that situation would flatten every real multi-day task into a single point — and a flattened task then also satisfies the milestone test, so tasks would turn into diamonds mid-cascade. The engine therefore recovers a duration instead, using this ladder (effectiveDuration in cascade-core.js).

Duration recovery ladder, in order

1. 1Take Number(_original.duration || duration) — the applied Jira baseline, falling through to the live value whenever the baseline is 0, null or absent — and use it if it is greater than 0. The baseline is preferred so that a half-edited issue still contributes its committed span.
2. 2Otherwise, if the issue declares a zero duration, return 0 — a declared milestone stays a milestone. (A positive CURRENT duration overrides a zero baseline: isDeclaredZeroDuration returns false in that case.)
3. 3Otherwise recover the issue's OWN working-day span from its dates — baseline start/due first, falling through per-field to the current dates — with a floor of 1.
4. 4Otherwise return 1.

Import normalisation on load

Raw Jira imports frequently carry a duration that disagrees with their own dates (a calendar-day difference, or an estimate). On load, normalizeImportedDurations rewrites duration to the working-day span of start→due for every issue that has BOTH dates, parents included, using the plan's own calendar. It also syncs _original.duration to the same value, so the correction does not read as an unsaved edit and does not appear as a permanent phantom row in every Apply. Issues missing either date are skipped, and an explicit duration of 0 is left alone. This runs before the KVS snapshot is taken, so the corrected value becomes the baseline.

Editing an edge recomputes the duration

Any edit that supplies a start date or a due date causes the duration to be recomputed as the working-day span of the resulting start→due. Without this, dragging only the due edge left the stored duration stale and the number no longer matched the bar. Drags that already send an explicit duration round-trip to the same value, so the rule is safe for them too.

12Per-link lag

How to hold a successor back by N working days without fighting the Iron-Clad rule, where lag is stored, and what it does to the required start.

Lag is a per-LINK delay measured in working days. It belongs to one dependency edge, not to an issue: the same successor can follow one predecessor immediately and another with a five-day lag. Lag is stored on the successor as predecessorLags[predecessorKey] = N, kept in the plan's own dependency key so a re-index cannot wipe it, and denormalised onto the issues on every load (kvs-store.applyLagsToIssues).

The lag formula

base   = getNextWorkingDay(predecessor.due + 1 calendar day)   // lag 0 — plain adjacency
lag N  = base advanced N further WORKING days

requiredStart = MAX over predecessors of that per-link value

Implementation note: the backend writes addWorkingDays(base, N); the frontend's
addWorkingDays advances N-1, so it writes addWorkingDays(base, N + 1). Both must
land on the same date — locked by test/parity, including a lag=1 boundary fixture.

What a lag of N does (predecessor due Wed 10 Jun 2026, Mon–Fri, no holidays)

Setting a lag in the UI

1. 1Click the dependency arrow between two bars on the timeline. The link menu opens, headed "FROM blocks TO" (with a "staged" badge if the link itself has not been written to Jira yet), and carries a red "Remove link" button.
2. 2Use the − / + stepper labelled "Lag (working days)". The current value sits between them, in the primary colour when it is above zero and muted grey at zero; the − button is disabled at zero.
3. 3Every change re-settles the WHOLE plan immediately for live preview (cascadeAll), then persists the lag. Setting it back to 0 deletes the entry rather than storing a zero. If persisting fails, only that edge's lag is rolled back and re-cascaded, with the toast "Couldn't save lag: … — reverted." — and only if your optimistic value is still the current one, so a rapid re-edit is never clobbered.

13Buffers: due held, duration shrinks

What marking an issue Buffer = Yes does to it during a cascade, what exhaustion means exactly, what it looks like on the timeline, and what it protects downstream.

A buffer is an ordinary issue with the Buffer field set to Yes (Jira field customfield_12399 by default; toggled in the date editor with the No / Yes buttons). It is a shock absorber: its due date is treated as an immovable deadline, so when a cascade pushes it, the start moves and the DUE STAYS PUT. The duration shrinks by exactly the amount of the delay.

Buffer cascade, exactly

fixedDue = _original.dueDate  (the APPLIED Jira baseline, falling back to the current due)

if requiredStart <= fixedDue:        // absorbing
     start    = requiredStart
     due      = fixedDue             // unchanged
     duration = max(1, workingDaysBetween(requiredStart, fixedDue))

if requiredStart >  fixedDue:        // EXHAUSTED
     start    = requiredStart
     due      = requiredStart        // the deadline is gone
     duration = 1

Buffer states and what you see

What "exhausted" actually means

The condition

The required start computed from the buffer's predecessors is LATER than its fixed due date. There is no remaining span to give up.

The result

The buffer collapses to a single day at the required start. It stops being a deadline and becomes a point marker of where the chain now really is.

The consequence downstream

An absorbing buffer holds its due, so everything after it is untouched. An exhausted buffer's due moves, so the slip passes straight through to its successors. Verified against the engine: with A → BUF (fixed due 19 Jun) → Z, the first slip left Z untouched at 22 Jun→23 Jun; the slip that exhausted the buffer moved Z to 23 Jun→24 Jun.

How it is counted

In the cascade provenance a buffer is counted as either absorbed or exhausted, never both: absorbed means it shrank and survived, exhausted means duration <= 1 and start === due. The Gantt's own fill uses the slightly tighter duration === 1 && start === due.

14Parents roll up; milestones are declared

Parent dates are derived from children and can never be typed in; milestones are declared by a zero duration or a milestone issue type and stay points through every cascade.

Parent roll-up

A parent's dates are not scheduled — they are computed from its children, on every cascade, after the leaves have settled.

The roll-up formula

parent.start    = getNextWorkingDay( MIN over children of child.start )
parent.due      =                    MAX over children of child.due
parent.duration = workingDaysBetween(parent.start, parent.due)   // floored at 1

Details that matter

• Children are found by parentKey, so an Epic whose Stories point at it is rolled up even though those Stories are not Jira subtasks. (The backend additionally unions in the subtasks array, so both hierarchy shapes behave the same.)
• Roll-up walks UP the parent chain from every issue the cascade changed, parent before grandparent, so a grandparent bracket widens too.
• A parent with no children in the plan is left alone.
• Backend only: if the parent itself has predecessors and its dependency-driven start is later than its earliest child, that later start wins; and if the start then lands past the children's latest due, the parent collapses to a point (clamp M6).
• A parent's bar is never drawn as a task bar. Inside the 22 px bar row it renders as a 5 px top line carrying the grey gradient #475569 → #334155, with two 8 × 10 px end brackets in 3 px solid #475569 and the issue key above it in 9 px uppercase.

Milestones

A milestone is something you DECLARE, not something a schedule change can accidentally create. There is one definition, in utils/milestone.js, used by the chart, the Explain panel and the harness alike — the rule previously existed in three disagreeing copies.

The milestone test, in order

How milestones behave in a cascade

They move, but they stay points

A declared zero-duration milestone follows its predecessor to the required start and its due is set equal to that start. Locked by the parity snapshot: A 01→03 Jun blocking milestone M0 (duration 0) — pushing A's due to 10 Jun gives M0 11 Jun → 11 Jun, duration still 0.

Zero stays zero

A duration of exactly 0 is never "recovered" into 1. Both engines used to hand back 1 here, which un-declared the milestone — and because the frontend's preview is what Apply writes, that 1 was written to Jira. A dedicated parity fixture now locks this.

A milestone-typed issue with a real span is a bar

Verified by running the engine: an issue of type Milestone spanning 3 days cascades as an ordinary 3-day task (11 Jun → 15 Jun) and is drawn as a bar, not a diamond.

A one-day task is not a milestone

The old rule "start === due and duration <= 1" turned every one-day task into an unlabelled diamond, and turned ordinary tasks into diamonds mid-drag whenever a cascade collapsed them. Only a declaration counts now.

15The order the engine settles in

Why the engine sorts topologically instead of walking successors, how a merge point is made to wait, and what happens with a dependency cycle.

Order is not a detail here — it decides the answer. A merge point that is settled before its longest predecessor reads a stale date and, in a plain depth-first walk, is never revisited. The engine therefore settles in dependency order, and there are two paths that do it slightly differently.

The two settle paths

Why each is safe

Topological order for a single edit

Kahn's algorithm guarantees every predecessor inside the affected set is settled before the successor that reads it, in one pass. A predecessor OUTSIDE the affected set cannot move, so it constrains nothing and is correctly ignored. Only the ORDER differs from a plain successor walk — the set of issues touched is identical to getAffectedChain's, so a cascade can never reach beyond the chain you edited.

Fixed-point sweeps for a full recompute

The full recompute reuses a depth-first walk, which can settle a diamond's join node early. Because the Iron-Clad cascade is monotonic (a start only ever moves later within a sweep), repeating the sweep until nothing changes converges on the same unique settled state the backend's topological pass produces. The bound exists purely so a cyclic graph cannot loop forever.

Backend ordering

The backend sorts the whole plan with edges predecessor→successor AND child→parent, so children are always calculated before the parent that rolls them up. Its INITIAL zero-in-degree queue is then sorted by Jira hierarchy level, highest first — and Jira's convention is sub-task -1, standard 0, epic 1, initiative 2+ — so epics come before stories before sub-tasks, with ties broken by key. That sort is only for determinism; correct child-before-parent ordering comes from the edges.

Merge points

An issue with several predecessors starts on the LATEST of their required starts, and only after all of them have settled. Locked by the parity fixtures: in a diamond A → B1, B2 → C where B2 is the long branch, pushing the fork root A to 10 Jun settles B1 to 11–12 Jun, B2 to 11–26 Jun, and C to 29 Jun — the next working day after B2, not after B1. A three-way fan-in behaves the same way: the join lands on 06 Jul, the next working day after the latest finisher B3's due of 03 Jul, whichever order the traversal happened to visit.

Engine limits the calculation code actually reads

16From gesture to Jira: what each edit does, and why the preview is what gets applied

Exactly what a bar drag, an edge resize and a date-editor save send to the engine, and the proof that the dates you previewed are the dates written to Jira.

Drag versus resize — they are different operations

Drag behaviour worth knowing

• The 6 px EDGE constant decides the mode; the visible ew-resize cursor strips are 8 px wide and only render when the bar is wider than 20 px.
• The bar follows the pointer as a separate preview element; the cascade runs exactly ONCE on drop, with the final dates — one ripple reveal instead of a recalculation per day-step.
• Escape during a drag cancels it and restores the original position.
• Parking the pointer near the edge of the timeline auto-pans, and the bar keeps stepping in whole days under the stationary cursor.
• Whatever duration a resize sends is recomputed on commit as the working-day span of the resulting start→due, so the stored duration always matches the bar.
• Issues moved by the cascade flash for 800 ms with a 2 px dashed #60a5fa outline, staggered by their depth in the cascaded set so the schedule visibly ripples; two edits inside that window do not cancel each other's flash.

Other ways to change the schedule

The date editor (click a bar)

Fields for Start, Due, a Duration input in days and a Buffer No/Yes toggle, a timeline summary line, the issue's dependencies under "Blocked by" and "Blocks" with a × remove button each (confirmed via a "Remove Dependency" dialog before staging), plus a Clear button and Apply / Cancel. Editing one field derives the others as you type (debounced 150 ms); on save only the fields that actually differ are sent to the engine, and Apply stays disabled until something is dirty.

Bulk set from the table

Multi-select rows and set a field once: it is applied to every selected row that has no children, in a single pass, and then the whole plan is re-settled once with cascadeAll. A loop of single edits would read stale state and only the last would stick.

Backend user-intent rules

The backend engine resolves a partial edit with an explicit decision matrix — start+due defines a WORKING-day segment (calendar days caused runaway downstream growth), start+duration computes the due, due+duration computes the start backwards, an inverted start+due collapses to a 1-day task at the start, and when all three are given and disagree the DATES win and the duration is recomputed.

Preview equals apply

Apply does not re-run the scheduler. It diffs each issue against its Jira baseline (_original) on startDate, dueDate, duration and buffer, and writes exactly those values to Jira in chunks of 10, with a delay between issues. The dates you are looking at are the dates that get written.

What the parity harness proves (95 tests over 19 plan fixtures — run and confirmed all passing)

• The frontend preview is a FIXED POINT of the backend engine — settling the applied state with the backend moves nothing.
• The frontend full recompute is likewise a backend fixed point.
• Both engines, run independently on the SAME raw plan, produce identical dates — the only test shape that can catch the two engines mishandling missing input (for example a plan with no duration field at all).
• The two frontend paths agree with each other: a full recompute does not move a settled single-edit preview, so a plan cannot change dates simply because you reloaded it.
• A regression snapshot locks the exact settled output per fixture, catching the two engines drifting TOGETHER.

Explaining a cascade

After an edit, the Cascade Impact strip summarises the ripple — "This change moved N issues", plus the finish slip, buffers absorbed and an "N exhausted" chip — and offers an "Explain" button (tooltip: "Explain what this change did") alongside Details and dismiss. Everything it shows is a deterministic DIFF of the plan before and after, plus a recomputation of the binding predecessor on the final settled map — no language model is involved, so it cannot state anything the engine did not do. It reports the number of issues moved, the plan finish before and after and the slip in working days, buffers absorbed and buffers exhausted, milestones affected and milestones slipped later, and per moved issue its old and new dates, the signed working-day deltas, and which predecessor bound it. The list shows the 40 largest movers (sorted by absolute due-date delta) and says so when it truncates; the totals are always summed over the full set first.

The advisory headline you get, first match wins

17Two worked examples

A three-link chain re-planned by one edit, and a buffer that absorbs a slip and then is exhausted by the next one — both run through the real engine.

Example 1 — one edit re-plans a three-link chain

A blocks B, B blocks C. Nothing is a buffer, nothing is a milestone, no lags. You drag A's right-hand edge from Wed 03 Jun out to Wed 10 Jun. (This is the parity fixture "three-link chain A→B→C, push A due", so the numbers below are the engine's locked output.)

Before and after

What the Explain panel reports for this edit (run and captured from the engine)

• 2 issues moved (B and C), both classified as ordinary cascade moves; rippleCount 2.
• Plan finish before 11 Jun, after 18 Jun — a slip of 5 working days.
• B's binding predecessor is named as A (due 10 Jun, lag 0); C's is B (due 15 Jun, lag 0). Both are stated with confidence because each has exactly one binding predecessor, no later-finishing predecessor exists, and the settled start equals the required start. Each moved 5 working days on both edges.
• No buffers and no milestones were touched, but the finish moved, so the headline is "Finish slipped" at CAUTION severity (the 1-to-9-working-day band). "Contained" is only reached when the finish does not move at all.

Example 2 — a buffer absorbs, then is exhausted

A blocks BUF, and BUF blocks Z. BUF has Buffer = Yes with a committed due date of Fri 19 Jun. Two successive slips are applied to A. Every figure below was produced by running the real cascade engine and its provenance/advisory layer.

Step 1 — A's due moves from 03 Jun to 10 Jun

Explain, step 1

• movedCount 1. Plan finish before 23 Jun, after 23 Jun — slip 0 working days.
• Buffers absorbed: 1. Buffers exhausted: 0. Milestones affected: 0. BUF's row records 5 days absorbed and exhausted: false.
• Headline "Buffer absorbed it" at notice severity: the buffer took the hit as intended, the finish and milestones held, and that path is now carrying less slack.

Step 2 — A's due moves again, from 10 Jun to 19 Jun

Explain, step 2

• movedCount 2 (BUF and Z). Plan finish before 23 Jun, after 24 Jun — slip 1 working day.
• Buffers absorbed: 0. Buffers exhausted: 1. The buffer's own row records 6 days given up and exhausted: true; it is counted as exhausted, not absorbed, so the same buffer is never double-counted.
• Headline "Buffer spent" at caution severity, with the compound follow-up "And it still wasn't enough: your finish moved out anyway — you're now both later AND unprotected on that path."

18The toolbars: every button

Two separate control rows sit above the timeline — the plan toolbar (shared with every view) and the Gantt's own control strip — and this lists what each button does.

LeanZero Management puts the timeline's controls in two rows. The upper row is the plan toolbar; the lower row is the Gantt-only control strip that also carries the year navigator. The split is deliberate: zoom and Critical used to live in the plan toolbar gated on the Gantt view, which made that toolbar wider in Gantt than in Table and wrapped it to a second row, so the whole header jumped every time you switched tabs. What that fix guarantees is a CONSTANT TOOLBAR HEIGHT, not identical contents: the view tabs and Assess render in all five views, but the action cluster (drafts badge, Save, Delete, Re-index, Apply) and the calendar badge are hidden in Dashboard, Schedule and Permissions.

Plan toolbar (upper row) — left to right

Gantt control strip (lower row) — left to right

Sidebar header

The sidebar header reads "Showing X of Y" — Y is every issue indexed from your JQL sources, X is how many rows are currently visible after hierarchy grouping. Collapsing a parent lowers X but not Y; the collapsed children are still part of the plan and still cascade.

Parent rollup guides (not in this strip)

The dashed vertical guide lines that drop from a parent bracket to the children driving its dates are controlled by a display preference (ppm.display.parentGuides, default on) exposed in the admin Display settings, not on the Gantt toolbar.

19Zoom, the today line, and moving around the timeline

The four zoom levels and their exact pixel scales, what the header shows at each, how the timeline range is chosen, and every way to scroll or jump.

The four zoom levels

A month label is rendered only when its block is wider than 40px (mg.count * pxPerDay > 40); otherwise the cell is left blank rather than clipping text. The "first day of the work week" is Math.min(...workingDays) — 1 (Monday) on a standard calendar, 0 (Sunday) on a Sun–Thu calendar — so week gridlines follow the plan's own calendar, not a hardcoded Monday.

Bar geometry at any zoom

Bar width

(dueX − startX) + pxPerDay — the due day is included, so a one-day task is exactly one column wide. An issue with only a start or only a due date gets a one-column bar.

Minimum drawn width

6px. A bar whose start is after its due date (a real data state) has a negative computed width and is clamped to 6px.

Row height / bar height

40px row, 22px bar (14px for a parent bracket).

Key label

Inside the bar when the bar is wider than 50px; otherwise printed just outside the bar's right edge. Nothing on the chart is ever an anonymous rectangle — the label used to be hidden outright below 50px, which is any task under 4 days at Week zoom, 11 at Month, 21 at Quarter, and every milestone.

Connector dots

Only rendered when the bar is wider than 12px.

Resize edge zones

Only rendered when the bar is wider than 20px.

How far the timeline extends

The range is not fitted to your data — it is padded by a full year on each side so you can always scroll into next year. Start = 1 January of (the earlier of the plan's earliest start year and the current year) minus 1. End = 31 December of (the later of the plan's latest due year and the current year) plus 1. With no dated issues at all it falls back to today −30 days to today +90 days before that padding. The year navigator lists every year from the range start to startYear + floor(dayCount / 365) + 1.

Ways to move

The today line and non-working days

Today line

A 2px red (#ef4444) vertical line drawn in every row at todayIndex × pxPerDay + pxPerDay/2 — i.e. through the middle of today's column. It is drawn inside each row cell at zIndex 3, so it sits ABOVE the bars (zIndex 2) and the dependency-arrow layer, and below the milestone overlay (zIndex 4) and the sticky sidebar (zIndex 5).

Today in the header

Today's day number is red and extra-bold (font-weight 800). At Week zoom, today always gets a label even if it isn't the week-start day.

Weekends / non-working days

Drawn as one repeating 7-day CSS gradient per row rather than per-week divs. It follows the plan's working-day pattern, so a Sun–Thu calendar shades Friday and Saturday.

Holidays

Amber diagonal hatching (a −45° repeating gradient) with amber side borders, plus an amber-tinted header cell with an amber underline. Hovering either shows a tooltip labelled "Holiday" with the holiday's name (or Holiday: YYYY-MM-DD if it has no name). The cursor becomes a help cursor.

20Moving a task, changing its length, and the difference

Dragging the middle of a bar translates it and preserves its working-day span; dragging an edge changes its length — and the two use different arithmetic, which matters on non-Mon-Fri calendars.

Grab a bar anywhere and drag. Where you grab decides the mode: within 6px of the left edge is resize-left, within 6px of the right edge is resize-right, anywhere else is move. The cursor changes to grabbing for a move and ew-resize for a resize. (The visible ew-resize cursor zones on the bar are 8px wide while the mode test uses 6px, so the INNER 2px of that zone — the part furthest from the edge — still starts a move. Aim at the very edge.)

What happens during a drag

1. 1The bar itself does not move. A separate translucent blue preview rectangle follows the pointer, positioned from the same geometry React uses for the real bar, so preview and committed result cannot disagree.
2. 2Floating date labels appear at the bar's edges showing the candidate dates — start for a move or resize-left, due for a move or resize-right. They flip below the bar when the bar is within 80px of the viewport top.
3. 3The drag steps in whole days: dayDelta = round((pointerDeltaX + howFarAutoPanScrolled) / pxPerDay).
4. 4Nothing is recalculated while you drag. The cascade fires exactly ONCE, on drop, with the final dates — one ripple reveal instead of a recalculation per day-step.
5. 5Press Escape at any point to cancel; the bar returns to where it was and nothing is staged.

Move vs resize — the arithmetic

Scheduling an undated issue

The hover ghost

An issue with neither a start nor a due date has no bar. Hover its row and a 5-column ghost bar follows your cursor — a translucent blue fill with a 1.5px dashed blue outline — with date labels at both ends. It refuses to appear over a weekend or holiday.

Click to schedule

Clicking the ghost schedules the issue: duration is set to 5 and the due date is 5 WORKING days after the start, inclusive (start counts as day 1). The start is passed through a next-working-day snap, though in practice that is a no-op because clicks on non-working days are blocked outright.

Gotcha

The ghost preview is 5 CALENDAR columns wide and its end label is start + 4 calendar days, but the click creates 5 WORKING days. On a Mon–Fri calendar, clicking on a Thursday shows a ghost ending Monday but produces a task ending the following Wednesday.

The date popover (click a bar)

Clicking a bar — as opposed to dragging it — opens a 320px popover anchored under the bar (it flips above and clamps horizontally near a screen edge). A drag never opens it: the click that follows mouseup is suppressed whenever the drag actually moved something. It closes on Escape or an outside click (clicks inside the date-picker's own portal are excluded).

Date popover fields

21Dependencies: drawing, deleting, and lag

How to create a finish-to-start link by dragging between two bars, what the live validation rejects and why, how to delete a link, and how to put a lag on one.

Creating a dependency

1. 1Hover the predecessor's bar. A blue dot appears just off its RIGHT edge — the tail, meaning "this blocks…". Tooltip: "Drag to create dependency (this blocks...)".
2. 2Press and drag from that dot. A rubber band follows your cursor: dashed blue while roaming.
3. 3Every other eligible bar's LEFT edge grows a green dot (the head, "is blocked by…"), and while a draw is in flight the WHOLE target bar is a drop zone — you do not have to hit the 10px dot. Parent bars are not eligible targets.
4. 4Hovering a candidate gives you the verdict BEFORE you drop. A green solid line and a green chip reading "FROM → TO" means it will be accepted; the target bar gets a green outline and glow. A red dashed line, a red chip and a red outline mean it will be rejected, and the chip names the reason.
5. 5Release to stage the link. Press Escape, or release over empty space, to cancel.

Rejection reasons shown on the rubber band

Reading the arrows

Shape

A finish-to-start cable: it leaves the predecessor's RIGHT edge moving forward and enters the successor's LEFT edge from the left, as a soft cubic S-curve through the gutters between bars. The arrowhead therefore always points INTO the target bar, even for a backward or overlapping link (which becomes an honest C-loop rather than an arrow stabbing in from the right).

Curve reach

clamp(20, max(|dx| × 0.5, verticalDistance × 0.6) + fanOffset, 130) px. It widens with vertical distance so a pair of bars in the same columns but many rows apart sweeps sideways instead of collapsing into a vertical hairline.

Fanning

When several cables share a source or a target they would all emanate from one point. Each cable's exit is spread along the source bar's right edge and its entry along the target's left edge (step = min(7, 18/(n−1)) px, nearest target outermost so cables don't cross), and each sibling's belly is nudged 14px further sideways so they fan into distinct lanes.

Depth casing

Each cable is drawn over a canvas-coloured stroke 3px wider than itself, so where two cables cross the nearer one visibly breaks the further one — a metro-map over/under read instead of a dark smear. Critical edges use a blurred violet halo instead, because a canvas casing would erase their glow.

Colours

Grey solid #64748b = the link exists in Jira. Blue dashed #3b82f6 = staged, not yet written. Violet solid #7c3aed at 3px = a critical-path edge (both ends critical, Critical mode on). Blue #2563eb at 2.5px = in the currently highlighted chain — note a staged in-chain link stays DASHED, only its colour and weight change.

Hover

A CSS rule with !important wins over the inline hover colours, so hovering ANY arrow turns it light blue #60a5fa, thickens it to 3px and adds a blue drop-shadow, regardless of whether the link is real, staged or critical.

Deleting a dependency

1. 1Click anywhere on the arrow. (Hovering it first shows a tooltip: "FROM blocks TO · staged — click to remove".)
2. 2A small chip opens at the cursor showing FROM blocks TO, with a "staged" badge if the link isn't in Jira yet.
3. 3Click "Remove link". A confirmation dialog appears: title "Remove Dependency", body "Remove: FROM blocks TO?", confirm button "Remove".
4. 4The chip closes on Escape or an outside click.

The same removal is available in two other places, and all three ask for the identical confirmation: the × next to each entry in the date popover's Blocked by / Blocks lists, and the trash button on each relationship row in the chain viewer. After a removal the app also toasts which issue is now free — either "Unlinked FROM → TO. TO is now unconstrained." or "Unlinked FROM → TO. TO still has N other predecessors." — and re-settles the freed successor, not the predecessor.

Setting a lag

Where

The same chip you get by clicking an arrow. Below the FROM/TO line it shows "Lag (working days)" with a − / value / + stepper.

Range

Whole working days, minimum 0, no upper bound. The − button is disabled at 0. A non-zero lag renders the number in the primary colour.

Effect

The lag is stored on the SUCCESSOR (predecessorLags[predecessorKey]) and the whole plan is immediately re-settled through the same pure engine used elsewhere, so you see the resulting date shifts live. Those shifts then flow through the normal staged-Apply diff.

Persistence

The lag is written to plan storage right away via the setLinkLag resolver. If that write fails, only that one edge's lag is reverted (and only if your value is still the current one, so a rapid re-drag is never clobbered), the plan is re-cascaded, and an error toast says so.

Meaning in the schedule

A successor's required start is the next working day strictly after the predecessor's due date, advanced by the lag in working days. With multiple predecessors the engine takes the maximum over all of them.

Seeing a whole chain

Hover a bar

After 160ms, the entire connected dependency component containing that issue (all transitive predecessors AND successors) lights up — bars get a blue ring and glow, in-chain arrows go blue and thicken — and everything else dims to 25% opacity. Isolated issues with no links never trigger it, and the delay stops quick scans from flashing.

Chain viewer

From the date popover's "Chain →". A modal titled "Dependency Chain" listing the chain flat, walked from its roots down through successors, with a depth number on every row below the root, a A blocks B connector line between rows, each issue's dates and duration, a Buffer/Set Buffer toggle, an orange dot for staged rows, and a trash button per relationship. The header reports "N issues in chain", plus "· M levels deep" when the chain is more than one level.

Show on Gantt

A button in the chain viewer header (only when the chain has more than one issue). It closes the modal, highlights that chain on the timeline and auto-clears after 4.5 seconds.

When it clears

On mouse-out, after the 4.5s timer, or on any bar-drag date edit — a stale glow after positions have shifted would mislead.

22The complete bar-state legend: fill and outline are two separate axes

A bar's FILL says what the issue is; its OUTLINE says how it relates to Jira. Read them independently — the combinations are meaningful.

FILL — what the issue is (first match wins, top to bottom)

OUTLINE — how it relates to Jira (applied in this order; later wins)

Because they are applied in that order, a critical bar that is also cascaded and drafted shows the violet critical outline. Parents never take any of these outlines, and neither does a milestone's bar body. While you are drawing a dependency the drop-target outline overrides all of them: a valid target takes a green 2px outline offset OUTWARD (and an invalid one a red outline), on milestones too.

Why the duration rule is written that way

A duration-only edit counts as a draft because shortening a BUFFER is the everyday case: a buffer absorbs slip by holding its due date and shrinking, so both dates still match what Jira has and the bar would otherwise keep reporting itself as synced while carrying an unapplied change. The comparison only runs when both sides have a duration, because a null the engine later filled in is the app deriving a span, not a user edit — treating that as a draft would outline every duration-less issue forever.

The Legend popover (9 items)

Other marks on a bar

Progress line

A dark 3px line along the bottom of the bar, MS-Project style, derived from status category: 100% for done, 50% for in-progress (indeterminate), nothing for to-do. Not drawn on parents or milestones.

Bar tooltip

Hovering shows KEY: summary, then start → due with (Nd) appended when a duration is set (a missing date prints as ?), then either "✓ Synced" or "✎ Draft", then "Drag to move • Drag edges to resize".

Cascade ripple

When an edit moves several bars, each moved bar's slide is delayed by its depth within the cascaded set: min(depth, 12) × 45ms, so up to 540ms. The schedule visibly ripples in dependency order rather than snapping all at once.

23Milestones, parent brackets, guide lines and baseline ghosts

The four overlay layers drawn on top of the bars: milestone diamonds, plan target markers along the top, parent brackets with their rollup guides, and the baseline ghost bars.

Milestone diamonds (issues)

A milestone issue is drawn as a 13px rotated square in the middle of its row instead of a bar — violet #7c3aed, or green #16a34a when the issue is done. The bar body behind it is transparent with no state outline and no shadow. Because a milestone is by definition a single day, its bar is only one column wide, which is always below the 50px label threshold — so the issue key is always printed just outside it.

What counts as a milestone issue

The rule

It must be a single point in time (startDate === dueDate, and a start date must exist) AND either have an explicitly declared zero duration (duration != null && Number(duration) === 0), or have a Jira issue type of "milestone".

Never a milestone

Parents (their dates roll up) and buffers (an exhausted buffer is its own violet state).

Why it is written that way

The rule used to be "start === due AND duration ≤ 1", which turned every one-day task into an unlabelled diamond and — worse — turned ordinary tasks into diamonds mid-drag, because a cascade that collapses a task to one day also collapses due onto start. A milestone is now something you DECLARE, not something a schedule change can accidentally create. A milestone-typed issue that spans real days is drawn as the bar it is.

One definition, one file

There used to be three copies of this test and they disagreed (GanttChart used duration <= 1, cascade-provenance used Number(duration || 0) <= 1 so an undefined duration read as 0, and the harness had no parent guard), so the Explain dialog could call something a milestone that the chart drew as a bar. It now lives in utils/milestone.js alone.

Target markers (plan milestones)

What they are

The named target dates defined in the plan's own metadata, not issues. They are drawn as a separate overlay across the full height of the chart at zIndex 4.

How they look

A 2px violet (#7C3AED) vertical guide line down the whole chart at 50% opacity, a small ◆ at the very top anchored on the date, and a solid violet pill carrying the milestone's name next to it.

Hover

Hovering the name pill shows name · YYYY-MM-DD.

Where they land

At dateToX(date) + pxPerDay/2 — the centre of that day's column, so the line runs through the middle of the day, matching the today line.

Parent brackets

Shape

A 14px-tall bracket, not a filled bar: a 5px slate top rail with a downward foot at each end (8 × 10px, 3px strokes).

Span

Recomputed at render time from descendants — earliest start and latest due across the whole subtree, including grandchildren. It always spans its children even on first load before any edit, regardless of what the backend stored on the parent itself.

Label

The issue key in small uppercase above the bracket — inside at the left when the bracket is wider than 60px, otherwise just past its right edge.

Clicking one

Opens the read-only rollup popover with a "Rolled up" badge, the hint "Dates roll up from this issue's children. Edit a child to change them.", and a "from KEY" chip under each date naming the exact descendant that supplies it (clicking the chip opens that issue in Jira). It has no Apply, no Clear, and no duration or buffer fields — only Close.

Rollup guide lines

What they show

Two thin dashed verticals dropping from the parent bracket's left and right ends to the specific descendants supplying the earliest start and the latest due — so you can see at a glance what is driving each end of the rollup.

Appearance

1px, dash pattern 2,3, slate at 35% opacity, ending in a small horizontal tick just below the target bar.

When they are drawn

Only when the driving descendant is currently visible BELOW the parent in the row order (a collapsed or auto-arranged-above descendant gets no guide), and on very large plans only when the guide's row span intersects the rendered window.

Turning them off

The parentGuides display preference (default on), in the admin Display settings.

Baseline ghosts and the WAS HERE marker

What they are

A hollow 1px-dashed rectangle at each issue's FROZEN baseline position, drawn behind the live bar at 70% opacity. A rightward gap between the ghost's end and the live bar's start is schedule slip, visible at a glance.

When they appear

Only for leaf issues (never parents), only when a baseline snapshot exists for the plan, and only when the issue has actually MOVED from its baseline — identical positions would add pure noise.

The WAS HERE label

Ghosts wider than 58px carry a small uppercase "was here" caption centred in the outline. Hovering any ghost gives the native tooltip "Baseline — KEY was scheduled 2026-03-02 → 2026-03-13".

Why the label exists

The ghost used to be an unlabelled transparent dashed rectangle with pointer-events off, so its tooltip was unreachable and it read as "the item moved and left an empty rectangle behind" with no way to find out otherwise.

Interaction

Ghosts are hoverable but never draggable — the live bar owns dragging. They are display-only and never touch the cascade.

Toggle

The "Baseline" button in the Gantt control strip, which only exists when the plan has a baseline. Default on, remembered across sessions.

24Critical path, auto-arrange, and the reorder suggestion

The Critical toggle and how the zero-slack chain is computed, what auto-arrange does to row order, manual drag-reordering, and the banner that offers to persist a tidier order to Jira rank.

The Critical toggle

Tooltip

"Highlight the critical path — the zero-slack chain that drives the finish date".

What turns on

Critical bars take a violet outline and glow; critical arrows go violet, thicken to 3px and gain a soft blurred violet halo; every non-critical bar dims to 40% opacity and every non-critical arrow to 20%. The button label becomes "Critical (N)".

How the path is computed

A read-only CPM pass over LEAF issues only (parents are excluded because their dates are rollups). Forward pass: earliest finish = the longest predecessor chain by duration. Backward pass: latest finish, seeded from the project end for any issue with no successors. An issue is critical when its latest finish equals its earliest finish — zero slack.

Task length used

The explicit duration when it is set and positive; otherwise the issue's date span in days (due − start + 1); otherwise 1. Without that date-span fallback every issue scheduled by dates alone would count as 1 day and the "critical path" would degenerate to whichever single node is deepest instead of the real longest chain.

Cycles

Both passes carry a cycle guard, so a circular dependency cannot hang the computation.

Auto-arrange

Default

ON, remembered across sessions (ppm.display.gantt.autoArrange).

What it does

Orders rows by a dependency-tidy topological sort — the same algorithm the reorder banner uses — then refines within families so a leaf that blocks something far away is pulled toward its family's near edge. Dependency arrows therefore point forward and stay short.

What it does NOT do

It never touches Jira rank, and the Table view is unaffected. It is a view-only preview of the tidy order; the banner is what persists it.

Hierarchy

Always preserved. Families stay grouped under their parents at every level, and root order is fixed by the base order.

Refinement guarantee

The within-family pass runs up to four barycentre sweeps scored as (backward arrows, then total arrow length). A sweep is kept only when it strictly reduces backward arrows, or matches them and cuts total length — so the base order's backward-arrow guarantee can never be traded away.

Turning it off

Gives you raw Jira rank order and enables manual drag-reordering.

Reordering rows by hand (auto-arrange off)

1. 1Press and drag a row's SIDEBAR cell (the label side). The dragged row fades to 50% and the cursor becomes grabbing.
2. 2Move over another row; the drop target gets a filled highlight and a 2px top border.
3. 3Release. Dropping below the origin stages rankAfter: target; dropping above stages rankBefore: target. A toast confirms "KEY reordered", and the whole family (the issue plus all its descendants) moves together.
4. 4The moved row flashes for about a second (1100ms), and keeps an amber row tint plus a "Moved" chip until you apply or discard the rank change.
5. 5Dropping an issue onto one of its own descendants is refused with the toast "Cannot move X into its own descendant Y" — otherwise the move would silently do nothing while still registering a phantom rank operation.

The reorder suggestion banner

When it appears

Only when auto-arrange is OFF, the algorithm has found a reorder that MEASURABLY beats the current order (scored before vs after), and you have not already dismissed that exact suggestion for this plan.

What counts as worth flagging

A dependency is flagged when it stretches more than 6 rows OR points BACKWARD. The 6-row threshold applies only to long forward arrows — a backward arrow counts at ANY gap, including two adjacent rows, because an arrow pointing the wrong way is the worst readability fault.

Why auto-arrange suppresses it

With auto-arrange on, the view already shows the tidy order, so the banner would be nagging about an underlying rank you are not looking at.

Headline

"Reorder N issues to tidy dependencies", followed by "This <win>. Families stay grouped under their parents and other plans aren't affected."

The claimed win

Reported from measured before/after scores, never asserted: "straightens N backward arrows", "brings N long arrows into view", or "tightens the chain by N rows" (the last only when neither of the first two applies).

The caveat

Shown whenever there is anything to disclose: if the reorder lengthens forward arrows in exchange it says so ("It lengthens N forward arrows in exchange"); otherwise, if long arrows remain, it says how many still remain. When neither applies — a clean win with nothing traded away and no long arrows left — no caveat appears. Two-sided disclosure by design — the banner never oversells.

Buttons

Preview/Hide, Dismiss, Apply reorder.

Preview

Lists up to 8 operations as KEY → after/before OTHERKEY, with a "+N more" line.

Apply reorder

Sorts the local issue order to exactly the verified new order and stages every rank operation for Jira, then toasts "Reordered N issues to tidy dependencies" and dismisses the suggestion. There is no imperative per-op family walk that could drift on a partial failure — the view and the staged writes agree by construction.

Dismiss

Remembered per plan in localStorage (ppm.ranksuggest.dismissed.<planId>), keyed by an order-independent fingerprint of the operation set — so the same suggestion stays dismissed, but a genuinely different one will reappear.

First-load toast

The first time a plan loads with a fixable arrow you also get a warning toast lasting 6 seconds: "A tidier row order would straighten N backward arrows — review it above the Gantt", or "…would shorten N long arrows…" when there are no backward ones. It fires at most once per plan per session, and only when there is a concrete win to advertise.

25The Cascade Impact strip and the Explain dialog

What each figure in the blast-radius strip means, where the numbers come from, and how to read the Explain dialog's "can't begin until X finishes DATE" lines.

Every date edit ripples. The Cascade Impact strip appears directly above the timeline after an edit and quantifies the ripple the engine just computed. It is strictly READ-ONLY: it never recalculates or writes anything, it only narrates what the cascade already did, so you can see the blast radius before committing.

The strip's figures

The strip's buttons

The Explain dialog

Title

"✦ Explain this change" with the subtitle "Exactly what your edit did — computed from the schedule engine, not guessed."

Nothing is generated

Every date, day-count, issue key and cause is a diff of the pre/post cascade or a recomputation of the binding predecessor on the settled map. There is no LLM in this dialog, so a wrong fact is structurally impossible.

Your edit

A plain-English restatement in one of four shapes depending on which field you touched — "You moved WFH-12's start to Mar 4 (was Mar 2 → Mar 10)", "…moved WFH-12's due date to…", "You set WFH-12 to 7d", or "You rescheduled WFH-12 to Mar 4 → Mar 12" — plus a note if your chosen date was snapped to the next working day, and the violation text if the edit was blocked.

Headline totals

Issues moved, plan finish delta with before → after dates, buffers absorbed, buffers exhausted, milestones slipped later, and milestones pulled earlier. Each is omitted when it is zero.

Per-issue rows

Key, a ◆ if it is a milestone, summary, and either "buffer exhausted", "absorbed Nd", or the signed day delta — then a WHY line underneath. If nothing else moved it says "This edit didn't move any other issues."

Cap

At most 40 rows. When there are more it says "Showing the 40 largest moves." The TOTALS are always computed over the full set, before the cap.

Footer

"These facts are computed directly from the engine's cascade — nothing here changes your plan."

Reading the WHY line

"now starts Mar 12 — can't begin until WFH-8 finishes Mar 11"

This issue's start is BOUND by that one named predecessor. It is stated as a final-state constraint, not as a chain of causation: on the settled schedule, WFH-8's due date is what forces this start.

"+ 3d lag"

Appended when that link carries a lag. The required start is the next working day after the predecessor's due date, advanced by the lag in working days.

"bound by its predecessors"

The fallback, used whenever a single driver cannot be named with certainty. It is always true and can never be wrong.

When a name is withheld

The check falls CLOSED. A predecessor is named only when (a) exactly one predecessor is binding — no tie, (b) no predecessor finishes LATER than the binding one (possible when lags differ, and "latest finisher" would then be a false label), and (c) the issue's actual start equals the computed required start, so it is a genuine fixed point and not a stale or cyclic node.

"rolled up from its children"

Used for parent rows. Parents are never assigned a driver because their dates are rollups, not constraints.

The "what this means" advisory panel

Severity — which owns the panel's colour and headline — is bound to the DATA, never to the prose, so the wording can never escalate or de-escalate the chrome. The first matching row wins and supplies the primary message; additional co-occurring damage (a finish blowout, a buffer that also hit zero, a truncated list) is appended as extra "Consider" lines rather than being dropped. The wide-ripple case has two wordings: when parents outnumber real cascaded issues it says you moved a summary and its rows came with it, rather than calling it a dependency ripple.

26Rows, hierarchy, and what happens on very large plans

Expand/collapse and what it persists, the sidebar row anatomy, and exactly what changes above 150 rows.

The sidebar row

Expand / collapse

Default

All parents expanded on a plan you have never opened. A parent that appears later (after a re-index) is added as expanded.

Persistence

Per plan, in localStorage under ppm.display.expanded.<planId>. Collapses you made survive a reload — on the first sync with a stored set, parents you had collapsed are not auto-re-expanded.

Shared with the Table

The same expansion state is owned by PlanView and drives both the Gantt and the Table view.

Animation

Newly revealed rows fade and slide in over 0.24s, and the parent row you toggled gets a brief blue highlight pulse (0.5s, cleared after 600ms).

What collapsing does NOT do

Hidden children remain part of the plan and continue to cascade and roll up. Only the row count in "Showing X of Y" changes.

Large plans — what changes above 150 rows

The threshold exists because a 5000-issue plan put roughly 95,000 row nodes in the DOM, which measurably killed scroll performance. The window is recomputed at most once per animation frame during a fast scroll, and also on mount, on row-set changes and on container resize.

27The Dashboard: what it is and where the numbers come from

How to reach the plan health dashboard, what data it reads, the guarantee that it never changes a schedule, and the six KPI tiles with their exact values.

Open a plan and click the Dashboard tab in the plan toolbar (the tabs are Gantt, Table, Dashboard, Schedule, Permissions). The chosen tab is remembered per plan in localStorage under ppm.display.viewMode.{planId} — but only for Gantt, Table and Dashboard; Schedule and Permissions are deliberately not persisted, so you never come back to a plan sitting on a config screen. There is also a command-palette entry, "Go to Dashboard". The dashboard only renders when the plan has indexed issues; with zero issues you get the "No issues indexed" empty state ("Index this plan to fetch issues from your sources.") and an "Index Now" button instead.

Everything is computed in the browser, from the loaded plan

The dashboard receives the same in-memory issues array the Gantt and the Table use, and derives every figure client-side with three pure functions imported from plan-metrics.js: computePlanMetrics, computeWorkload and computeRiskScores (computePlanMetrics in turn calls computeBufferHealth from the same file). The file's own header states the contract: "ZERO schedule mutation: nothing here writes startDate / dueDate / duration / buffer / predecessors / successors, and nothing calls the cascade engine." Nothing on this screen edits your plan or your Jira issues. The two exceptions are the explicit Set baseline / Clear buttons, which write a separate baseline record (see the baseline section).

Leaf tasks vs parents — the single most important distinction

Most metrics are computed over LEAVES, not over all issues. A leaf is any issue that no other in-plan issue names as its parentKey. The code deliberately does NOT use "has an empty children[] array", because children[] holds only Jira SUBTASKS: an Epic whose Stories are linked by parentKey would then count as a leaf and be double-counted alongside its own children in progress, risk, workload and the critical path. The plan toolbar shows both figures side by side, e.g. "45 issues · 38 tasks" (taskCount = issue count minus parent count), exactly because counting only tasks used to read as a bug. The "· N tasks" half is hidden when the plan has no parents at all, i.e. when the two numbers are equal.

The six KPI tiles

Drill-down

Clicking the On track, At risk or Overdue tile (or pressing Enter/Space on it — the clickable tiles are keyboard-focusable buttons with the title "Show {label} issues") opens a panel below the tiles titled "On-track issues", "At-risk issues" or "Overdue issues", with the hint "N issues · click to open". Each row shows the issue key, its summary and its due date (or an em dash). Clicking a row — or pressing Enter/Space on it — opens that issue in Jira's native issue modal (ViewIssueModal from @forge/jira-bridge; outside Forge it is a no-op). Clicking the same tile again, or the ✕, closes the panel. The keys listed come from the buckets object computed alongside the counts, so the list and the tile number can never disagree.

The hero band

At the top sits the plan health ring (see next section) with three lines: the label "Plan health" and its breakdown tooltip; the state word, one of Healthy / At risk / Critical; and a subtitle reading "{onTrack} on track · {atRisk} at risk · {overdue} overdue", to which " · N buffers exhausted" (singular "buffer" for one) is appended when at least one buffer is exhausted. The score inside the ring counts up on mount and the arc draws itself in over ~0.9s whenever the score changes.

28The plan health score and its exact weighting

The composite 0-100 score in the hero ring: its four components, their formulas and weights, the colour bands, and why it can never reach 0.

The formula, exactly as implemented

leaves        = max(1, leafCount)
onTime        = 1 − overdue / leaves
bufferHealth  = buffers.total > 0 ? buffers.avgHealth : 1
lowRisk       = risk.scored.length > 0 ? 1 − red / max(1, risk.scored.length) : 1
progress      = 0.5 + 0.5 × (percentComplete / 100)

raw   = 100 × (0.35×onTime + 0.25×bufferHealth + 0.25×lowRisk + 0.15×progress)
score = clamp(round(raw), 0, 100)

The four components

Bands, colour and wording

Seeing the breakdown

The info icon next to "Plan health" shows the tooltip "Weighted score:" followed by one line per component in the form "On-time 87% × 35%", "Buffer health 100% × 25%", "Low risk 92% × 25%", "Progress 70% × 15%" (each percentage is the component rounded to a whole number). The comment in the code says why it exists: the score was previously an opaque number. The raw, unrounded component values are also exposed on the hero element as the data attributes data-ontime, data-buffer, data-lowrisk and data-progress, alongside data-score and data-testid="plan-health", which is what the automated tests assert against.

29Complete % — effort-weighted, and why it disagrees with the Done count

The exact effort weighting behind the Complete tile, the status-category proxy table, and how the status breakdown donut counts differently on purpose.

Percent complete

for each LEAF issue i:
    dur_i = max(1, Number(i.duration) || 1)      // working days; missing/0 → 1
    pct_i = { new: 0, indeterminate: 50, done: 100 }[i.statusCategory] ?? 0

percentComplete = round( Σ(pct_i × dur_i) / Σ(dur_i) )     // 0 when the denominator is 0

Status-category → percent-complete proxy

Why this legitimately differs from the raw Done count

The Complete tile carries an info tooltip that states the reason verbatim: "Effort-weighted progress: each task counts by its working-day duration — done 100%, in progress 50%, not started 0%. This is why it differs from the raw done-issue count in the status breakdown below (which credits nothing for in-progress work)." Two effects stack. First, a 20-day task that is done contributes twenty times as much as a 1-day task that is done, so completing large work moves the number more. Second, in-progress work earns half credit here and zero credit in the donut. Take twelve one-day leaves, three done, six in progress, three not started: the donut reports 3 of 12 done, while the tile reads (3×100 + 6×50) ÷ 12 = 50%.

Status breakdown donut segments

Segments with a value of zero are dropped from both the ring and the legend, and each legend entry shows its own count in bold. The number in the centre of the ring is m.total — every issue in the plan — with the caption "issues". It is rendered as a bare number with no thousands separators (a 5300-issue plan reads 5300). Thousands grouping applies to the KPI tile values and to the health-score ring, not to the donut centre.

30On track, at risk and overdue — the precise test

The exact classification rule for open leaf tasks, including how 'today' is fixed, what happens to undated issues, and why done work never appears.

Classification, run over LEAF issues only

today = UTC midnight of the current UTC date (Date.UTC of getUTCFullYear/Month/Date)
due   = new Date(i.dueDate + 'T00:00:00Z')

for each LEAF i:
    if i.statusCategory === 'done'      → skipped entirely (no bucket)
    if no dueDate                        → ON TRACK
    d = round((due − today) / 86,400,000)      // whole CALENDAR days
    if d < 0                             → OVERDUE
    else if d <= 5                       → AT RISK
    else                                 → ON TRACK

onTrack (tile value) = max(0, openLeafCount − overdue − atRisk)

The three states at a glance

Drill-down consistency

The counts and the drill-down list are produced in the same loop: the buckets object stores the actual issue keys per state so, in the code's words, "the dashboard KPI tiles can drill into the matching issues". Because every open leaf lands in exactly one bucket, the three tiles always sum to the number of open leaves.

31Schedule risk — the cascade-derived RAG score

The per-issue 0-100 risk score: its four weighted inputs, the band thresholds, what the RAG bar and top-6 list show, and when the card appears at all.

The card is headed "Schedule risk" with the hint "cascade-derived · slip · chain depth · deadline · buffer depletion". Every leaf issue gets a score from 0 to 100 where higher is riskier. The function's comment states the intent: it blends baseline slip, dependency-chain depth, deadline proximity and buffer depletion — "a risk signal competitors' manual RAG dropdowns can't produce" — and it is read-only, "pure derivation, never writes a field".

The score

if statusCategory === 'done':  score = 0
else:
    slip      = max(0, dueDate − _original.dueDate) in calendar days   // 0 if either is missing
    depth     = longest chain of in-plan predecessors ending at this issue
    deadline  = 30 if overdue,  else 15 if at risk (0..5 days),  else 0
    depletion = (buffer === 'Yes') ? clamp(1 − currentDuration / originalDuration, 0, 1) : 0

    score = slip×4 + depth×3 + deadline + depletion×25

score = clamp(round(score), 0, 100)

The four inputs and what each is worth

Bands

What the card renders

A single horizontal RAG bar whose three segments are sized in proportion to the number of issues in each band (a band with zero issues renders no segment; each segment carries a "High: N" style hover title), then a legend reading "High N", "Medium N", "Low N". Under it, the highest-scoring issues: the list is sorted by score descending, cut to the first 6, and only then are zero-score rows dropped — so it shows at most 6 rows and can show fewer. Each row shows the score in a band-coloured pill, the issue key and the summary, and clicking (or Enter/Space on) a row opens that issue in Jira's issue modal.

32Buffer health — per buffer and the pool figure

How each buffer's remaining shock absorption is measured, the exact exhausted predicate, the pool average, and the colour rules of the fever chart.

The card is headed "Buffer health" with the hint "shock-absorption remaining before a date slips for real". A buffer is any issue whose Buffer field is Yes. When the cascade pushes work later it compresses buffers before it moves real dates, so a buffer's remaining length is the plan's remaining slack.

Per-buffer arithmetic

original    = max(1, Number(_original.duration ?? duration) || 1)
current     = max(0, Number(duration) || 0)
compression = clamp(1 − current / original, 0, 1)      // 0 = untouched, 1 = fully compressed
exhausted   = (buffer === 'Yes') AND Number(duration) === 1 AND startDate === dueDate
health      = exhausted ? 0 : max(0, 1 − compression)   // i.e. current / original

The pool figure

total      = number of issues with Buffer = Yes (over ALL issues, not just leaves)
exhausted  = how many of those satisfy the exhausted predicate
avgHealth  = mean(health of every buffer row)     // 1 when the plan has no buffers at all
Pool %     = round(avgHealth × 100)

Reading the fever chart

The first line is labelled "Pool" and shows one bar plus the pool percentage; that bar is drawn in the exhausted (violet, full-width) style only when at least one buffer is exhausted AND the pool average is exactly 0. Under it, one row per buffer — issue key, summary, bar, and a value that reads either "exhausted" or "{current}/{original}d" (for example "4/10d": four working days left of an original ten). Rows are sorted by health ascending, so the most at-risk buffer is always first. If the plan contains no buffers the card reads "No buffer issues in this plan."

Bar colours

33Milestone tracking

What the dashboard treats as a milestone, the four milestone states and their tests, and the slip figure shown next to each.

What counts as a milestone

The dashboard uses the shared predicate isMilestoneIssue, the same one the Gantt uses to draw a diamond. The comment explains why it is shared: the Milestone tracker used to carry its own "any single-day leaf" heuristic, and after the Gantt moved to declared-only milestones "the two views [would have been] disagreeing about the same plan". The dashboard only ever tests leaves, so the predicate's isParent argument is passed as false.

An issue is a milestone when ALL of these hold

1. 1It is not a parent (parents' dates roll up, so they can never be a point in time).
2. 2Its Buffer field is not Yes (an exhausted buffer is its own state, drawn violet).
3. 3It has a startDate and startDate === dueDate — it is genuinely a single point.
4. 4AND either its Jira issue type is literally "Milestone" (case-insensitive; the set MILESTONE_ISSUE_TYPES holds exactly that one name), or its duration is present and numerically 0. A null or undefined duration does not qualify — the code tests duration != null && Number(duration) === 0 precisely so a missing value is never mistaken for a declared zero.

Milestone states (d = due date − today, in calendar days)

Milestone slip

slip = dueDate − _original.dueDate, in whole calendar days
     = 0 when either date is missing

Displayed only when slip ≠ 0, as "+3d" (class is-late) or "−2d" (class is-early).

Each row shows a state dot, the issue key, the summary, the current due date exactly as stored (the ISO YYYY-MM-DD string, unformatted), and the slip badge. Clicking a row, or pressing Enter/Space on it, opens the issue in Jira. Each row also carries data-state, data-slip and data-date attributes for the automated tests. The whole card is hidden when the plan has no milestones.

34Baseline and variance

How to freeze a plan, where the snapshot is stored, the variance arithmetic, and the honest limits of the 'net slip' figure.

Setting one

The card "Baseline & variance" shows the hint "Freeze the current plan to track slip over time" until a baseline exists. The button reads "Set baseline" the first time and "Update baseline" afterwards ("Saving…" while in flight, with both buttons disabled); a "Clear" button appears once a baseline exists. Setting one snapshots every loaded issue as { startDate, dueDate, duration } — each field stored as null when absent — under the KVS key p:{planId}:bl together with a takenAt ISO timestamp and a count. Once set, the hint becomes "Baseline set YYYY-MM-DD · N issues tracked", where N is the number of issues the variance calculation actually matched, not the number stored.

Variance arithmetic (per issue that exists in both the baseline and the plan, and has a due date in both)

tracked += 1
d = current dueDate − baseline dueDate, in whole calendar days

if d > 0:   net += d ;  slipped += 1
if d < 0:              ahead   += 1
if d ≠ 0:   add a row {key, summary, slip: d}

rows sorted by |slip| descending, first 6 displayed

What the panel shows

A single large figure — "+14d" in red when net > 0, otherwise green — captioned "net slip · {slipped} late / {ahead} ahead", beside the six largest movers. Each mover row shows its signed slip badge (+Nd late / −Nd early), the key and the summary, and opens the issue in Jira when clicked or activated by keyboard. The panel carries data-net, data-slipped, data-ahead and data-tracked for the tests, and is hidden entirely when nothing has moved.

35Resource workload per assignee

The weekly concurrency heatmap: what a cell counts, the over-allocation threshold, the colour rules and the hard caps on what is displayed.

The card is headed "Resource workload" with the hint "concurrent tasks per assignee · red = over-allocated". The function's comment sets the boundary plainly: it "REPORTS contention (and flags over-allocation); it never reschedules anything. No resource leveling."

How the grid is built

1. 1Eligible issues: leaves only, that have an assigneeName AND a startDate AND a dueDate. Everything else is invisible to this chart.
2. 2Find the earliest start and latest due across those issues.
3. 3Week buckets start on the Monday on or before the earliest start, and step 7 days at a time while the cursor is still on or before the latest due — capped at 26 buckets (maxWeeks). Each bucket runs from its Monday to that Monday + 6 days.
4. 4Cell value = for that assignee, the number of eligible tasks that OVERLAP the week, tested as (task.start ≤ week.end AND task.due ≥ week.start).
5. 5Per assignee: peak = the largest cell, total = the sum of all cells, over = peak > 3 (overThreshold).
6. 6Assignees are sorted by total descending and the first 12 are shown (maxAssignees).

Cell colours (threshold = 3)

Labels and tooltips

Only every fourth week carries a printed label (index % 4 === 0), formatted as short month plus day-of-month ("Jun 1"). Hovering any cell gives "{assignee} · {week label}: N tasks" (singular "task" for one). An assignee whose peak exceeds the threshold gets a flag marker before their name, titled "Over-allocated".

36The two CSV exports

The Export CSV and Health report buttons: their exact columns, filenames, escaping rules, and the one column that is always blank.

Both buttons sit in the toolbar at the top of the Dashboard. Both are generated entirely in the browser and downloaded as a Blob (text/csv;charset=utf-8) via a temporary link — there is no server round trip and nothing is stored. Each file starts with a header row of the column names, then every issue in the plan gets a row, in the plan's own order, parents included and with no filtering.

Button 1 — "Export CSV" (title: "Download all issues as CSV")

Button 2 — "Health report" (title: "Download the computed health analytics (risk, buffer health) as CSV")

Filenames and confirmations

Escaping

A value is wrapped in double quotes only when it contains a comma, a double quote or a newline, and embedded double quotes are doubled — so a summary of Has, comma and "quote" is emitted as "Has, comma and ""quote""". Null and undefined become empty strings. Rows are joined with bare newlines and there is no BOM, which matters if you open the file in a spreadsheet that guesses the encoding.

37Table view: columns, the column picker and layout

The six always-on columns, the fourteen optional ones grouped into six categories, how the Key and Summary widths are derived, and exactly what persists between sessions.

The Table tab is a spreadsheet over the same plan data the Gantt draws, and it edits through the same cascade. PlanView renders the same CascadeImpact blast-radius strip — with its Explain action and clickable issue keys — directly above the grid, exactly as it does in the Gantt; the source comment there reads "Table edits cascade too — show the same blast-radius strip + Explain."

Primary columns — always shown, cannot be turned off

Optional columns — the "Columns" picker, by group

Using the picker

Click the "Columns" button in the table toolbar. A dropdown lists the fourteen optional columns under their six group headings; each is a toggle button with a check box and aria-pressed state, and the Columns button carries a badge with the number of extra columns currently on (the badge is hidden at zero). The dropdown closes on an outside mousedown. Enabled columns are appended to the right of the six primary ones, in the order listed above (the picker order), not in the order you clicked them.

Key column auto-width

maxDepth   = deepest visible tree depth (forced to 0 while grouped)
longestKey = longest issue key length in the plan

width = max(90, 14 + ceil(longestKey × 7) + 24 + maxDepth × 14)

(a plan with no issues at all simply uses 90)

The reason is given in the code: without it, "deeply-indented keys wrap to two lines and make the whole row look crammed". Each tree level indents by 14px (TREE_INDENT). Grouping removes indentation entirely and reclaims that width.

Summary column resize

Drag the 5px handle on the right edge of the Summary header (it highlights in the primary colour on hover). The minimum is 120px. Until you drag it, the column is elastic (minmax(150px, 1fr)); once dragged it becomes a fixed pixel width. The whole grid has a minimum width of 36px (the checkbox column) plus the sum of all column widths, using 250px for Summary when it has not been resized — below that the table scrolls horizontally.

What persists, and where

38Table view: sorting, the quick filter and group-by

How sorting interacts with the tree, exactly what the filter matches and why it keeps ancestors, the seven grouping fields with their labels and colours, and how the row counter behaves in each mode.

Default order

With no sort and no grouping, rows are in tree order: a depth-first walk where parents precede their children, sibling order at every level follows the plan's own issue array (Jira LexoRank, per the code comment), and children of a collapsed parent are not rendered at all. Each row is indented 14px per level; parents get a rotating chevron, non-root leaves get a ↳ branch mark, and root-level leaves get a blank 14px spacer so the keys still line up.

Sorting

1. 1Click any column header — including Key and Summary — to sort ascending; click the same header again to flip to descending. Headers are also keyboard-activatable with Enter/Space. The arrow ▲ / ▼ shows the active column and direction, and aria-sort is set for screen readers.
2. 2Sorting switches the grid from tree order to a FLAT list of every issue. Indentation is kept so depth is still readable, but collapsing is not applied — children of a collapsed parent reappear while sorted. The code states the reason: otherwise "children would vanish on sort".
3. 3Rows with no value in the sorted column (null, undefined or empty string) always sort LAST, in both directions. The comment explains: sorting by a column "should surface the rows that HAVE a value, not bury them under ~100 blank rows".
4. 4Two numbers are compared numerically; everything else is compared with localeCompare on their string form. Array columns (Blocked By, Blocks, Labels) therefore sort by their comma-joined text, e.g. "LZPT-4,LZPT-9".

The quick filter

The search box in the toolbar has the placeholder "Filter tasks…" and matches a case-insensitive substring against the issue KEY or the SUMMARY only. No other field is searched, and there is no syntax — it is a plain contains test on the trimmed text. A × button (title "Clear filter") appears once you type. When nothing matches, the grid is replaced by "No tasks match “your text”" plus a "Clear filter" button; with no filter text an empty grid instead reads "No tasks match the current view" and offers no button.

Group-by options (the "Group" dropdown — a custom Select, not a native one)

How groups are ordered and labelled

Groups are sorted alphabetically by value (localeCompare), except Priority which uses the rank Highest, High, Medium, Low, Lowest with any unrecognised priority ranked after those, and except the empty bucket which is always sorted LAST. A Parent group is labelled "KEY · first 40 characters of the parent's summary", resolved from the full unfiltered issue list so the label still works when the parent row itself is filtered out; if the parent is not in the plan at all the label is just the key. Rainbow colours cycle through a fixed ten-hue palette by group index (#2563eb, #a855f7, #f97316, #16a34a, #e11d48, #0891b2, #d97706, #7c3aed, #059669, #db2777).

Behaviour while grouped

Each group is a full-width header row with a chevron, the colour chip, the label and a count badge; clicking the header (a real button with aria-expanded) collapses or expands that group. The tree dissolves: rows appear in the plan's flat LexoRank order within each group, indentation is dropped, parent chevrons disappear and the WBS column shows an em dash — "WBS is a tree positional outline — meaningless once regrouped". Changing the group field resets all collapsed groups. The "Show children" expand-all toggle is hidden while grouped.

What the row counter (top left) says

39Table view: selection, bulk edit, inline editing and the chips

Multi-select and the bulk buffer bar, the exact arithmetic behind inline date and duration edits, what the amber cell background means, and the meaning of every status, priority and buffer chip.

Multi-select

1. 1Each leaf row has a check box in the leading 36px column. PARENT rows have no check box at all — dates and buffer are rolled-up or leaf-only concepts.
2. 2The header check box (title "Select all visible rows") selects or deselects every currently selectable row, and shows an indeterminate state when only some are selected. "Selectable" means: visible after the filter, not inside a collapsed group, and not a parent.
3. 3Select-all only unions or subtracts the CURRENTLY selectable keys. Selections in filtered-out or collapsed rows are preserved untouched — the comment calls this "never a surprise".
4. 4While grouped, each group header carries its own check box scoped to that group's leaf members (hidden entirely for a group with no leaves).

The bulk bar

As soon as one row is selected, a floating bar appears fixed at the bottom centre reading "{N} selected", then "Set buffer" with a "Yes" and a "No" button, then "Clear". Those two buttons are the only bulk actions in the table. Applying one writes the buffer field to every selected key in a SINGLE pass followed by a SINGLE full-plan cascade — the code is explicit that this is not a loop of individual edits, because such a loop "closes over stale issues and only the last would stick". Issues that already hold the target value, and any issue that has Jira subtasks (a non-empty children array), are skipped; if that leaves nothing changed, no cascade runs at all. The selection is cleared afterwards.

Inline start / due date editing

1. 1Click a Start Date or Due Date cell on a leaf row; a date picker opens over the cell. Parent cells show the tooltip "Rolled up from children" and do not open. An empty date cell reads "Click to set" on a leaf and an em dash on a parent.
2. 2When you pick a date, the app also fixes up the other two fields: if a start and a duration exist but no due date, dueDate = the start pushed forward to the next working day, then advanced by duration working days — the helper is 1-indexed, so a duration of 1 means start = due.
3. 3If both dates are now known, duration is RECOMPUTED as the count of working days between them, inclusive, with any falsy result (0) replaced by 1.
4. 4The change is then handed to PlanView, which runs the iron-clad rule and the buffer cascade from that issue — a table edit propagates through successors exactly like a Gantt drag and feeds the Cascade Impact strip and the Explain panel. The ~800ms row flash, though, is a Gantt-only affordance: table rows never flash. In the Table the visible feedback is the Cascade Impact strip above the rows, plus the amber staged background on every cell the cascade changed.

Inline duration editing

1. 1Click a Duration cell on a leaf row to get a numeric input with a "days" suffix; the existing value is pre-selected. Only digits and Backspace, Delete, ArrowLeft, ArrowRight, Tab, Enter and Escape are accepted — other keystrokes are swallowed.
2. 2Enter commits (by blurring), Escape cancels, and clicking away commits.
3. 3An empty value is allowed and clears the duration (unscheduling the task). A non-empty value that is not a positive integer — 0 or garbage — is REJECTED silently and the cell reverts, because "a scheduled task can't be 0 days, and setting 0 left a stale due date".
4. 4On a valid value, if the issue has a start date the due date is recomputed as the start (pushed to the next working day) plus N working days, and the cascade runs.

Buffer cell

On a leaf, the Buffer cell is a one-click toggle between Yes and No, which also triggers the cascade. On a parent it shows an em dash with the tooltip "Buffer is a leaf-task setting".

Status chip

Priority chip (all solid fills with white text — no faded tints)

The other cell renderings

40Staged, saved, applied — the three states of an edit

The core mental model: edits live in your browser, then in the app's own storage, and only reach Jira when you Apply.

Every change you make in the timeline or the table happens in your browser first. Dragging a bar, typing a date, drawing a dependency arrow, deleting one, dragging a row into a new position — none of it contacts Jira. An edit passes through three distinct states, and only the third one writes to a Jira issue.

The three states

Two counters, two different baselines

The toolbar shows two numbers and they are not measuring the same thing. This is the single most common source of confusion.

Save (N)

Issues whose fingerprint differs from the last storage checkpoint. The fingerprint is startDate|dueDate|duration|buffer|predecessors|successors. When N is 0 the button is disabled and reads "Saved".

Apply N changes

Issues whose startDate, dueDate, duration or buffer differ from _original — the values Jira held when the plan was last indexed — plus every staged new dependency, removed dependency and rank move. The button only appears when this total is above 0.

The one exception: link lag

Setting a finish-to-start lag on a dependency arrow is not staged. It updates the plan immediately (setLinkLag writes straight to the plan's lag map at p:{planId}:deps), re-settles the schedule locally with the same cascade engine, and if that write fails the app reverts just that one edge and tells you: "Couldn't save lag: … — reverted." The revert is surgical — it is skipped if you have since changed the same edge again. Lag never reaches Jira at all, because Jira issue links carry no lag; it is app-private data stored in its own key so a re-index cannot wipe it. The date shifts the lag causes do flow into the normal Apply diff.

41What Save writes, and what it deliberately refuses to write

Save checkpoints four scheduling fields into the plan's own storage — never into Jira, and never the dependency graph or the Jira baseline.

Save calls savePlanState and sends a deliberately minimal payload: for each changed issue, exactly four fields. Everything else in your in-memory issue object is withheld.

The complete Save payload, per issue

On the server these four values are merged into the stored issue row ({ ...issue, ...patch, key: issue.key }). The rest of the row — summary, status, hierarchy, children, dependency lists, the Jira baseline — is left exactly as the indexer wrote it.

Three things Save refuses to send, and why

• predecessors / successors. A dependency you have only DRAWN does not exist in Jira yet. Writing it into plan storage produced a graph that was part real and part fiction; a partial re-index after an Apply only refreshes the date-changed keys, so the phantom edges survived, got baked into the next baseline, and then rendered as staged arrows that could be neither applied nor discarded.
• _original, the Jira baseline. Save used to overwrite it with the frontend's normalised duration. The external-conflict check compares that baseline against raw Jira, so on any plan without a PPM Duration field it then reported a phantom "Duration changed in Jira" conflict and aborted the entire Apply.
• predecessorLags. Lags are denormalised onto issues when the plan loads, but deliberately live in their own storage key so that a re-index cannot wipe them. Round-tripping them through Save would defeat that.

What one Save does

1. 1The Save button flashes and shows a spinner with "Saving...".
2. 2savePlanState merges the four fields into the plan's issue shards, running at most 5 shard writes concurrently.
3. 3The local checkpoint (kvsSnapshot) is rebuilt from the issues as they are at that moment, so the Save (N) counter drops to 0.
4. 4The plan's version number is incremented by 1. Nothing is broadcast — another tab picks the change up on its next version check, which runs when you switch views.
5. 5Toast: "Saved N issues to plan".

The "saved X ago" indicator

Once everything is saved, the toolbar shows a green tick and a relative time next to the Save button: "just now" under 5 seconds, "Ns ago" under a minute, then "Nm ago". It is recomputed every 10 seconds and is hidden while there are unsaved changes or a save in flight.

42Drafts — your unsaved work, and everyone else's

A per-user autosaved draft keeps unsaved edits across reloads and re-indexes, and makes other people's work-in-progress visible.

A draft is not the same thing as a Save. Save is the plan's shared checkpoint; a draft is your private copy of the edits you have not checkpointed yet. It exists so that a reload, a re-index, or the hourly background refresh cannot silently throw your work away.

Draft mechanics

Why Re-index does not ask you to confirm

Re-index pulls fresh Jira data for the plan and resets the local checkpoint, which re-arms the draft overlay — your unsaved edits are re-applied on top. That is why the Re-index button has no "you will lose changes" confirmation: a mis-click cannot lose edits. A genuine clash with Jira surfaces later, at Apply, through conflict detection.

Other people's drafts

A warning-bordered banner appears under the toolbar whenever anyone else has an active draft on this plan: "N active drafts", each person's display name with their issue count in brackets, and a total ("· 12 total issues affected"). The toolbar also carries a "N drafts" badge. Both count other users only — the server excludes your own account from the list before it is returned.

Stale drafts

When someone applies changes to Jira, every other user's draft that touches any of the written issues is flagged stale, with a reason recorded ("Issues were written by another user at …"), and the registry entry is flagged too. A stale draft is never overlaid on load — the overlay function returns the issues untouched when draft.stale is set — so you are not silently re-applying edits that were computed against superseded dates.

43The Review Changes dialog

The confirmation gate before anything reaches Jira: every pending change listed, individually tickable, with Discard All as the escape hatch.

Pressing "Apply N changes" does not write anything. It opens the Review Changes dialog, which is the complete manifest of what is about to be sent. The subtitle reads "N changes will be written to Jira", followed in orange by "(M discarded)" once you untick anything. If the dialog is somehow opened with nothing pending, it closes itself rather than stranding you.

The four sections, in order

How a date diff is rendered

Unticking a row

Every row has a solid blue tick box (red for removed dependencies). Clicking it drops that row to 35% opacity and removes it from the count in the Apply button. The button label tracks live: "Apply 12 Changes", and it disables itself when you untick everything.

Discard All

The red "Discard All" button in the footer throws away every pending change at once and, unlike unticking, persists that decision.

What Discard All does

1. 1Reverts every listed issue's startDate, dueDate, duration and buffer to its _original Jira baseline in the view.
2. 2Clears all staged links, unlinks and rank moves.
3. 3If at least one date change was reverted: writes the reverted values back through savePlanState, updates the local checkpoint for those keys, and deletes your draft. (With only links or ranks staged there is nothing to write back, so this step is skipped.)
4. 4If any staged unlink was discarded, reloads the issues from plan storage so the removed arrow reappears and the freed successor re-pins correctly.
5. 5Toast: "All changes discarded".

The other footer buttons

Review with AI

Only shown when AI is enabled for the site (checked via getAiConfig when the dialog opens). Runs an advisory semantic pass over exactly three checks — semantic precedence conflicts, unrealistic compression, missing intended dependencies — and layers its results above this dialog. It is never a gate — you can always apply regardless of what it says, and it changes nothing in your plan. The footer of that modal shows a CACHED · 0 tokens pill when the result was reused, the model name, and input/output token counts; when a daily or monthly cap is hit it says so explicitly ("Daily AI review limit reached", with used-of-cap and "You can still apply").

Cancel

Closes the dialog and keeps everything staged. Escape does the same — unless the AI review is open on top, in which case Escape belongs to that modal.

Apply N Changes

Confirms. From here on, the write path in the next section runs.

44Apply — what actually happens to your Jira issues

The full write sequence: lock, conflict pre-check, chunked field writes, verification, re-index, unlock — plus the separate path for link and rank changes.

Confirming the Review Changes dialog starts one of two write paths, depending on whether your change set contains any date changes.

Which path runs

The date write, step by step

1. 1startWrite: your plan role is checked (editor, owner or admin required — a viewer is refused here, and since every chunk requires holding the lock, a refused user cannot write at all). Your real display name is resolved server-side from Jira so the lock overlay names you correctly. The write lock is acquired and the plan status is set to "writing". A lock:acquired event is published.
2. 2Conflict pre-check (first chunk only): every issue in the change set is re-fetched from Jira live and compared with the baseline you started from. Any difference aborts the whole apply before a single field is written, releases the lock, and returns the conflicting issues.
3. 3Field filtering: the app reads Jira's edit metadata for the first issue in the chunk and drops any field that issue cannot accept.
4. 4Writing: issues are written 10 at a time, one PUT per issue, with a 250 ms pause between issues inside a chunk. After each chunk the lock TTL is refreshed and a write:progress event is published for observers.
5. 5Verifying: every written issue is re-fetched, parsed with the same transformer the indexer uses, and compared against the values you intended to write.
6. 6Re-index: the written issues are refreshed from Jira into plan storage, your draft is deleted, other users' overlapping drafts are flagged stale, the plan version is incremented and the lock is released. lock:released and plan:version events tell everyone else to refresh.
7. 7The modal shows "Applied" for about 1.1 seconds and dismisses itself; the plan reloads in place without the timeline jumping.

Exact fields written to Jira

Write pacing and retry

The link and rank pass

Links, unlinks and rank moves are written one item at a time in a fixed order — new dependencies first (they often inform the rank decisions), then removed dependencies, then rank moves — with the current operation named in the modal ("PROJ-1 → PROJ-2", "✕ PROJ-3 → PROJ-4", "PROJ-5 after PROJ-6"). A dependency is created as the configured link type (default "Blocks") with the predecessor as the blocker, and the app also updates the stored predecessor/successor lists so the edge reads as real after a reload. Deleting one first looks up the link id on the predecessor issue, and reports "Link not found" if the link is no longer there; a removed edge also has its stored lag cleared so a re-link doesn't resurrect it. After the rank pass, refreshRanks updates the stored rank values so the timeline shows the new order on reload.

45When a write fails partway

There is no rollback: issues already written stay written. What the app does instead is keep the rest recoverable and never lie about success.

Failure modes and what each one does

Retry semantics

The Retry button re-runs the whole sequence from the beginning: it re-acquires the lock and re-writes every issue in the change set, including ones that already succeeded. Re-writing the same date values is harmless. Note that when a run ends in the error phase, the plan is NOT reloaded — your edited timeline stays exactly as it was on screen, which is what makes an immediate retry possible.

After a mixed run

When the date pass completes but some links or ranks failed, the toast reads "N link/rank changes couldn't be written to Jira — still staged, Apply again to retry". (The differently worded "Applied N · M couldn't be written to Jira — still staged, Apply again to retry" belongs to the link/rank-only path, which has no date pass to report.) Either way the plan then reloads: successfully written issues come back with a fresh baseline (so they no longer count as changes), and anything still staged still counts, so the Apply button reappears with just the remainder.

46The write lock and what other people see

One writer at a time per plan, for a maximum of five minutes, with a live progress bar and an auto-unlock countdown for everyone else.

A date apply takes an exclusive write lock on the plan before touching Jira, so two people cannot write over each other. The lock record holds the holder's account id, their display name resolved from Jira, a timestamp, a unique token and an expiry.

Lock behaviour

What the other user sees

Anyone else on the plan gets a dimmed, blurred overlay across the plan content area with a lock icon and the heading "Plan is being written", then: "<name> is writing changes to Jira tickets. Editing is temporarily disabled." Below it is a progress bar. If write progress events are arriving it is a real bar with "12 of 60 written · 20%"; otherwise it is an indeterminate bar. Underneath, a live countdown ticking every second: "Plan unlocks automatically in 4:12", then "Unlocking…". A Refresh button re-polls the lock and draft state on demand. The overlay never renders for the lock holder themselves.

Side effects on the plan while writing

The plan's status is set to "writing" for the duration. The hourly background refresh skips any plan whose status is "writing" or "indexing", so a scheduled re-index cannot land in the middle of your apply.

47Conflict detection — when an issue changed in Jira while you were planning

Two separate checks with different scopes: a local pre-check that can be over-eager, and a live Jira comparison at write time that aborts the whole apply.

Both checks look at the same four fields — Start Date, Due Date, Duration, Buffer. Changes to summary, status, assignee or anything else are ignored entirely and never block an apply.

The two checks

The Conflicts Detected dialog

Headline: "N issues have been modified by other users since you started editing." Each row shows the issue key, the field label, and the old value struck through with an arrow to the current value in red. Empty values render as "(empty)", and anything that looks like a date is formatted short. You must tick "I understand that my changes may override the external modifications listed above" before the Apply Anyway button becomes usable.

Your three options

Cancel

Closes the dialog. Nothing is written, everything stays staged. Escape does the same.

Re-index Plan

Runs the same re-index as the toolbar button: fresh Jira data for the whole plan, with your unsaved edits re-overlaid from your draft on top. This is the option to take when you want to see the other person's change before deciding.

Apply Anyway

Proceeds with the write. Your values overwrite whatever is currently in Jira for the fields you are writing.

48Live presence, live updates, and the polling fallback

Who else is on the plan, how changes from others reach your screen, and the honest Live / Polling indicator when the live channel is unavailable.

At the left of the toolbar's action group — ahead of the drafts badge, Save, Delete, Re-index and Apply — sit two things: a connection pill and a cluster of avatars. Both are read-only awareness; neither changes any data.

The connection pill

What each live event does to your screen

Presence

Your client sends a heartbeat every 30 seconds, carrying which view you are on, plus an extra beat immediately when you switch views. The server prunes anyone whose last beat is more than 90 seconds old. Leaving is sent on both pagehide and beforeunload so a closed tab drops out promptly rather than lingering for the TTL, and returning to a backgrounded tab re-beats immediately. The avatar cluster shows up to 5 people, most recently active first, and then "+N"; hovering names each one, marks yourself "(you)" and shows the view they are on. Each person gets a ring colour derived deterministically from their account id, so the same person is the same colour for everyone, across sessions. The cluster is hidden when you are the only person there.

49Plan protection, and how to undo an apply

The one place the app writes to Jira without you asking — and the honest answer that there is no undo button.

Plan protection

Plan protection is the only path where the app changes a Jira issue without anyone pressing Apply. It runs from the Forge trigger on avi:jira:updated:issue and exists to stop ad-hoc ticket edits from breaking a plan's dependency structure.

What it checks, in order

1. 1The update must include a date field change; anything else is ignored immediately.
2. 2The issue must belong to a plan that has protection enabled.
3. 3The issue must have at least one predecessor. Unblocked issues are never protected.
4. 4The changelog must contain a START date change.
5. 5Required start is computed as the maximum, over all predecessors, of the lag-aware next working day after that predecessor's due date — the same rule the scheduling engine uses, so a legitimately lagged link is not punished for landing later than bare adjacency.
6. 6If the new start is earlier than that required start, the change is reverted and a comment is posted.

What the revert does

It writes the previous start date back (and the previous due date too, if the due date was changed in the same edit) and posts a plain-text comment on the issue headed "⚠️ LeanZero Management: Date change reverted". The comment names the blocking issues, the latest predecessor due date, the earliest allowed start date, the start date that was requested, a one-line statement of the Iron Clad Rule, and the plan name — then points the user at the plan view, where changing the date will cascade to dependents properly instead of being rejected. Both the revert and the comment are made as the app, but only the revert suppresses notifications (the write goes out with notifyUsers=false). The comment is posted as an ordinary comment — the comment endpoint has no suppression parameter — so Jira's normal comment notifications to watchers still go out, which is in practice how the person whose edit was reverted finds out.

Undoing an apply

There is no undo. Nothing in the app stores a pre-apply snapshot of Jira values that can be restored, there is no revert or undo resolver anywhere in the API surface, and no revert path in the write flow. The moment an apply completes, the re-index makes the written values the new baseline for the plan.

What to do instead

• Before applying: Discard All in the Review Changes dialog is your real undo. It reverts the view, clears every staged link, unlink and rank move, and persists the revert.
• After applying: recover the previous values from Jira's own issue history (the change log on each ticket shows the app's write and the value it replaced), then set them back in the plan and apply again. Re-index first so you are editing against current Jira data.
• Do not rely on a baseline snapshot for this. A baseline freezes planned start, due and duration into a separate key purely so the timeline can draw ghost bars for variance — it is display-only, it never enters the write path, there is no restore-from-baseline action (only get, set and clear), and it is capped at 2000 issues.
• For links and rank moves there is no history to recover from beyond Jira's own issue activity: re-create the link or drag the row back, then apply.

50Roles, the capability matrix, and how a role is decided

The five roles LeanZero Management recognises, exactly what each one can do, and the precise order in which the app decides which role you have for a given plan.

Access is decided per plan, not per project. Every plan carries its own owner, its own member list and its own default access level, all stored in the plan's metadata record (p:<planId>:meta). There is no global "can use the app" role beyond Jira's own app access.

Capability matrix

The four capability predicates, verbatim

canView(role) = role !== 'none'. canEdit(role) = admin, owner or editor. canDelete(role) = admin or owner. canManagePermissions(role) = admin or owner. There is no separate "apply to Jira" capability — applying is gated by canEdit, the same predicate as editing dates in the timeline.

Role resolution order (resolveRole), first match wins

1. 1Jira site/org/app administrator → admin. Determined by GET /rest/api/3/mypermissions?permissions=ADMINISTER called as the user; any error returns false, so the check is fail-closed.
2. 2Your accountId equals the plan's createdBy → owner. The comparison is guarded so that a plan whose createdBy was lost (undefined) plus a caller with no accountId does not accidentally resolve to owner.
3. 3You appear in the plan's members array → the role recorded on that member entry (viewer, editor or admin).
4. 4You appear in the legacy editors array (plans created before the members model) → editor.
5. 5Otherwise the plan's defaultAccess value is your role — none, viewer, editor or admin.
6. 6Legacy plans with no defaultAccess field at all: viewer if they have an editors array, otherwise none.

Plan visibility (defaultAccess) — the dropdown on the plan's Permissions tab and on Settings → Plan Permissions