@chromvoid/headless-ui 0.1.0

package/specs/components/window-splitter.md

@@ -0,0 +1,297 @@
+# Window Splitter Component Contract
+
+## Purpose
+
+`Window Splitter` (or Splitter) provides a headless APG-aligned model for a moveable separator between two panes, enabling users to resize them via keyboard or pointer interactions.
+
+## Component Files
+
+- `src/window-splitter/index.ts` - model and public `createWindowSplitter` API
+- `src/window-splitter/window-splitter.test.ts` - unit behavior tests
+
+---
+
+## Orientation Semantics (ARIA-aligned)
+
+The `orientation` option describes the physical orientation of the **separator bar itself**, not the layout direction. This matches ARIA conventions.
+
+| `orientation` value | Separator bar direction         | Layout split       | Active arrow keys                               |
+| ------------------- | ------------------------------- | ------------------ | ----------------------------------------------- |
+| `'vertical'`        | Vertical bar (standing upright) | Left / right panes | `ArrowLeft` (decrease), `ArrowRight` (increase) |
+| `'horizontal'`      | Horizontal bar (lying flat)     | Top / bottom panes | `ArrowUp` (decrease), `ArrowDown` (increase)    |
+
+**Important correction from earlier convention:** Prior versions of this spec had the mapping reversed (horizontal → left/right keys). The ARIA-aligned convention used here treats `orientation` as describing the separator element itself, not the axis of movement. A vertical separator divides content left and right; a horizontal separator divides content top and bottom.
+
+The `aria-orientation` attribute exposed on the separator element reflects this same value directly.
+
+---
+
+## Public API
+
+### `CreateWindowSplitterOptions`
+
+| Option             | Type                         | Default                     | Description                                                                                                                                                                                                                                   |
+| ------------------ | ---------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `idBase`           | `string`                     | `'window-splitter'`         | Base string used to derive stable element IDs and atom names.                                                                                                                                                                                 |
+| `min`              | `number`                     | `0`                         | Minimum allowed position value.                                                                                                                                                                                                               |
+| `max`              | `number`                     | `100`                       | Maximum allowed position value.                                                                                                                                                                                                               |
+| `position`         | `number`                     | mid-point of `[min, max]`   | Initial position.                                                                                                                                                                                                                             |
+| `step`             | `number`                     | `1`                         | Amount moved per arrow-key press.                                                                                                                                                                                                             |
+| `orientation`      | `'horizontal' \| 'vertical'` | `'horizontal'`              | Orientation of the separator bar (see Orientation Semantics section).                                                                                                                                                                         |
+| `isFixed`          | `boolean`                    | `false`                     | When `true`, the splitter is in fixed mode: arrow keys are disabled and `Enter` toggles between min and max.                                                                                                                                  |
+| `ariaLabel`        | `string`                     | —                           | Value for `aria-label` on the separator element.                                                                                                                                                                                              |
+| `ariaLabelledBy`   | `string`                     | —                           | Value for `aria-labelledby` on the separator element.                                                                                                                                                                                         |
+| `primaryPaneId`    | `string`                     | `'{idBase}-pane-primary'`   | Explicit ID for the primary pane element.                                                                                                                                                                                                     |
+| `secondaryPaneId`  | `string`                     | `'{idBase}-pane-secondary'` | Explicit ID for the secondary pane element.                                                                                                                                                                                                   |
+| `formatValueText`  | `(value: number) => string`  | —                           | Custom formatter for `aria-valuetext`.                                                                                                                                                                                                        |
+| `snap`             | `string`                     | —                           | Optional space-separated list of snap positions. Each token is either a bare number (value in `[min, max]` units) or a percentage string ending in `%` (resolved as `min + pct/100 * (max - min)`). Example: `"25% 50% 75%"` or `"10 50 90"`. |
+| `snapThreshold`    | `number`                     | `12`                        | Maximum distance (in the same units as position) between the candidate position and a snap point for snapping to activate.                                                                                                                    |
+| `onPositionChange` | `(value: number) => void`    | —                           | Callback fired after position changes. Receives the post-snap, clamped value. Only called when the value actually changes.                                                                                                                    |
+
+### State Signals
+
+| Signal              | Type                               | Description                                       |
+| ------------------- | ---------------------------------- | ------------------------------------------------- |
+| `state.position`    | `Atom<number>`                     | Current position, always clamped to `[min, max]`. |
+| `state.min`         | `Atom<number>`                     | Current minimum bound.                            |
+| `state.max`         | `Atom<number>`                     | Current maximum bound.                            |
+| `state.orientation` | `Atom<'horizontal' \| 'vertical'>` | Current orientation of the separator bar.         |
+| `state.isDragging`  | `Atom<boolean>`                    | Whether a pointer drag is in progress.            |
+
+### Actions
+
+| Action          | Signature                                     | Description                                                                                                                         |
+| --------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `setPosition`   | `(value: number) => void`                     | Set position to `value`. Applies snap logic then range clamping (see Snap Behavior). Fires `onPositionChange` if the value changed. |
+| `moveStep`      | `(direction: -1 \| 1) => void`                | Move position by one `step` in the given direction. Fires `onPositionChange` if the value changed.                                  |
+| `moveToMin`     | `() => void`                                  | Move position to `min`. Fires `onPositionChange` if the value changed.                                                              |
+| `moveToMax`     | `() => void`                                  | Move position to `max`. Fires `onPositionChange` if the value changed.                                                              |
+| `startDragging` | `() => void`                                  | Set `isDragging` to `true`.                                                                                                         |
+| `stopDragging`  | `() => void`                                  | Set `isDragging` to `false`.                                                                                                        |
+| `handleKeyDown` | `(event: Pick<KeyboardEvent, 'key'>) => void` | Dispatch keyboard intent to the appropriate action.                                                                                 |
+
+### Contracts
+
+| Method                    | Returns                   | Description                                                                                             |
+| ------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `getSplitterProps()`      | `WindowSplitterProps`     | ARIA and event props for the separator element. Must be called inside a reactive scope (reads signals). |
+| `getPrimaryPaneProps()`   | `WindowSplitterPaneProps` | Data attributes for the primary pane element.                                                           |
+| `getSecondaryPaneProps()` | `WindowSplitterPaneProps` | Data attributes for the secondary pane element.                                                         |
+
+### TypeScript Shapes
+
+```ts
+export interface WindowSplitterProps {
+  id: string
+  role: 'separator'
+  tabindex: '0'
+  'aria-valuenow': string
+  'aria-valuemin': string
+  'aria-valuemax': string
+  'aria-valuetext'?: string
+  'aria-orientation': WindowSplitterOrientation
+  'aria-controls': string
+  'aria-label'?: string
+  'aria-labelledby'?: string
+  onKeyDown: (event: Pick<KeyboardEvent, 'key'>) => void
+}
+
+export interface WindowSplitterPaneProps {
+  id: string
+  'data-pane': 'primary' | 'secondary'
+  'data-orientation': WindowSplitterOrientation
+}
+```
+
+---
+
+## APG and A11y Contract
+
+- role: `separator`
+- Required attributes on the separator element:
+  - `aria-valuenow`: current position (string)
+  - `aria-valuemin`: minimum position (string)
+  - `aria-valuemax`: maximum position (string)
+  - `aria-orientation`: `'horizontal'` or `'vertical'` (see Orientation Semantics)
+  - `aria-controls`: space-separated IDs of the pane elements being resized
+  - `tabindex`: `'0'` — the splitter must be focusable
+- Optional attributes:
+  - `aria-label` or `aria-labelledby` — at least one should be provided for accessible labelling
+  - `aria-valuetext` — human-readable position label via `formatValueText`
+
+---
+
+## Keyboard Contract
+
+| Key          | Orientation condition          | Effect                                      |
+| ------------ | ------------------------------ | ------------------------------------------- |
+| `ArrowLeft`  | `orientation === 'vertical'`   | Decrease position by one `step`             |
+| `ArrowRight` | `orientation === 'vertical'`   | Increase position by one `step`             |
+| `ArrowUp`    | `orientation === 'horizontal'` | Decrease position by one `step`             |
+| `ArrowDown`  | `orientation === 'horizontal'` | Increase position by one `step`             |
+| `Home`       | any                            | Move position to `min`                      |
+| `End`        | any                            | Move position to `max`                      |
+| `Enter`      | any (`isFixed === true`)       | Toggle between min and max (see Fixed Mode) |
+
+Keys for the **inactive orientation** (e.g., `ArrowLeft`/`ArrowRight` when `orientation === 'horizontal'`) are no-ops and must not change state.
+
+When `isFixed === true`, all arrow keys are disabled. Only `Enter`, `Home`, and `End` remain active.
+
+---
+
+## Fixed Mode
+
+When `isFixed: true` is passed in options:
+
+- Arrow keys (`ArrowLeft`, `ArrowRight`, `ArrowUp`, `ArrowDown`) are **disabled** — pressing them does nothing.
+- `Home` and `End` still work as normal.
+- `Enter` **toggles** position between `min` and `max`:
+  - If `position <= midpoint` (where `midpoint = min + (max - min) / 2`), set position to `max`.
+  - Otherwise, set position to `min`.
+- `isFixed` defaults to `false`. When `false`, `Enter` has no effect.
+
+This mode supports use cases like a collapsible sidebar where the splitter can only be "open" or "closed".
+
+---
+
+## Snap Behavior
+
+When the `snap` option is provided, `setPosition` (and any action that ultimately calls it) applies snap logic before finalizing the value.
+
+### Algorithm
+
+1. **Parse** the `snap` string into an array of numeric positions:
+   - Tokens ending in `%` are resolved as: `min + (pct / 100) * (max - min)`
+   - Bare numeric tokens are used as-is (as values in `[min, max]` space)
+   - Invalid tokens are ignored
+2. **Clamp** the incoming position to `[min, max]`.
+3. **Find** the nearest snap point from the parsed array.
+4. **Snap**: if `|clampedPosition - nearestSnapPoint| <= snapThreshold`, use `nearestSnapPoint` as the final position.
+5. Otherwise, use the clamped position unchanged.
+6. **Fire** `onPositionChange` with the final post-snap value (only if it differs from the previous position).
+
+### Defaults
+
+- `snap`: not set (snapping disabled)
+- `snapThreshold`: `12`
+
+### Examples
+
+```
+min=0, max=100, snap="25% 50% 75%", snapThreshold=12
+  setPosition(28)  → nearest snap = 25, distance = 3  ≤ 12  → final = 25
+  setPosition(40)  → nearest snap = 50, distance = 10 ≤ 12  → final = 50
+  setPosition(62)  → nearest snap = 75, distance = 13 > 12  → final = 62 (no snap)
+
+min=0, max=200, snap="50 100 150", snapThreshold=12
+  setPosition(55)  → nearest snap = 50, distance = 5  ≤ 12  → final = 50
+  setPosition(70)  → nearest snap = 50, distance = 20 > 12 and to 100 distance = 30 > 12 → final = 70
+```
+
+---
+
+## Behavior Contract
+
+- `Window Splitter` manages the numerical state of the split. The actual resizing of DOM elements is handled by the adapter (e.g., via CSS variables or direct style updates).
+- `orientation` determines which arrow keys are active (see Orientation Semantics and Keyboard Contract).
+- `step` size for keyboard navigation is configurable via `CreateWindowSplitterOptions`.
+- `onPositionChange` is only fired when the position value **actually changes** (comparing pre- and post-action values). No spurious calls on no-ops.
+
+---
+
+## Invariants
+
+- `position` must always be clamped between `min` and `max`.
+- `aria-valuenow` must be updated in real-time during dragging or keyboard interaction.
+- The splitter must be focusable (tabindex `'0'`) to allow keyboard users to resize panes.
+- Arrow keys for the inactive orientation must have no effect on state.
+- `onPositionChange` must never fire when the position did not change.
+
+---
+
+## Adapter Expectations
+
+The UIKit adapter (e.g., a Solid.js or Angular binding) is expected to:
+
+### Signals read by the adapter
+
+| Signal              | Usage                                                |
+| ------------------- | ---------------------------------------------------- |
+| `state.position`    | Drive CSS variable or style for pane size            |
+| `state.isDragging`  | Apply a drag-active CSS class or `user-select: none` |
+| `state.orientation` | Conditionally apply layout CSS                       |
+
+### Actions called by the adapter
+
+| Action                 | When                                                                   |
+| ---------------------- | ---------------------------------------------------------------------- |
+| `startDragging()`      | On `pointerdown` on the separator element                              |
+| `setPosition(value)`   | On `pointermove` while dragging (adapter computes pixel-to-unit value) |
+| `stopDragging()`       | On `pointerup`                                                         |
+| `handleKeyDown(event)` | On `keydown` on the separator element                                  |
+
+### Contracts spread by the adapter
+
+The adapter calls `getSplitterProps()`, `getPrimaryPaneProps()`, and `getSecondaryPaneProps()` inside a reactive computation and spreads the returned objects directly onto the corresponding DOM elements.
+
+### Pointer event drag contract
+
+```
+pointerdown on separator
+  → actions.startDragging()
+  → element.setPointerCapture(event.pointerId)
+
+pointermove (while captured)
+  → actions.setPosition(computedValue)   // adapter converts pointer offset to numeric position
+
+pointerup / pointercancel
+  → actions.stopDragging()
+  → element.releasePointerCapture(event.pointerId)  // optional; browser releases automatically on pointerup
+```
+
+### Snap and `snapThreshold` pass-through
+
+The UIKit adapter reads `snap` and `snapThreshold` from element attributes (or component props) and passes them directly to `createWindowSplitter`. The adapter does not implement snap logic itself — it is fully handled inside the headless model.
+
+---
+
+## Minimum Test Matrix
+
+| Test case                                         | What is verified                                                                 |
+| ------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Arrow keys move position (vertical orientation)   | `ArrowLeft` decreases, `ArrowRight` increases; `ArrowUp`/`ArrowDown` are no-ops  |
+| Arrow keys move position (horizontal orientation) | `ArrowUp` decreases, `ArrowDown` increases; `ArrowLeft`/`ArrowRight` are no-ops  |
+| Inactive-orientation keys are no-ops              | Neither signal changes nor `onPositionChange` fires                              |
+| `Home` moves to `min`                             | Position becomes `min` regardless of current position                            |
+| `End` moves to `max`                              | Position becomes `max` regardless of current position                            |
+| Clamping at boundaries                            | `setPosition` beyond `max` clamps to `max`; below `min` clamps to `min`          |
+| `aria-valuenow` synchronization                   | Reflects current position after every update                                     |
+| Drag lifecycle                                    | `startDragging` → `isDragging === true`; `stopDragging` → `isDragging === false` |
+| `aria-controls` linkage                           | `getSplitterProps()['aria-controls']` contains both pane IDs                     |
+| `onPositionChange` only fires on actual change    | Calling `setPosition(currentValue)` does not invoke the callback                 |
+| Fixed mode — Enter toggles to max                 | When `position <= midpoint`, Enter sets position to `max`                        |
+| Fixed mode — Enter toggles to min                 | When `position > midpoint`, Enter sets position to `min`                         |
+| Fixed mode — arrow keys disabled                  | Arrow keys do nothing when `isFixed === true`                                    |
+| Snap within threshold                             | `setPosition` value within `snapThreshold` of a snap point → snaps to that point |
+| Snap beyond threshold                             | `setPosition` value beyond `snapThreshold` of all snap points → no snap          |
+| Snap percentage resolution                        | `"50%"` with `min=0, max=200` resolves to `100`                                  |
+| Snap no-op when `snap` not set                    | Normal `setPosition` behavior without snap string                                |
+| `onPositionChange` receives post-snap value       | Callback value equals the snapped position, not the raw input                    |
+
+---
+
+## ADR-001 Compliance
+
+- **Runtime Policy**: Reatom v1000 only; no `@statx/*` in headless core.
+- **Layering**: core → interactions → a11y-contracts → adapters; adapters remain thin mappings.
+- **Independence**: No imports from `@project/*`, `apps/*`, or other out-of-package modules.
+- **Verification**: Mandatory adapter integration tests and standalone package test execution.
+
+---
+
+## Out of Scope (Current)
+
+- Multiple splitters in a single container (nested splitters)
+- "Collapsible" panes (where the pane can be hidden completely)
+- Persistent state (saving position to localStorage)
+- Touch-specific gesture optimization (should be handled in the adapter)

