---
name: "convention-decision-log"
type: convention
description: The tool-agnostic standard for the decision log — what it records, the index-plus-weekly-child-documents structure, the entry format, and the lifecycle (append newest-first, one entry per decision, update rather than leave a stale one). Read whenever recording or organising a consequential decision. The discipline holds even if the tracker changes; convention-linear maps it onto Linear documents. Grown as the format solidifies.
license: CC BY-NC-SA 4.0
---

# Decision log

How consequential decisions are recorded so the reasoning survives the session that made it. Stated independently of any tracker, so it survives a change of tool — `convention-linear` is the tool layer that maps this onto Linear documents. The failure mode is silent: a decision made in chat and never logged does not persist, and the next session re-litigates it or contradicts it.

## What it records

A decision log captures every **consequential architectural, structural, or scope decision** — what was decided, why, and what changes as a result. Not every choice: a reversible, low-blast-radius call does not need an entry; a decision that future work will depend on, or be confused by if it is missing, does.

Logs are **scoped per domain**, one log per project/area, sharing this format:

- `osclaude.log-decisions` — how Claude is operated (skills, routines, the delivery loop, the conventions).
- `osdashboard.log-decisions` — the os.Dashboard operating-system dashboard project (stood up 2026-08-12, listed here same day — APP-834).
- `build.log-decisions` — careerOS infrastructure and build.
- `app.log-decisions` — AI-behaviour experiments.
- `bottrader.log-decisions` — the bot.Trader vertical. **One log for the vertical, not one per mandate**: it covers both Mandate A (the platform and its validation gauntlet) and Mandate B (the bot.Trader-B agent). Separate *reporting* lines do not imply separate logs, and a single log is what lets a decision taken on one path be read against the other (stood up 2026-08-09, listed here 2026-08-10 — APP-749).
- `mbn.log-decisions` — the Made by — Neud site and storefront.
- `a1-<client>.log-decisions` — one log per A1 client engagement (see *Slug naming* below).
- `a1-<property>.log-decisions` — one log per non-client A1 sub-account property, on the same hyphenated stem (e.g. `a1-aledpritchard.log-decisions` for aledpritchard.com).

A vertical without an entry here has no log of its own — BARA is the current case — and its decisions are logged wherever the work sits. Do not assume a log exists because a vertical has an operator; check, and stand one up under the new-domain rule below if it should.

**Standing the log up is part of standing the property up, not a later tidy.** `playbook-client-onboard` creates a log per client engagement, and nothing does the equivalent for a non-client property, so each one gets its log only when a session happens to notice the absence. Create the index and the current-period child at the point the property's Linear project is created, and add the stem to the list above in the same action where that list does not already carry a pattern bullet covering it. A property with no log is invisible to `skill-coordinate` Pass 6 in both directions — there is no log to read for a decision that commissioned work, and no log to diverge from later. (Worked case: a1.assoc-one is a live `started` project whose `NEXT_PUBLIC_SITE_MODE` architecture call, `.vercelignore`-versus-delete decision and open site-scope question sit only in ticket bodies and comments, with `list_documents` returning zero — APP-1407.)

## Slug naming

A log's slug is composed from its vertical's **registered stem** — `<stem>.log-decisions`, with weekly children `<stem>.log-decisions.YYYY-Www`. The stem registry, the hyphenated `a1-` rule for A1 sub-accounts and their non-client properties, the case rule, and the reconciliation list of live logs that predate the form all live in **`convention-naming`**, which rules every name above the canon-artefact line. Read them there, not here.

The section that used to sit in this place was a naming convention that had grown inside a log convention because there was nowhere else to put it, and a rule held in two places drifts in two directions. Nothing was dropped in the move: the `a1-` stem and its sub-account reading, the established stems, and the three logs recorded as **observed, not reconciled** are all carried in `convention-naming` (APP-1381).

