diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index ec3e640546..96c6bac78e 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -81,8 +81,10 @@ are closed (status: closed in frontmatter)._ - [ ] **[B-0168.1](backlog/P1/B-0168.1-ani-review-on-brat-voice-framework.md)** Ani-review on the brat-voice enterprise translation framework (slice 1 of B-0168) - [x] **[B-0169](backlog/P1/B-0169-decision-archaeology-skill-aaron-2026-05-02.md)** Decision-archaeology skill — universal "why is it like this?" investigation surface for new contributors - [ ] **[B-0170](backlog/P1/B-0170-substrate-claim-checker-ts-tool-aaron-2026-05-03.md)** Substrate-claim-checker TS tool — mechanize the verify-then-claim discipline (Otto 2026-05-03; drift instances (the verify-then-claim memo's body table is canonical) catalogued as empirical eval-set) +- [ ] **[B-0170.1](backlog/P1/B-0170.1-semantic-equivalence-drift-checker.md)** Substrate-claim-checker - semantic-equivalence-drift checker - [ ] **[B-0171](backlog/P1/B-0171-openspec-catch-up-canonical-source-of-truth-aaron-2026-05-03.md)** OpenSpec catch-up — restore OpenSpec capabilities as canonical source-of-truth (Aaron 2026-05-03 architectural-debt naming; "if we deleted everything other than it [OpenSpec]") - [ ] **[B-0171.1](backlog/P1/B-0171.1-author-z-set-spec.md)** OpenSpec catch-up - author Z-Set Algebra spec +- [ ] **[B-0171.2](backlog/P1/B-0171.2-author-tick-history-spec.md)** OpenSpec catch-up - author Tick-History Schema spec - [ ] **[B-0173](backlog/P1/B-0173-hook-authoring-for-skill-creation-contracts-aaron-2026-05-03.md)** Hook authoring for skill-creation contracts — pre/post-condition enforcement at skill-creation + commit + PR-creation time (Aaron 2026-05-03 rule 3b from skill-design memo) - [x] **[B-0181](backlog/P1/B-0181-fix-spinemergeinvariants-tla-counterexample-blocks-b1-ci-registration-2026-05-03.md)** Fix SpineMergeInvariants.tla counterexample (closed — Cascade downstream-room precondition + state constraint; B1 → A CI registration landed) - [x] **[B-0184](backlog/P1/B-0184-fix-spine-als-alloy-6-2-0-type-error-line-35-spec-bug-2026-05-03.md)** Fix Spine.als spec bug — Alloy 6.2.0 type-check failure at line 35 col 25 (sum-vs-all comprehension confusion) + check-vs-run-vs-fact semantic confusion diff --git a/docs/backlog/P1/B-0171.2-author-tick-history-spec.md b/docs/backlog/P1/B-0171.2-author-tick-history-spec.md new file mode 100644 index 0000000000..9a685d61cb --- /dev/null +++ b/docs/backlog/P1/B-0171.2-author-tick-history-spec.md @@ -0,0 +1,36 @@ +--- +id: B-0171.2 +priority: P1 +status: open +title: "OpenSpec catch-up - author Tick-History Schema spec" +created: 2026-05-28 +last_updated: 2026-05-28 +parent: B-0171 +depends_on: [B-0171.1] +classification: buildable-now +decomposition: atomic +owners: [lior] +type: spec-authoring +--- + +# B-0171.2 — Author Tick-History Schema spec + +This task implements the second item from the Phase 1 audit of the OpenSpec catch-up project (B-0171). It involves creating a formal specification for the Tick-History Schema. + +## Scope + +This task is focused on creating the OpenSpec document for the tick-history schema. The spec will define: + +- The file and directory structure of tick-history shards. +- The shard filename grammar (`HHMMZ.md`, `HHMMZ-.md`, `HHMMSSZ-.md`). +- The pipe-row-first shard body format (tick shards carry no file-head frontmatter; the first non-empty line is a canonical table row). +- The invariants that are enforced by the hygiene tools (e.g., chronological order, timestamp-path congruence). + +The implementation is a collection of tools under `tools/hygiene/`. This task is about formally documenting the existing behavior. + +## Acceptance Criteria + +- A new spec file `openspec/specs/tick-history/spec.md` is created (so the capability is discovered by `tools/openspec/inventory.ts`, which scans `openspec/specs/*/spec.md`). +- The spec formally defines the tick-history schema using the canonical six-column row format (`date | agent | cron-id | action-summary | commit-or-link | notes`). +- The spec documents the pipe-row-first shard body format (no file-head frontmatter). +- The spec lists the invariants that are checked by the hygiene tools. diff --git a/openspec/specs/tick-history/spec.md b/openspec/specs/tick-history/spec.md new file mode 100644 index 0000000000..3db4d4807b --- /dev/null +++ b/openspec/specs/tick-history/spec.md @@ -0,0 +1,100 @@ +## Purpose + +The tick-history capability specifies the schema and invariants for the +tick-history, the primary auditable log of all autonomous agent operations in +the factory. It pins the observable structure of the two artifact families the +history is composed of — the append-only Tick History Log and the per-tick Tick +Shards — and the invariants the `tools/hygiene/` checkers enforce over them. +This spec is language-agnostic: it describes observable behaviour (file +locations, row formats, filename grammars, ordering invariants), not any +particular runtime or host-language surface. + +**Parent:** B-0171.2 + +## Requirements + +### Requirement: Tick History Log row format + +The canonical Tick History Log lives at +`docs/hygiene-history/loop-tick-history.md`. Each row MUST be a markdown table +row using the canonical six-column schema, matching the existing log header: + +`| date (UTC ISO8601) | agent | cron-id | action-summary | commit-or-link | notes |` + +- **date (UTC ISO8601):** An ISO-8601 timestamp in UTC, with minute or second + precision (e.g. `2026-05-28T12:34:56Z`). +- **agent:** The model + harness that performed the tick (e.g. + `opus-4-7 / autonomous-loop`). +- **cron-id:** The cron / fire identifier for the tick. +- **action-summary:** A brief one-line, human-readable summary of the tick's + actions. +- **commit-or-link:** The commit SHA or link produced by the tick. +- **notes:** Free-form notes. + +#### Scenario: a log row carries the six canonical columns + +- **WHEN** a row is appended to `docs/hygiene-history/loop-tick-history.md` +- **THEN** its first column MUST be a UTC ISO-8601 timestamp +- **AND** the row MUST carry at least the six canonical columns above + +### Requirement: Tick History Log chronological order + +The `date` column MUST be non-decreasing when rows are read in file order. + +#### Scenario: ordering is enforced + +- **WHEN** `tools/hygiene/check-tick-history-order.ts` scans the log +- **THEN** any row whose timestamp is earlier than a preceding row's timestamp + is reported as a violation + +### Requirement: Tick Shard directory structure and filename grammar + +Each tick generates a shard file stored under +`docs/hygiene-history/ticks/YYYY/MM/DD/`, where `YYYY`, `MM`, and `DD` are the +year, month, and day of the tick. The filename MUST match one of three forms +(as enforced by `tools/hygiene/check-tick-history-shard-schema.ts`): + +- `HHMMZ.md` — hour+minute in UTC (e.g. `0754Z.md`). +- `HHMMZ-.md` — hour+minute with a lowercase-hex disambiguation suffix + (e.g. `0754Z-3f2a.md`). +- `HHMMSSZ-.md` — hour+minute+seconds with a hex suffix, for + high-concurrency ticks (e.g. `075412Z-3f2a.md`). + +#### Scenario: a bare HHMMZ shard is accepted + +- **WHEN** a shard is named `0754Z.md` under a `YYYY/MM/DD` path +- **THEN** the schema checker accepts the filename + +#### Scenario: a seconds+hash shard is accepted + +- **WHEN** a high-concurrency shard is named `075412Z-3f2a.md` +- **THEN** the schema checker accepts the filename + +#### Scenario: a non-conforming filename is rejected + +- **WHEN** a shard filename matches none of the three forms +- **THEN** the schema checker reports `filename does not match HHMMZ.md, + HHMMZ-.md, or HHMMSSZ-.md` + +### Requirement: Tick Shard content is pipe-row-first with no frontmatter + +Tick shards do NOT carry file-head YAML frontmatter. The first non-empty line +of a shard MUST be a markdown table row that matches the Tick History Log row +format (the six canonical columns above), and its first column's timestamp MUST +agree with the date and time encoded in the shard's directory path and +filename. Both invariants are enforced by +`tools/hygiene/check-tick-history-shard-schema.ts`. + +#### Scenario: first non-empty line is a pipe row + +- **WHEN** a shard file is scanned +- **THEN** its first non-empty line MUST begin a markdown table row whose first + column is a UTC ISO-8601 timestamp +- **AND** the shard MUST NOT begin with YAML frontmatter + +#### Scenario: timestamp-path congruence + +- **WHEN** the first column's timestamp is compared to the shard's + `YYYY/MM/DD/HHMM` path +- **THEN** the date and time MUST agree, or the checker reports a congruence + violation