package/specs/ops/git-shard-sync.md

@@ -0,0 +1,107 @@
+# Git-Shard Sync Operations Guide
+
+## Purpose
+
+This document defines the operational sync flow between:
+
+- monorepo mirror: `packages/headless`
+- canonical public repository: git-shard
+
+It implements `HLS-001` and supports ADR-001/ADR-002.
+
+## Source of Truth
+
+- git-shard is the canonical source for tags, release history, and package publication.
+- monorepo is a development mirror used for local integration and fast iteration.
+
+## Sync Directions
+
+## 1) Outbound Sync (mirror -> shard)
+
+Use this when changes were developed inside monorepo and must be promoted to canonical shard.
+
+### Preconditions
+
+1. changes are limited to `packages/headless/**`
+2. local checks pass:
+   - `npm run lint`
+   - `npm run test`
+3. boundary check is green
+
+### Procedure
+
+1. create a dedicated sync branch in git-shard:
+   - naming: `sync/mono-YYYYMMDD-<topic>`
+2. copy/sync files from mirror into shard working tree
+3. run shard-local checks:
+   - lint
+   - test
+4. open PR in shard with title prefix: `sync(mirror): ...`
+5. merge only after CI is green
+
+### Required Evidence in PR
+
+- list of synced files
+- lint/test outputs
+- statement confirming no monorepo-internal imports
+
+## 2) Inbound Sync (shard -> mirror)
+
+Use this after shard releases or direct shard-first development.
+
+### Preconditions
+
+1. identify source tag/commit in shard
+2. confirm shard CI is green for that state
+
+### Procedure
+
+1. create monorepo branch:
+   - naming: `sync/shard-YYYYMMDD-<tag-or-topic>`
+2. copy/sync shard files into `packages/headless`
+3. run mirror checks:
+   - `npm run lint`
+   - `npm run test`
+4. open monorepo PR with title prefix: `sync(shard): ...`
+5. merge after CI is green
+
+### Required Evidence in PR
+
+- shard commit/tag reference
+- changed file list
+- local validation outputs
+
+## Conflict Resolution Rules
+
+When mirror and shard diverge:
+
+1. prefer shard behavior for released contracts
+2. prefer newer docs if they are contract-compatible
+3. if behavior differs and contract impact is unclear:
+   - stop merge
+   - create reconciliation issue
+   - resolve before sync merge
+
+## Branch and Tag Handling
+
+- release tags (`vX.Y.Z`) are created only in shard
+- mirror must not create package release tags for `headless`
+- mirror sync PRs must reference source shard tag when applicable
+
+## Emergency Rules
+
+If a critical bugfix is required:
+
+1. patch in shard first
+2. release from shard
+3. back-sync to mirror immediately
+
+## Operational Checklist (Quick)
+
+Before any sync merge:
+
+- [ ] scope limited to `packages/headless/**`
+- [ ] lint/test checks are green
+- [ ] no forbidden imports
+- [ ] source and destination references documented
+- [ ] PR title uses `sync(mirror)` or `sync(shard)` prefix

