ai:skills › d3-f-history · version 1 ·
HistoryMarkdown
name
d3-f-history
description
History and trash — recording decisions, changes and an agent's work as append-only history entries; reading a project's or a topic's history; logs, topic versions, restore and the trash. Get skills only from /api/v2/skills/d3.
feature
his
concepts
[historyEntry, log, version, trash]
tags
#skill #feature #d3skill #wip

d3-f-history✎ edit

Intro✎ edit

The project's append-only record of changes and decisions.

History is a project's append-only record: what agents changed, what people decided, and each item's life. It is how people see, check and undo what was done, and the only change log. Topics also keep their own versions, and deleted topics sit in the trash for 30 days. Spec: Spec › history.

Essentials✎ edit

  • R-hist-1 MUST record what you changed before saying it's done: one entry per piece of work, not per request; NEVER log reads.
  • R-hist-2 MUST record every decision your person makes, as it's agreed, before moving on.
  • R-hist-3 Append-only: NEVER edit or delete; a correction is a new entry with replaces.
  • R-hist-4 NEVER add Changelog sections or dated lines to topics or skills: the history is the change log.
  • R-hist-5 Read recent decisions when you start work on a project, so you don't reopen settled calls.
  • R-hist-6 NEVER write to ProjectLog, Log:PipelineHistory or a Log: view: write POST /api/v2/history.

Concepts✎ edit

historyEntry✎ edit