**Registering the stem is part of standing the log up, not a later tidy** — a live log missing from `convention-naming`'s registry is invisible to anyone reading canon to find out where a decision belongs (worked cases: `bottrader.log-decisions`, APP-749; `osdashboard.log-decisions`, APP-834). And a session looking for a log whose name is on that reconciliation list should **search the project rather than compose the conventional slug**, because those names have not been reconciled and renaming a live log is the Owner's call, not a drain's.

**The search comes before every log write, not only before a name on the reconciliation list.** The clause above scopes the search to that list, which leaves the ordinary case — a conventionally-named log on a registered stem — reachable by composing the slug and creating it, and a composed slug collides silently: Linear does not enforce unique document titles, so the create succeeds, the project carries two indexes under one name, and each index links only the weekly children its own session made. The cost falls on whichever index a reader finds first, which is the newer one on an `updatedAt` listing, so the older entries go unread rather than contradicted. So list the owning project's documents and filter on **exact title equality** before creating an index or a weekly child — the project-scoped, cursor-paged lookup `convention-linear` prescribes in *Find a document by exact title*, never a first-page `query` result, whose miss never proves absence — and where the listing returns an existing log, write into it. Where two already exist, the merge is a restructure of a live decision record and is the **Owner's** action, named and never taken by a drain. (Worked case, verified by a read-only `list_documents` on the owning project: a1.Advisory holds two documents titled `a1-advisory.log-decisions` — one created 2026-09-12T10:37Z, whose index lists `2026-W37`, `2026-W44` and a `2026-W45` child, and one created 2026-11-03T16:17Z, whose index lists a second `2026-W45` child that was still taking entries on 2026-11-05 — so a reader of the newer index never reaches the older weeks. `APP-2899` dates both indexes to 2026-11-03; 12:26Z is the older index's `updatedAt`, not its creation, so the older log is two months old with three weekly children and the duplication is worse than filed. The per-child entry counts are as reported on that note — `APP-2899`.)

**The listing is workspace-wide by exact title, not project-scoped, because a log is defined by its own name and not by the project a session happened to be working in.** The rule above sends the search to the owning project — the lookup `convention-linear` prescribes in *Find a document by exact title* is `list_documents(projectId: <owning project>, …)` — and that lookup cannot collide on a twin filed in a **sibling project** at all: the listing returns clean, the create succeeds, and the miss is invisible to the session that made it. One log per property is the point of `a1-<property>.log-decisions` above: the name fixes the log, so two sessions working in two of a property's projects compose the same slug and each creates its own index under the project in front of it. So list by **exact title across the workspace** before creating an index or a weekly child, filter client-side on exact title equality as before, follow `cursor` until `hasNextPage` is false, and treat a hit in any project as the log — write into it where it stands, rather than a second copy under the project at hand. This is the same shape as `skill-ops-retro`'s rule that the Pulse queue is read by its `PUL-5E` label across the workspace and never by project: the label is the queue's definition, the title is the log's, and a project-scoped read is clean on both misses. (Second instance, verified by a read-only `list_documents` across both of the property's projects: aledpritchard.com holds two documents titled `a1-aledpritchard.log-decisions`, one in `aledpritchard.com · Site & presence` and one in `aledpritchard.com · Launch build`, plus two `a1-aledpritchard.log-decisions.2026-W45` children, one under each project, so a reader of either index never sees the other's entries — `APP-3167`. The first instance, `APP-2899`, was closed Done on 2026-11-06 and its a1.Advisory duplication is **still live on the board** — two indexes and two `2026-W45` children — so the earlier fix demonstrably did not hold. This clause does not change the merge: it remains a restructure of a live decision record and the **Owner's** action, named and never taken by a drain.)

## Structure — index plus weekly child documents

A log is an **index** plus **child documents**, not one ever-growing page:

- The **index** holds this purpose, a **pointer to this artefact's Entry format** rather than a copy of it, and a table listing the child documents, each linking to one. It is the scannable front page. **The pointer is the mechanism; a copy of the format is a second source of truth and has no detector.** A writer appending to the week's child reads the index, because the index is the document in front of it — so a format block reproduced inside the index governs in practice while this artefact governs on paper, and the two drift with nothing mechanical to disagree: no digest, no count, no arithmetic for a later pass to trip. The index's format section therefore names this artefact as canon and reproduces no field lines of its own — the same wrapper discipline canon already applies to a scheduled task's loader config, where the artefact is canon and the config does nothing but read it. (Worked case: `osclaude.log-decisions` carried its own copy of the Entry format block, one revision behind this artefact's Impact field, which additionally requires that the open tickets a decision supersedes be named and reconciled — repointed, re-scoped, or waived. The entries filed that day followed this artefact rather than the index only because that leg happened to be instructed to: an instruction, not a mechanism. Re-syncing one index removes one instance; striking the mandated copy removes the class — `APP-3062`.)
- Each **child document** holds the full entries for one **ISO week** (`<log-name>.YYYY-Www`), newest entry at the top.

Weekly is the bucket because each document must stay **small enough to append safely** — appends often mean rewriting the whole document, so a small bucket bounds both effort and the risk of clobbering existing entries, on a predictable boundary that needs no "is it too big yet" judgement. Buckets are not migrated when the scheme changes: earlier periods stay in their original documents, listed in the index, and the new scheme starts from the changeover.

**The bucket is also a hard write guarantee, and a log that is not on the scheme eventually cannot be written to at all.** The tracker imposes a maximum document size — in Linear, 250,000 characters — and it is a floor under nothing: at the cap, *every* write that does not shrink the document is rejected, including an append of one entry and including a one-line row added to an index. A log kept on index-plus-weekly-children never comes near it. A monolithic log grows into it silently and then stops, with no warning before the first refusal. So:

- **Check the scheme, not the size, at every append.** A log that is one ever-growing document is on borrowed time whatever its current length; move it to index-plus-children at the next entry rather than waiting for a size trigger, because the size trigger arrives as a refusal.
- **Where a monolith has already reached the cap, the changeover rule above still applies to the entries and breaks on the index.** Start the new scheme from the changeover: file the entry in its weekly child and say at the child's head what it is. But if the monolith *is* the index, the row pointing at that child cannot be written, and the child is live and unreferenced — a reader of the main log will not see the entry. State that gap in the entry and on the ticket; do not treat the filing as complete.
- **Un-sticking it is a one-off restructure of a live decision record, and that is the Owner's call, not a pass's.** Trimming or splitting a log at the cap changes the system of record. Name it and stop. (Live case: `log.meirion-decisions`, a single document of roughly 250,380 characters, refused a D094 append on 2026-10-03 — *"content must be shorter than or equal to 250000 characters."* D094 was filed in `log.meirion-decisions.2026-W40`; the index row for it still cannot be added. The size figure and the missing index row are as reported on APP-2017 and are unverified. APP-2017; the Linear mapping and the limit are in `convention-linear`, *Documents and the decision log*.)

## Entry format

```
### YYYY-MM-DD — [Decision title]
**Project:** The project this decision belongs to, named as the tracker names it — `engagement-wide` where it genuinely spans the whole engagement
**Decision:** What was decided
**Context:** What was happening / what triggered it
**Why:** Reasoning. Options considered briefly where relevant.
**Impact:** What changes downstream — including the **open tickets this decision supersedes or invalidates**, each named and reconciled (repointed, re-scoped, or waived), not only the new work it implies
**Status:** Active / Superseded by [X]
```

**The Project line is the entry-level scope, and a log scoped per domain does not supply it.** Logs are one per domain and, for an A1 engagement, one per engagement — that is the *log* level, and it is the right level: an engagement that runs several projects files all of their decisions in one log so a ruling taken on one project can be read against the others. What the five fields never carried was the *entry* level. With no project field the project is recoverable only by inference from the entry title, a per-project export means re-reading the whole log, and nothing marks which entries travel on a handover of one project. So name the project the decision belongs to, exactly as the tracker names it, or `engagement-wide` where the decision genuinely spans the engagement. The preference is one log per engagement plus a project tag, not a log per project, and the tag is what makes an entry filterable and exportable without re-reading the log. Where a log's domain *is* a single project the line still carries that project's name rather than being dropped, because a reader filtering across logs cannot tell a missing line from an unscoped decision. (Worked case: a decision for the new `a1.Muse.legacy-outreach` project was logged in `a1-muse.log-decisions` — correctly, one log for the whole engagement — and its project was recoverable only from the entry title, with no field to filter or export on — `APP-3067`.)

**A decision taken by reviewing an artefact pins the artefact; it never paraphrases the mechanism as the ruling.** Where the Context is *"after reviewing both modes live on the prototype"* — a file, a preview, a running build — the **Decision** line names that artefact by location and by the state that was read (which document or repo path, which commit or date) and says what was approved *about* it. It does not restate the mechanism in prose. A locked entry is read as settled by every leg downstream, so a paraphrase inside one is the most authoritative wrong sentence available: it is internally consistent, it agrees with whatever ticket copied it, and nothing mechanical disagrees with it — there is no digest, byte count or arithmetic for a later check to trip. Where a mechanism genuinely has to be written down, write it as a summary that cites the artefact and is explicitly subordinate to it, so a later reader knows which of the two governs. This is the log's half of the rule `skill-build-ticket` carries at claim time (*the source outranks every restatement of it*); neither substitutes for the other. (Worked case, **unverified** here — no repo is readable from the drain surface, so the prototype's contents are the filing leg's own report and that flag covers that assertion only: D080 in `log.meirion-decisions` restated a superseded 27%-of-viewport / 100px-scroll mechanism in its Decision text while its own Context said the ruling was made after reviewing the prototype live, and the prototype implements a fixed-pixel landmark from the viewport top with a row-0-crossing arm condition. Two independent passes on A1-555 — the exec build and the reviewing QA pass — reproduced the entry's reading rather than the prototype's, 2026-09-28 — APP-1839.)

**Where the pinned artefact is designated transient, the entry carries the values and says so in the Decision line.** The pin rule above assumes the artefact outlives the entry. It sometimes does not: a ruling taken on an exploration frame, a scratch branch or a preview that is deleted once the build lands leaves an entry pinned to something a later reader cannot open, and "the artefact governs over this summary" silently stops being true — with no mechanical disagreement to trip, exactly as the paraphrase failure above has none. So where the same ruling designates the artefact transient, the entry still pins it by location and by the state read, **and additionally transcribes in full the values the ruling turns on**, as read on that date; and the Decision line states that the artefact is to be deleted and that the transcription therefore governs from that point. This is the one case where the summary outranks the artefact, and it is only safe because the entry says which of the two governs and from when. Sequence the delete behind whatever binds those values into the build, so the artefact is still readable while the figures are carried across, and name that sequencing on the ticket that performs the delete. An entry that pins a transient artefact without transcribing its values is **not complete**. (Worked case: D110 in `log.meirion-decisions.2026-W41`, the 640 hero-bar — the Owner ruled "consider this the value for 640" on Figma exploration frame `673:5389` and, in the same message, that the exploration frames are deleted once the build is done. The values on that node were typed, not variable-bound, so the entry could not point at a variable instead. The filing session wrote size 53, line 65, padding 21, trimmed, bar 80 into the entry as read on 2026-10-09, said in the Decision line that the node would be deleted so the summary carries the values, and sequenced the delete behind the bind in the Figma ticket. That was judgement; this paragraph is that judgement in canon — APP-2213, APP-1839. The node id, the figures and the deletion instruction are as reported on that note and are **unverified** from the drain surface.)

**A ruling that changes board state is not recorded until the state carries it.** Where a decision changes something the deciding ticket cannot itself express — a project's status, an initiative's target, a cycle's membership — the log entry names the enacting write and the surface that owns it, and the pass that receives the ruling **either makes that write in the same pass or files it in the lane that owns it**. A ruling recorded only as prose is invisible to the machine that reads it: every liveness-gated sweep keys on `statusType`, not on comment history (`convention-project-status`, *The lifecycle*), so the board goes on asserting the opposite and each sweep dutifully re-surfaces the drift the Owner has already settled. This is the mirror of APP-1041's re-check rule: that one makes a later run re-verify a park a run asserted; this one stops a park the Owner decided from never reaching the field a later run re-verifies. "Named for action" is not a filing (APP-631). (Worked case: on 2026-09-09 the ruling *"Accepted: park app.fitness"* was recorded as a comment on APP-500, which correctly noted that the project-status change still needed doing deliberately. The project read `In Progress` with a target date 14 days past when the 2026-09-14 strategy review found it, and `[goal-review]` the same morning independently re-recommended the same park. The status write landed at 06:55Z on 2026-09-14, six days after the ruling and an hour after the friction note — APP-1422, APP-1048.)

## Lifecycle

- **Append** the entry to the **current period's** child document — creating that document if it does not yet exist — then add or update that period's row in the index.
- **One entry per decision.** Don't bundle unrelated decisions into one entry, or split one across several.
- **A `Dxxx` number is a reference label, not the entry's identity — and it is not safe to allocate under concurrency.** The entry's identity is its heading, `### YYYY-MM-DD — [Decision title]`, which two sessions cannot collide on. `Dxxx` is the short form used to cite an entry from a ticket, a PR body or another entry, and it is allocated by reading the head of the current child document immediately before appending and taking the highest number plus one. That read **narrows** the race, it does not close it: two parallel sessions on one project can both read the same highest number and both write the next one, so a collision is an expected outcome and not an error to be prevented by care. Where a number is found to collide after the fact, **renumber the later entry** — the one whose citations are fewest — leave a one-line note in place saying what it was first filed as and why it moved, and correct every citation of the old number in the same action: the ticket, the PR body, and any other entry that cites it. Cite an entry by its **date and title** wherever the citation is load-bearing and the `Dxxx` may still move. (Worked case: on 2026-09-23 two sessions on one project each filed a **D058** — Studio Mux uploads from A1-504, and the image asset block from A1-476 — alongside a D059, inside one window; the first was renumbered to **D060** about three hours later, and the number had to be corrected by hand on the ticket, the PR body and A1-515's cross-references — APP-1709.)
- **Update, don't leave stale.** When a logged decision is later resolved or reversed, edit its entry — set `Status: Superseded by [X]` and point to the superseding decision — rather than leaving a contradiction in place.
- **The log write is part of recording the decision, not a later step.** A consequential decision captured only as a ticket comment or a chat message is **not yet recorded** — the log is the system of record, the comment is not. Write the log entry in the **same action** that captures the decision; never leave "on completion, record to the log" as a deferred instruction in a ticket body, because nothing comes back to it. A `type:decision` ticket is not Done until its choice is in the log — a linked `Dxxx` entry, or an explicit "no log entry needed" note; the Linear binding of that gate is the `type:decision` Definition of Done in `convention-ticket`. (Worked case: A1-115's consent decision lived only as a ticket comment for 23 days — its own "record to the log" step never actioned — and surfaced only when Aled read a downstream ticket; back-filled as D031 — APP-724.)
- **The ticket write is part of the same action as the log entry — on the deciding ticket *and* on every ticket the ruling unblocks.** The converse of the rule above. A ruling that reaches the log and not the deciding ticket is recorded on one surface and absent from the other, and every sweep that reads tickets rather than logs — the five operator stand-ups, `task-owner-standup`, `skill-triage`, `skill-coordinate` — goes on reading that ticket as unruled and re-surfacing a question the Owner has already answered. Write the log entry and the write-back in **one action**: tick the acceptance criteria the ruling settles, carry the figure and any conditions into the criterion line itself, and move the ticket's state to whatever the ruling makes it. **That same action also writes the dependent tickets.** A consequential ruling almost always gates work sitting on a *different* ticket — a `blockedBy` sibling, or the build ticket a `DECISION:` ticket was split out of — and a write that reaches the deciding ticket and stops there leaves the dependent reading as an open ask to every sweep that buckets by current ticket state. So, in the same action: name the ruling and its date in a comment on each ticket the ruling unblocks, tick any of that ticket's own criteria the ruling settles, and move its state if the ruling makes it movable. A ruling has landed when **both ends** carry it; one end is half a write, and the half that is missing is the half the Owner sees. (Worked case: APP-1299's generator-prototype ruling was approved 2026-09-21 and written back to APP-1299 in full — visual direction, role→shape table and animation tiers, recorded in `app-agentart.log-decisions`, with the follow-on refinement ticket APP-1601 filed — while the dependent build ticket it gated, APP-1298, was never moved or annotated. The 2026-09-22 `task-daily-report` brief read APP-1298's current state, bucketed it under *Your move*, and it reached the 09:00 stand-up as a decision still needing a call Aled had already made. The deciding end was complete; the dependent end was the whole gap — APP-1644.) An entry whose deciding ticket still reads as unruled is **not complete**, and the pass that recorded it is not finished. This is the near mirror of the board-state rule under *Entry format*: that one covers what the deciding ticket cannot express, this one covers what it can and should. (Worked case: MBN-291's bounded Christmas paid-test ruling was approved 2026-09-14 and recorded in full in `mbn.log-decisions.2026-W38`, dated 09-14 with the figure and all three conditions, while the ticket kept its "Owner ruling recorded here with the figure" criterion unticked and sat in Refinement; it reached the 09-15 owner agenda as an unresolved Urgent decision — APP-1478. Re-read 2026-09-18 at 04:37Z: MBN-291 is `Todo`, its first two acceptance criteria ticked, state moved out of Refinement at 2026-09-15 08:13:36Z. The symptom was cleared by hand on that one ticket; the gap it came from is what this rule closes.)
- **The write-back follows the ruling across project and log boundaries, and reaches every live document that lists the decision as open.** The rule above says both ends carry it; it does not say the two ends sit in the same project. A ruling is routinely logged where the *deciding* work sits while the ticket it gates sits in another project served by its own log — and then no sweep reading one project's log and tickets meets both ends. The dependent reads as unruled to every pass on that side, and a session that asks the Owner asks a question he has already answered. So, in the same action: carry the ruling, its date and **the log and entry it is filed in** onto the dependent ticket, citing the entry by its full slug and by date-and-title, because that citation is the only route from that project back to the entry; and update every live document on either side that enumerates the decision as open — a sweep approach, a spike scope, a planning doc — since those are read by people and by passes as the current list of what is undecided, and one that still lists a settled point will be acted on. Where the dependent project keeps its own log and the ruling is consequential there too, file a cross-reference entry in that log rather than relying on the foreign citation alone. The surface to check is not "my project's log": it is **every** log and document that named the question. (Worked case: the Owner ruled APP-2082's decision 2 on 2026-10-06 — the house stroke token renamed in place for global use — and a manual Pulse drain set the name the same day, both entries in `osclaude.log-decisions.2026-W41`. Three days later A1-611, in a different project served by `log.meirion-decisions`, still read "Open Owner decision … whether `border/cell-width` and `border.cell` are renamed"; `spec.meirion-ds-sweep-approach`, written 2026-10-09, still listed it as an open decision affecting A1-611; and PR #236 built `--line-w` on `border.cell`, not `border.width`. The session found it only because it searched the other project's log before asking the Owner — third instance of the write-back family after APP-1478 and APP-1644, and the first where the two ends sat in different logs — APP-2212. The A1-611 and PR #236 states are as read on 2026-10-09, the PR through the GitHub connector and not a checkout, and are **unverified** here.)
- **Sweep back, not only forward.** A decision propagates into *new* tickets on its own; the failure is the *open* tickets whose premise it has just invalidated. Name them in the Impact field and reconcile each in the same pass — repoint, re-scope, waive its acceptance criteria, or **close it as folded-in where the decision has made it moot** — rather than leaving the contradiction latent. **The fourth option is the one this list was missing, and the omission is load-bearing.** A ruling does not only unblock or rescope work; it sometimes **retires** it — the change it asked for has already shipped under another ticket, or the route chosen removes the need for it altogether. A session working a three-option list finds no listed action for that case and leaves the ticket live, which reads to every sweep that buckets by current state as work still to do, and to the delivery loop as a candidate to claim. So name it, close it as folded-in, and say in the close which ticket carries the work now. Note what this is *not*: the write-back rule below reaches every ticket a ruling **unblocks** and every **dependent** ticket, both of which are forward-gating. A ticket the ruling makes moot is neither, which is why it fell through. (Worked case: a 2026-09-23 decision-log entry recorded its chosen route and named the ticket that had raised it; that ticket's single code change had already been folded into another ticket and shipped, so the ruling made it **moot** rather than unblocked. It was never closed, stayed live in Todo, and was dispatched and built — one PR opened and then closed with its branch deleted, one CI run, a decision-log draft withdrawn, one Owner correction. Two `[coordinate]` comments, of 2026-09-10 and 2026-09-13, had already recommended closing it, so the board was not short of the information: the write-time list was short of the verb. Second instance of the same shape reaching the log rather than a state batch — APP-1707, APP-1406. The PR numbers and repo state in those notes are **unverified from the drain surface**, which can read no repo.) A live decision that contradicts an open ticket's ACs is invisible to the delivery loop: Forge builds to the ticket and QA verifies against it, both passing while the ticket asserts what the decision reversed. (Worked case: the operator-console auth decision of 2026-07-27 recorded its new secrets but its Impact did not flag that it reversed the Vercel-SSO premise of A1-241 / A1-219; the contradiction sat latent ~3 days, produced a mis-ticked AC, and surfaced only at a runtime check — APP-725.)

## Tool mapping

This convention is the discipline; the tracker binding lives elsewhere. In Linear, the index and child documents are project documents and the index table links to each child — see `convention-linear` for the document mechanics, slug naming, and the full-replace-write caveat that sets the bucket size. If the tracker changes, this format is unaffected; only the mapping is rewritten.

## Quick checklist before logging a decision

- [ ] Is the decision actually consequential (depended-on or confusing-if-missing), not a routine reversible call?
- [ ] Entry in the standard format — Project, Decision, Context, Why, Impact, Status?
- [ ] Appended to the current period's child document (newest at the top), creating it if needed?
- [ ] Index row for that period added or updated?
- [ ] Slug correct for the domain (any A1 sub-account, client or not → `a1-<name>.log-decisions`)?
- [ ] Standing up a **new** log? → stem added to the list above in the same action.
- [ ] Any decision this supersedes updated to `Superseded by [X]`?
- [ ] Written **now**, in the same action as the decision — not left as a deferred "record later" step in a ticket body?
- [ ] Impact names every **open ticket this decision supersedes**, each reconciled (repointed / re-scoped / waived)?
- [ ] Deciding ticket written back in the **same action** — acceptance criteria ticked with the figure and conditions, state moved — so no ticket-reading sweep still sees it as unruled?
- [ ] **Dependent tickets written back in the same action too** — every `blockedBy` sibling and every build ticket the ruling unblocks carries the ruling and its date, with its own criteria ticked and its state moved where the ruling allows, so no bucket reads a settled decision as an open ask (APP-1644)?
- [ ] Any dependent ticket or tracking document in **another project**? → the ruling, its date and the **full log slug plus date-and-title** of the entry carried onto it, every live document that lists the decision as open updated, and a cross-reference entry filed in that project's own log where the ruling is consequential there (APP-2212)?
- [ ] Tone clean per `cos.tov`?