package/specs/ops/release-checklist.md

@@ -0,0 +1,76 @@
+# Headless Release Checklist (Git-Shard)
+
+## Purpose
+
+This checklist is mandatory for shard releases and implements `HLS-002`.
+
+It enforces ADR-002 (release ownership) and ADR-003 (versioning/deprecation policy).
+
+## Inputs
+
+- target release version
+- release branch/PR
+- changelog draft
+- list of included issues/PRs
+
+## 1) Scope and Source Verification
+
+- [ ] release branch is in git-shard (not monorepo mirror)
+- [ ] release scope is limited to package-owned files
+- [ ] all sync references are documented (if changes originated in mirror)
+
+## 2) Quality Gates
+
+- [ ] `npm run lint` passes in shard
+- [ ] `npm run test` passes in shard
+- [ ] boundary checks pass (no forbidden imports)
+- [ ] no unresolved TODO/FIXME in contract-critical files
+
+## 3) SemVer Classification (ADR-003)
+
+- [ ] classify release as `patch`, `minor`, or `major`
+- [ ] release PR body includes `SemVer: patch|minor|major`
+- [ ] classification includes runtime API impact
+- [ ] classification includes type-level API impact
+- [ ] classification includes behavior-contract impact (keyboard/focus/a11y)
+
+Decision log:
+
+- Selected version type:
+- Rationale:
+
+## 4) Deprecation Review (ADR-003)
+
+- [ ] all newly deprecated APIs are marked with `@deprecated`
+- [ ] replacement paths are documented
+- [ ] deprecation timeline is explicit
+- [ ] no removal happens before required deprecation cycle
+- [ ] for `major` releases, PR body includes `Migration Notes: <path or link>`
+- [ ] for `major` releases, `specs/release/migration-notes-pre-v1.md` is updated in the same PR
+
+## 5) Documentation and Changelog
+
+- [ ] changelog updated
+- [ ] release notes include user-visible changes
+- [ ] breaking changes section present if applicable
+- [ ] migration notes included for incompatible changes
+
+## 6) Tag and Publish Preparation
+
+- [ ] target version in package manifest is correct
+- [ ] release tag format is `vX.Y.Z`
+- [ ] release commit is finalized and reviewed
+- [ ] package contents are validated before publish
+
+## 7) Publish and Post-Release
+
+- [ ] publish completed from git-shard only
+- [ ] tag pushed and release notes published
+- [ ] post-release sync back to monorepo mirror created/tracked
+
+## Sign-off
+
+- Release owner:
+- Reviewer:
+- Date:
+- Result: Approved / Blocked