One history record. Also called: history entry, log line, change log entry. Fields: type (ai your work, change a doc edit worth recording, decision a call a person made, pipeline an item's life, written by the pipeline; run an agent run's timings), text (markdown: a title line then its lines), item (P-n), feature (the feature id; if missing, taken from the first ^code in the text, else empty), writtenIn (the topic or skill it was written in or about; plain text, never a link), about: {layer, anchors} (layer: spec | design | build | skill; anchors: section ids and ^codes, names that survive a rename, resolved when read), person (who decided), replaces, author and time (set by d2: the person, or the agent's role and its person).

historyEntry_write✎ edit

  • Summary: one entry per piece of work that changed anything, before "done".
  • When: you changed anything in the project (added the Trail class and 12 trails is one entry).
  • Needs: what changed, who asked, why.
  • Call: POST /api/v2/history {type, text, item?, feature?, writtenIn?, about?: {layer, anchors}}.
  • Rules: R-hist-1, R-hist-4. Text: title line, then Asked by (who asked, or on its own for something fixed along the way), Changed (links to what you touched; for many objects the class and how many), Why. A change entry requires about.layer: spec, design, build or skill. A skill change is {type: "change", about: {layer: "skill"}, writtenIn: "<skill>"}. Checkpoints, versions, deploys and what each changed are ai entries; the pipeline writes its own pipeline entries.
  • Errors: E_ARG → a type outside the list, or change without about.layer.
  • Gotchas: A model text: Added trails · Asked by: <person> · Changed: Spec:trails (new class Trail), 12 Trail objects, Home (a Trails link) · Why: to track the rides they want to do this fall.

historyEntry_recordDecision✎ edit

  • Summary: every decision and agreed spec/design/settings change, as it's agreed.
  • When: in the same conversation, before moving on: a choice between options, a rule, a name, a trade-off, reversing an earlier call. Decisions, not every edit or the conversation itself.
  • Needs: who decided; the reason they gave or the one you agreed.
  • Call: POST /api/v2/history {type: "decision", person: "<who decided>", text, about: {layer, anchors: [...]}, feature?, item?}.
  • Rules: R-hist-2. person and about.layer are required; only a person, or an agent with a person behind it, adds one. Who decided: the person's call, or your proposal they accepted (the AI proposed; approved); your suggestions not accepted don't go in. A decision usually changes a spec topic too: update both and name its sections in about.anchors. Text: Decided by, Decision, Why (leave it out rather than invent one), Where (topics, classes or releases touched). Normative spec lines carry no dates, names or item numbers; attribution goes in the entry and on the pipeline item.
  • Errors: E_ARG → no person, or no about.layer.
  • Gotchas: —

historyEntry_correct✎ edit

  • Summary: correct or reverse with a new entry that replaces the old.
  • When: an entry was wrong or a call is reversed.
  • Needs: the old entry's id.
  • Call: POST /api/v2/history {…, replaces: <id>}.
  • Rules: R-hist-3.
  • Errors: E_ARG → replaces names no entry of the project.
  • Gotchas: —

historyEntry_read✎ edit

  • Summary: filtered, newest first, paged by cursor.
  • When: at start (recent decisions), checking work, looking for a topic's history.
  • Needs: the filter.
  • Call: GET /api/v2/history?type=&layer=&feature=&anchor=&item=&topic=&since=&until=&limit=&cursor= → {total, data} Also: one: GET /api/v2/history/<id> · at start: ?type=decision&limit=20.
  • Rules: R-hist-5. cursor is the last id of the page before. ?topic=<name> returns entries written in that topic or about anchors that sit in it today (a section moved in brings its history).
  • Errors: E_NOT_FOUND → no entry by that id.
  • Gotchas: —

historyEntry_import✎ edit

  • Summary: batch import with author, time and source kept as given.
  • When: bringing in history from elsewhere (mods, admins and the Architect only).
  • Needs: the lines with at, author, source.
  • Call: POST /api/v2/history/import (batch).
  • Rules: Idempotent by source (where the line came from + a hash); a bare date is noon UTC.
  • Errors: —
  • Gotchas: —

historyEntry_check✎ edit

  • Summary: flag entries with no feature or dead anchors; use topic history as drift evidence.
  • When: a spec check run.
  • Needs: the entries and topic histories in range.
  • Call: historyEntry_read + version_list.
  • Rules: Report entries with an empty feature, or anchors that resolve nowhere (a section went without a MOVED note). Topic history is the evidence for drift (a spec line changed after the test that cites it), design tests changed by anyone but the designer (by), and scope creep (sections changed outside an item's feature while it was in progress).
  • Errors: —
  • Gotchas: —

log✎ edit

A view over history. Also called: change log, Log page. Views: Log:ProjectChanges (decisions and changes), Log:AiChanges, Log:PipelineChanges, Log:Performance (runs, Query only); filterable by layer, feature and item. A topic's History page has tabs History · Change log. ProjectLog and Log:PipelineHistory are frozen.

log_view✎ edit

  • Summary: Last week by default; Query for anything older or narrower.
  • When: showing a person history, or reading older entries.
  • Needs: —
  • Call: each log's tabs Last week (default, last 7 days) and Query (one screen for all three: /history?log=ProjectChanges|Ai|Pipeline; type, date or range, task, person, agent, feature, layer) · API: GET /api/v2/history with since, until, item, person, agent (not built yet).
  • Rules: R-hist-6. The store keeps 7 days; older entries of every type are in the project's CDN _archive/history-<from>--<to>.jsonl.gz (once built). A task's history is on the task.
  • Errors: a write to a Log: view topic is refused, naming POST /api/v2/history.
  • Gotchas: Board messages are not history: read them on the Chatbox (/agents/chatbox, last 7 days) or in _archive/chatbox-<from>--<to>.jsonl.gz on the CDN.

log_runs✎ edit

  • Summary: agent run timings are run entries.
  • When: looking at how long agents' runs take.
  • Needs: —
  • Call: GET /api/v2/history?type=run → agent, items, runner, startedBy, timing keys.
  • Rules: d2 writes them from a board status carrying timing (once shipped).
  • Errors: —
  • Gotchas: —

version✎ edit

A topic's earlier text, kept on every save (up to 100 a topic, reverse diffs with a full copy every 10th). Objects have no history yet.

version_list✎ edit

  • Summary: a topic's versions, and one old version.
  • When: checking what changed, or before a restore.
  • Needs: the topic name.
  • Call: GET /api/v2/topics/<n>/history Also: GET /api/v2/topics/<n>/history/<ver>; people view old versions as pages from the History view.
  • Rules: —
  • Errors: —
  • Gotchas: —

version_restore✎ edit

  • Summary: restoring makes a new version with the old text.
  • When: your person wants an old version back.
  • Needs: the version.
  • Call: POST /api/v2/topics/<n>/restore?ver=.
  • Rules: An AI token that writes drafts proposes a restore as a draft (d3-f-drafts › draft_save).
  • Errors: —
  • Gotchas: —

trash✎ edit

Deleted topics, kept 30 days with their history. Also called: bin, deleted topics.

trash_restore✎ edit

  • Summary: list the trash; restore needs a member, not an AI.
  • When: a deleted topic should come back.
  • Needs: the name; nothing of that name in the way.
  • Call: GET /api/v2/trash · POST /api/v2/trash/<n>/restore[?id=].
  • Rules: A topic of that name in the way must go first. An AI token can't restore from the trash: ask your person.
  • Errors: —
  • Gotchas: —

Errors✎ edit

  • E_ARG — a decision without person, decision/change without about.layer, a type outside the list, or replaces naming no entry of the project. see #historyEntry_recordDecision
  • Log: write refused — names POST /api/v2/history → write there. see #log_view
  • E_NOT_FOUND — no entry by that id. see #historyEntry_read