From 5726251d4d2bd83663c4f22f525f4d467f1e2934 Mon Sep 17 00:00:00 2001 From: Lior Date: Thu, 28 May 2026 13:06:31 -0400 Subject: [PATCH 1/3] feat(openspec): Add Tick-History Schema spec (B-0171.2) This change implements the second spec from the OpenSpec catch-up project. - Creates the backlog item 'B-0171.2' to track the work. - Adds the OpenSpec document for the Tick-History Schema at 'openspec/specs/tick-history/README.md', formally documenting its structure and invariants. --- .../P1/B-0171.2-author-tick-history-spec.md | 35 ++++++++++++ openspec/specs/tick-history/README.md | 53 +++++++++++++++++++ 2 files changed, 88 insertions(+) create mode 100644 docs/backlog/P1/B-0171.2-author-tick-history-spec.md create mode 100644 openspec/specs/tick-history/README.md 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..5d0613112e --- /dev/null +++ b/docs/backlog/P1/B-0171.2-author-tick-history-spec.md @@ -0,0 +1,35 @@ +--- +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 frontmatter schema for the shard files. +- The format of the shard body. +- The invariants that are enforced by the hygiene tools (e.g., chronological order, relative paths). + +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/README.md` is created. +- The spec formally defines the tick-history schema. +- The spec documents the frontmatter fields and their expected values. +- The spec lists the invariants that are checked by the hygiene tools. diff --git a/openspec/specs/tick-history/README.md b/openspec/specs/tick-history/README.md new file mode 100644 index 0000000000..b5640233fc --- /dev/null +++ b/openspec/specs/tick-history/README.md @@ -0,0 +1,53 @@ +# OpenSpec: Tick-History Schema + +This document specifies the schema and invariants for the tick-history, which serves as the primary, auditable log of all autonomous agent operations in the factory. + +**Parent:** B-0171.2 + +## 1. Concepts + +The tick-history is composed of two main types of artifacts: + +- **Tick History Log (`loop-tick-history.md`):** A single, append-only markdown file containing a chronological summary of all ticks. +- **Tick Shards:** Individual markdown files, one per tick, containing the detailed output and context of a single tick. + +## 2. Tick History Log Schema + +The canonical Tick History Log is located at `docs/hygiene-history/loop-tick-history.md`. + +### 2.1. Row Format + +Each row in the log represents a single tick and MUST adhere to the following markdown table format: + +`| | | | | | |` + +- **Timestamp:** An ISO-8601 timestamp in UTC, with second precision (e.g., `2026-05-28T12:34:56Z`). +- **Model-ID:** The identifier for the model and harness that performed the tick (e.g., `opus-4-7 / autonomous-loop`). +- **Session-ID:** The unique identifier for the agent session. +- **Summary:** A brief, human-readable summary of the tick's actions. +- **PRs:** A list of pull request numbers acted upon during the tick. +- **Claim:** The claim ID for the work performed. + +### 2.2. Invariants + +- **Chronological Order:** The `Timestamp` column MUST be non-decreasing when read in file order. This is enforced by `tools/hygiene/check-tick-history-order.ts`. + +## 3. Tick Shard Schema + +Each tick generates a shard file that contains its full context and output. + +### 3.1. File and Directory Structure + +Tick shards MUST be stored in the following directory structure: + +`docs/hygiene-history/ticks/YYYY/MM/DD/HHMMZ.md` + +- `YYYY`, `MM`, `DD`: The year, month, and day of the tick. +- `HHMMZ.md`: The hour and minute of the tick in UTC. An optional `-` suffix may be present. + +This structure is enforced by `tools/hygiene/check-tick-history-shard-schema.ts`. + +### 3.2. File Content + +- **First Line:** The first non-empty line of a tick shard file MUST be a markdown table row that matches the schema defined for the Tick History Log (see section 2.1). +- **Timestamp-Path Congruence:** The timestamp in the first column of the first line MUST match the date and time encoded in the file's directory path and name. This is also enforced by `tools/hygiene/check-tick-history-shard-schema.ts`. From 947133f3d13f3bf1e8cf927cf8c4e597b9f8e2f7 Mon Sep 17 00:00:00 2001 From: "Otto-CLI (Claude)" Date: Thu, 28 May 2026 23:20:12 -0400 Subject: [PATCH 2/3] fix(B-0171.2): markdownlint MD032 + regenerate BACKLOG index after main merge - Add blank line before list (MD032/blanks-around-lists) in B-0171.2 row - Regenerate docs/BACKLOG.md to index the new B-0171.2 row + pick up current main (branch was 103 commits behind; merged main in additively) - Resolves required lint (markdownlint) + non-required BACKLOG drift checks Co-Authored-By: Claude Opus 4.8 --- docs/BACKLOG.md | 2 ++ docs/backlog/P1/B-0171.2-author-tick-history-spec.md | 1 + 2 files changed, 3 insertions(+) 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 index 5d0613112e..1764c8baf6 100644 --- a/docs/backlog/P1/B-0171.2-author-tick-history-spec.md +++ b/docs/backlog/P1/B-0171.2-author-tick-history-spec.md @@ -20,6 +20,7 @@ This task implements the second item from the Phase 1 audit of the OpenSpec catc ## 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 frontmatter schema for the shard files. - The format of the shard body. From d43848bd734d89b05ac97039033f9c2ab4d893c0 Mon Sep 17 00:00:00 2001 From: "Otto-CLI (Claude)" Date: Thu, 28 May 2026 23:56:46 -0400 Subject: [PATCH 3/3] fix(B-0171.2): make tick-history spec discoverable + accurate (PR #5884 review) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses 4 Copilot review findings on the tick-history OpenSpec capability: - Rename openspec/specs/tick-history/README.md -> spec.md so it is discovered by tools/openspec/inventory.ts (scans openspec/specs/*/spec.md). Confirmed via `bun tools/openspec/inventory.ts` now lists tick-history. - Restructure into OpenSpec Purpose/Requirements/Scenario format matching the sibling z-set-algebra + operator-algebra specs. - Align the Tick History Log row schema to the canonical header in docs/hygiene-history/loop-tick-history.md: `date | agent | cron-id | action-summary | commit-or-link | notes` (was: Timestamp | Model-ID | Session-ID | Summary | PRs | Claim). - Document all three shard filename forms enforced by check-tick-history-shard-schema.ts: HHMMZ.md, HHMMZ-.md, HHMMSSZ-.md (was: only HHMMZ.md + optional -). - Drop the frontmatter claim: tick shards are pipe-row-first with NO file-head frontmatter (the checker validates the first non-empty line is a table row). Updated B-0171.2 Scope + Acceptance Criteria to match the real format. markdownlint-cli2 clean. The 5th thread (B-0171.1 dependency) is stale — B-0171.1 landed on main via #5883. Co-Authored-By: Claude Opus 4.8 --- .../P1/B-0171.2-author-tick-history-spec.md | 12 +-- openspec/specs/tick-history/README.md | 53 ---------- openspec/specs/tick-history/spec.md | 100 ++++++++++++++++++ 3 files changed, 106 insertions(+), 59 deletions(-) delete mode 100644 openspec/specs/tick-history/README.md create mode 100644 openspec/specs/tick-history/spec.md 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 index 1764c8baf6..9a685d61cb 100644 --- a/docs/backlog/P1/B-0171.2-author-tick-history-spec.md +++ b/docs/backlog/P1/B-0171.2-author-tick-history-spec.md @@ -22,15 +22,15 @@ This task implements the second item from the Phase 1 audit of the OpenSpec catc 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 frontmatter schema for the shard files. -- The format of the shard body. -- The invariants that are enforced by the hygiene tools (e.g., chronological order, relative paths). +- 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/README.md` is created. -- The spec formally defines the tick-history schema. -- The spec documents the frontmatter fields and their expected values. +- 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/README.md b/openspec/specs/tick-history/README.md deleted file mode 100644 index b5640233fc..0000000000 --- a/openspec/specs/tick-history/README.md +++ /dev/null @@ -1,53 +0,0 @@ -# OpenSpec: Tick-History Schema - -This document specifies the schema and invariants for the tick-history, which serves as the primary, auditable log of all autonomous agent operations in the factory. - -**Parent:** B-0171.2 - -## 1. Concepts - -The tick-history is composed of two main types of artifacts: - -- **Tick History Log (`loop-tick-history.md`):** A single, append-only markdown file containing a chronological summary of all ticks. -- **Tick Shards:** Individual markdown files, one per tick, containing the detailed output and context of a single tick. - -## 2. Tick History Log Schema - -The canonical Tick History Log is located at `docs/hygiene-history/loop-tick-history.md`. - -### 2.1. Row Format - -Each row in the log represents a single tick and MUST adhere to the following markdown table format: - -`| | | | | | |` - -- **Timestamp:** An ISO-8601 timestamp in UTC, with second precision (e.g., `2026-05-28T12:34:56Z`). -- **Model-ID:** The identifier for the model and harness that performed the tick (e.g., `opus-4-7 / autonomous-loop`). -- **Session-ID:** The unique identifier for the agent session. -- **Summary:** A brief, human-readable summary of the tick's actions. -- **PRs:** A list of pull request numbers acted upon during the tick. -- **Claim:** The claim ID for the work performed. - -### 2.2. Invariants - -- **Chronological Order:** The `Timestamp` column MUST be non-decreasing when read in file order. This is enforced by `tools/hygiene/check-tick-history-order.ts`. - -## 3. Tick Shard Schema - -Each tick generates a shard file that contains its full context and output. - -### 3.1. File and Directory Structure - -Tick shards MUST be stored in the following directory structure: - -`docs/hygiene-history/ticks/YYYY/MM/DD/HHMMZ.md` - -- `YYYY`, `MM`, `DD`: The year, month, and day of the tick. -- `HHMMZ.md`: The hour and minute of the tick in UTC. An optional `-` suffix may be present. - -This structure is enforced by `tools/hygiene/check-tick-history-shard-schema.ts`. - -### 3.2. File Content - -- **First Line:** The first non-empty line of a tick shard file MUST be a markdown table row that matches the schema defined for the Tick History Log (see section 2.1). -- **Timestamp-Path Congruence:** The timestamp in the first column of the first line MUST match the date and time encoded in the file's directory path and name. This is also enforced by `tools/hygiene/check-tick-history-shard-schema.ts`. 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