package/specs/release/GAP-TO-GREEN-ISSUES.md

@@ -0,0 +1,88 @@
+# Gap-to-Green Issue Pack
+
+## Purpose
+
+This file provides issue-ready tickets for the remaining work before stable release sign-off.
+
+## How to Use
+
+- copy each issue into tracker as a standalone task
+- keep scope limited to `packages/headless/**` unless issue says otherwise
+- require evidence links for CI runs and docs updates
+
+Common labels:
+
+- `headless`
+- `release`
+- `governance`
+- `tests`
+- `docs`
+- `ci`
+
+## HLS-GTG-001 - Enforce ADR-003 classification in release PRs
+
+- **Status**: Open
+- **Priority**: High
+- **Labels**: `headless`, `release`, `governance`, `ci`
+- **Scope**: add an automated gate that validates SemVer classification in release PR metadata
+- **Deliverables**:
+  - release-governance check script in `packages/headless/scripts/`
+  - CI workflow job that runs the check for release PR context
+- **Acceptance Criteria**:
+  - release PR without explicit SemVer classification fails CI
+  - supported values are `patch`, `minor`, `major`
+  - non-release PRs are not blocked by this check
+
+## HLS-GTG-002 - Enforce migration notes policy on behavior-breaking changes
+
+- **Status**: Open
+- **Priority**: High
+- **Labels**: `headless`, `release`, `governance`, `docs`
+- **Scope**: require migration-note evidence when release PR declares breaking behavior/API change
+- **Deliverables**:
+  - governance check updated with migration-note requirement
+  - release checklist wording aligned to automation
+- **Acceptance Criteria**:
+  - release PR classified as `major` fails if migration note reference is absent
+  - release PR classified as `major` fails if migration notes file is not changed
+  - check output includes actionable failure reason
+
+## HLS-GTG-003 - Add adapter integration test coverage
+
+- **Status**: Open
+- **Priority**: High
+- **Labels**: `headless`, `tests`, `a11y`
+- **Scope**: add component-level integration tests validating adapter-style bindings for keyboard/pointer flows
+- **Deliverables**:
+  - adapter integration tests under `packages/headless/src/adapters/`
+- **Acceptance Criteria**:
+  - tests validate `model -> bindings -> events -> state` flow
+  - tests cover keyboard and pointer paths
+  - tests run in existing `npm run test`
+
+## HLS-GTG-004 - Finalize docs for multi-component reality and ADR status
+
+- **Status**: Open
+- **Priority**: Medium
+- **Labels**: `headless`, `docs`
+- **Scope**: align README and ADR-001 metadata with implemented state of package
+- **Deliverables**:
+  - `packages/headless/README.md` updated with all implemented components and structure
+  - `packages/headless/specs/ADR-001-headless-architecture.md` status/version update
+- **Acceptance Criteria**:
+  - README no longer describes listbox as the only current example
+  - ADR-001 status reflects accepted architecture baseline
+  - docs remain consistent with current source tree
+
+## HLS-GTG-005 - Add monorepo CI guard for headless package gates
+
+- **Status**: Open
+- **Priority**: High
+- **Labels**: `headless`, `ci`, `release`
+- **Scope**: add root CI job that runs package-specific lint and tests for `packages/headless`
+- **Deliverables**:
+  - root workflow update with headless package job
+- **Acceptance Criteria**:
+  - root CI executes `npm run lint`
+  - root CI executes `npm run test`
+  - failures block merge

