docs(hygiene): endorse hybrid shard format (pipe-row + H1 body) per B-0529 Option 3#4004
Merged
Merged
Conversation
Per B-0529 Recommendation (Option 3 "hybrid"), update the shard file schema section to explicitly describe the canonical shape: pipe-row first line for validator + machine-parseability, H1-rich body below for substantive content. Adds: - Cross-link to the validator (check-tick-history-shard-schema.ts) - Explicit statement of date+hour+min matching contract - Worked example showing pipe-row then H1 body - Reference to add-pipe-row-header.ts for retrofit of older shards - Note that validator inspects only first non-empty line Aligns documentation with the substrate landed in PR #3990 (add-pipe-row-header.ts) and reflects the lived convention that recent shards (~585 of 944) already follow. Composes with: - docs/backlog/P2/B-0529-tick-shard-schema-validator-vs-practice-drift-2026-05-15.md - tools/hygiene/check-tick-history-shard-schema.ts (validator) - tools/hygiene/add-pipe-row-header.ts (retrofit tool, PR #3990) Co-Authored-By: Claude <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR updates tick-history shard schema documentation to endorse the hybrid shard format: validator-friendly pipe-row metadata first, followed by rich Markdown content.
Changes:
- Documents the validator-aligned first-line pipe-row contract.
- Adds a worked hybrid-format example.
- References the retrofit tool for older H1-first shards.
4 tasks
AceHack
added a commit
that referenced
this pull request
May 17, 2026
Files B-0591 as the explicit decomposition of B-0529's "Later (separate row)" Recommendation. Two slices: - Slice 1 (this row, P3): wire validator as non-required check in .github/workflows/gate.yml. Observability without enforcement. - Slice 2 (separate row, after Slice 1 + bulk-retrofit lands): promote to required. Pre-requisite is 0 violations on main. Composes with B-0529 (parent), the validator at tools/hygiene/check-tick-history-shard-schema.ts, the retrofit tool at tools/hygiene/add-pipe-row-header.ts (PR #3990), and the README docs updated in PR #4004. Not in scope: bulk retrofit --write run (separate row); legacy pre-2026-04-29 shard migration. Co-authored-by: Claude <noreply@anthropic.com>
…iants (Copilot P1 #4004) Resolves two Copilot P1 review findings on PR #4004: 1. Schema paragraph listed only `HHMMZ` and `HHMMSSZ-<hex>` filename forms; the validator (BARE_RE in check-tick-history-shard-schema.ts) also accepts `HHMMZ-<hex>` — the same-minute disambiguation form the README's own "Naming" section documents via `0215Z-01.md`. Now lists all three accepted forms inline. 2. The "YAML frontmatter fields" subsection said frontmatter was "preferred for richer shards", but file-head YAML frontmatter puts `---` on the first non-empty line, which fails the validator's pipe-row-first contract. Renamed to "Optional body metadata" and clarified that structured metadata lives in the H1 body, not at file head. Outer code fence widened to 4 backticks so the inner `yaml block renders correctly. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This was referenced May 17, 2026
Merged
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Per B-0529 Recommendation (Option 3 "hybrid") — the "Soon (separate row)" follow-up — this PR updates the shard-file-schema documentation in
docs/hygiene-history/ticks/README.mdto explicitly describe the canonical shape: pipe-row first line for validator + machine-parseability, H1-rich body below for substantive content.Aligns documentation with the substrate landed in PR #3990 (
tools/hygiene/add-pipe-row-header.ts) and reflects the lived convention that recent shards (~585 of 944) already follow.Changes
check-tick-history-shard-schema.ts)add-pipe-row-header.tsfor retrofit of older shardsComposes with
docs/backlog/P2/B-0529-tick-shard-schema-validator-vs-practice-drift-2026-05-15.mdtools/hygiene/check-tick-history-shard-schema.ts(validator)tools/hygiene/add-pipe-row-header.ts(retrofit tool, PR #3990)Test plan
🤖 Generated with Claude Code