Repository navigation
Description
Facts
hooks/hooks.json's top-leveldescriptionfield has grown into a single
large run-on paragraph documenting the rationale for every hook ever
added, citing issue numbers feat: re-run provenance/placeholder scan against the actually-posted PR/issue body (post-write verification) #878, feat(hooks): add PreToolUse hook to block issue creation without ACM disclosure #413, fix(gate-skill-audit-disclosure): close disclosure gaps in script + PR template #517, chore(retrospective): merge retrospective for PR #186 #187, refactor(skills): rename driving-pr-to-merge -> drafting-a-pr-to-merge; terminal state is DRAFT, never merge #637, feat(hooks): gate PR creation on referenced issue's ACM/waiver disclosure #657, Add a deterministic gate restricting PR titles to Conventional Commits format #1058, and
fix(dedup): add deterministic duplicate-work checks for PRs, retrospective issues, and new issues #1197.- This content duplicates what
.gitapex/ssot.json'sgates[]array already
tracks per-gate, structured, in its ownruleandtracking_issuefields
-- confirmed directly by reading both files. - Direct investigation: of the 10 hook scripts
hooks/hooks.jsonwires, 9
already have a corresponding.gitapex/ssot.jsongate entry. Only
hooks/check-merge-pull-request-block.sh(backing issue refactor(skills): rename driving-pr-to-merge -> drafting-a-pr-to-merge; terminal state is DRAFT, never merge #637) has none. - No existing deterministic gate or test asserts on
hooks.json's
descriptionfield content -- confirmed by a repo-wide search.
gitapex_gate_plugin_root_brace_notation.pyexplicitly scopes itself to
commandvalues only and statesdescription:is never graded. .github/scripts/gitapex_gate_skill_audit_disclosure.py's own docstring
confirms a diff touching both.gitapex/ssot.jsonandhooks/hooks.json
(its own words: "the two files that decide whether gates run at all")
requires adeterministic-gate-qualityskill-audit disclosure on the PR
that implements this.- The repo owner directly requested this consolidation in this session's
own conversation, after an earlier exchange establishing that hooks.json's
description field was the source of the duplication.
Requested outcome
Shrink hooks/hooks.json's top-level description field to a short pointer
directing readers to .gitapex/ssot.json's gates[] registry as the single
source of truth for gate rationale, and register the one currently-missing
gate entry (hooks/check-merge-pull-request-block.sh, issue #637) so no
rationale is lost in the consolidation.
Acceptance Criteria Map
Draft, not pre-verified -- planning-a-branch-from-an-issue's own Step 4
independently re-checks each row against this issue's own stated facts
before implementation, rather than trusting it merely for being
well-formed.
| Criterion | Interpretation | Planned ops | Proof method | Residual risk |
|---|---|---|---|---|
hooks/hooks.json's description field must stop duplicating per-gate rationale already tracked in .gitapex/ssot.json |
Replace the current prose blob with a short pointer sentence naming .gitapex/ssot.json's gates[] registry and its trigger field as the place to find each gate's own rationale |
Edit hooks/hooks.json's top-level description field only; no command, matcher, or timeout value touched |
Confirm no existing gate/test asserts on this field's content (already verified this session); confirm gitapex_detect_changed_gate_scripts.py still flags the diff as gate-wiring-relevant (unchanged, path-based behavior) |
None identified -- pure documentation consolidation, no runtime behavior change |
Every hook script hooks/hooks.json wires must have a corresponding .gitapex/ssot.json gate entry, so the registry stays complete |
Add a new gates[] entry for hooks/check-merge-pull-request-block.sh, mirroring the existing pr-duplicate-issue entry's field shape/order, with rule text extracted from that script's own header comment rather than restated from memory |
Add one entry to .gitapex/ssot.json's gates[] array; no existing entry modified |
tests/test_gitapex_scan_ssot_schema.py (schema validity, id uniqueness, script-path existence, cluster resolution) passing on the new entry |
The diff's own shape (touching both .gitapex/ssot.json and hooks/hooks.json) triggers a mandatory deterministic-gate-quality skill-audit disclosure on the implementing PR -- accepted, not a defect |
Constraints
- No change to any hook's actual runtime behavior -- documentation/registry
consolidation only. - Every issue number currently named in
hooks.json's own description must
either already resolve inside.gitapex/ssot.jsonor be added by this
same change -- nothing may simply disappear.
Non-goals
- Does not touch any other
hooks.jsonfield (command,timeout,
matchervalues) or any other existing.gitapex/ssot.jsongate entry. - Does not address the three sibling PreToolUse hooks' own jq-coalescing
bug named as a follow-up in PR fix(dedup): add deterministic duplicate-work checks for PRs and issues #1215's own Risk/blast-radius section --
that is separate, already-flagged follow-up work, out of this issue's
scope. - Does not extend to
.github/workflows/*.ymlfiles' own duplicated
rationale prose -- that is issue CI gate workflows: centralize duplicated cross-workflow rationale prose into one shared reference doc #1186's own, distinct scope (see Dedup
below).
Dedup
Dedup: search_issues query "consolidate hooks.json description into
ssot.json gate registry, remove duplicated rationale", 3 results reviewed
-- none duplicate this issue (detail below).
- CI gate workflows: centralize duplicated cross-workflow rationale prose into one shared reference doc #1186 (open) -- related in spirit (de-duplicating rationale prose) but a
distinct scope: centralizing rationale repeated across multiple
.github/workflows/*.ymlfiles' own header comments into a new shared
doc, nothooks/hooks.json's description field, and not consolidating
into an already-existing structured registry. Not a duplicate; no fold-in. - refactor(gates): extract shared JSON-schema load/validate helper #755 (closed) -- unrelated (a JSON-schema load/validate helper
extraction). - feat(cli): define .gitapex/ssot.json gate-registry schema (child of #82) #123 (closed) -- the original issue that specced
.gitapex/ssot.json's
own schema; this issue extends that registry, doesn't duplicate its
creation.
Next Move
Draft ready to create as-is; no open question blocks filing it.
Activity
test(gate-local-preflight): fix exclusion-count drift after main merge