package/specs/release/api-freeze-candidate.md

@@ -0,0 +1,54 @@
+# API Freeze Candidate (Pre-v1)
+
+## Purpose
+
+This document is the `HLS-070` API freeze candidate result.
+
+It captures the current freeze scope, contract confidence level,
+and pre-stable cleanup requirements before first stable release.
+
+## Candidate Scope
+
+Included components:
+
+- Listbox
+- Combobox
+- Menu
+- Tabs
+- Treeview
+
+Included shared primitives:
+
+- keyboard intents
+- typeahead
+- selection reducers
+
+## Freeze Criteria Checklist
+
+- [x] each component has dedicated source directory and spec document
+- [x] each component contract has unit tests
+- [x] boundary checks prevent monorepo-only imports
+- [x] package-level lint/test gates are green
+- [x] SemVer/deprecation process documented (ADR-003)
+- [x] release ownership documented (ADR-002)
+
+## Contract Stability Assessment
+
+Current status: **freeze-candidate (not final freeze)**
+
+Rationale:
+
+- behavior contracts are implemented and tested for current APG subset
+- public API is coherent across components (`createX`, state/actions, `get*Props`)
+- release governance documents now exist
+
+Outstanding pre-stable items:
+
+1. run shard-only release drill and close follow-ups
+2. finalize release notes format and changelog protocol in shard workflow
+3. validate migration docs against first external consumer integration
+
+## Recommended Freeze Decision
+
+- Freeze candidate accepted for release rehearsal.
+- Final freeze approval deferred until `HLS-072` follow-ups are resolved.