Move the Hook contract out of plugins/os-sdlc/CLAUDE.md after a CLAUDE.md best-practices ruling #1747

New issue

Open

opened 2026-11-13 12:39:50 +00:00 by jared · 0 comments

jared commented

2026-11-13 12:39:50 +00:00

Owner

Problem

plugins/os-sdlc/CLAUDE.md loads into every os-sdlc session, and about 75% of it is the "Hook contract" paragraph, which most sessions do not need. Jared's standard for a CLAUDE.md (2026-11-13) has three parts: (a) it orients the AI to navigate the project by progressive disclosure; (b) it holds only rules that are relevant to every session; (c) it holds no detail that matters only in specific situations. The Hook contract is type (c): hooks are deterministic and run in the background. Jared wants a separate session on CLAUDE.md best practices before any edit.

Observed

The file is 1,254 tokens. The Hook contract paragraph is about 3,760 bytes.
Two independent read-only assessments on 2026-11-13 agree on the history.
The section first entered on 2026-09-10 in 86f36f2a7, at about 650 bytes.
The section grew to about 4,000 bytes from 2026-09-27 to 2026-09-29 (#767, #781, #834).
Each later refactor commit rewrote the paragraph in place. The largest rewrite is b2187b6dc on 2026-11-10. Commits 86417907c, 39c877a11 and 6cc5095e4 on 2026-11-12 added about 580 bytes.
A git revert is not a fix. Each older version is as long and names deleted objects (OsSdlc::Boot.run, Boot::Commands::TABLE, Hook::Pipe).
No other copy of the text exists under docs/implementation-status/ or plugins/os-sdlc/references/.
The root CLAUDE.md is 2,246 tokens. Its shape has not changed since 2026-08-19 (fdd1f1e23). It grew from 1,647 tokens through one-line and two-line additions.

Reproduce

n/a: prose artifact; python3 plugins/os-doc-hygiene/scripts/token_estimator.py plugins/os-sdlc/CLAUDE.md prints the size.

Approach

Jared rules on CLAUDE.md best practices first, in a separate session. The items below are proposals for that session.

Move the Hook contract text, verbatim at HEAD, to a reference file (for example plugins/os-sdlc/references/hook-contract.md) and leave a one-line pointer in plugins/os-sdlc/CLAUDE.md. Estimated result: about 350 tokens.
Decide if one hook rule stays inline because it applies to each hook edit: "Add no field extraction to a hook; read new event fields with event.fetch(:key) or event[:key]."
Remove the cause: refactor commits update this paragraph in place. Find the instruction or habit that sends those updates to CLAUDE.md, and point it at the reference file.
Root CLAUDE.md: decide on a trim of the type (c) sections ("Token counting", "CRC refactor") and of the rule "When the change alters how a user runs an os-sdlc tool, update plugins/os-sdlc/README.md", which plugins/os-sdlc/CLAUDE.md already holds.

Rejected: restore an older version of either file — each older version is as long and has facts that are now false.

Origin

Trigger: Jared read plugins/os-sdlc/CLAUDE.md on 2026-11-13 and asked for an assessment and a possible revert.
Improvised this session: none
Chain: Hook contract is 75% of the file ← refactor commits rewrite the paragraph in place since 2026-09-27 (git log of plugins/os-sdlc/CLAUDE.md) ← no reference file owns the hook contract ← DESIGN (plugins/os-sdlc/CLAUDE.md, section "Hook contract", first added in 86f36f2a7)
Root candidate: none found; searched CLAUDE.md, hook contract, progressive disclosure, doc hygiene, context size, baseline tokens
Where: plugins/os-sdlc/CLAUDE.md, CLAUDE.md
Session: 74660e62-c65e-4fd6-98dd-4b93559cd779
Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os-plugins-os-sdlc/74660e62-c65e-4fd6-98dd-4b93559cd779.jsonl

VERDICT: CREATE — No open ticket covers moving the Hook contract out of plugins/os-sdlc/CLAUDE.md or a CLAUDE.md best-practices ruling; the user named this work.

## Problem `plugins/os-sdlc/CLAUDE.md` loads into every os-sdlc session, and about 75% of it is the "Hook contract" paragraph, which most sessions do not need. Jared's standard for a CLAUDE.md (2026-11-13) has three parts: (a) it orients the AI to navigate the project by progressive disclosure; (b) it holds only rules that are relevant to every session; (c) it holds no detail that matters only in specific situations. The Hook contract is type (c): hooks are deterministic and run in the background. Jared wants a separate session on CLAUDE.md best practices before any edit. ## Observed The file is 1,254 tokens. The Hook contract paragraph is about 3,760 bytes. Two independent read-only assessments on 2026-11-13 agree on the history. The section first entered on 2026-09-10 in 86f36f2a7, at about 650 bytes. The section grew to about 4,000 bytes from 2026-09-27 to 2026-09-29 (#767, #781, #834). Each later refactor commit rewrote the paragraph in place. The largest rewrite is b2187b6dc on 2026-11-10. Commits 86417907c, 39c877a11 and 6cc5095e4 on 2026-11-12 added about 580 bytes. A `git revert` is not a fix. Each older version is as long and names deleted objects (`OsSdlc::Boot.run`, `Boot::Commands::TABLE`, `Hook::Pipe`). No other copy of the text exists under `docs/implementation-status/` or `plugins/os-sdlc/references/`. The root `CLAUDE.md` is 2,246 tokens. Its shape has not changed since 2026-08-19 (fdd1f1e23). It grew from 1,647 tokens through one-line and two-line additions. ## Reproduce n/a: prose artifact; `python3 plugins/os-doc-hygiene/scripts/token_estimator.py plugins/os-sdlc/CLAUDE.md` prints the size. ## Approach Jared rules on CLAUDE.md best practices first, in a separate session. The items below are proposals for that session. - [ ] Move the Hook contract text, verbatim at HEAD, to a reference file (for example `plugins/os-sdlc/references/hook-contract.md`) and leave a one-line pointer in `plugins/os-sdlc/CLAUDE.md`. Estimated result: about 350 tokens. - [ ] Decide if one hook rule stays inline because it applies to each hook edit: "Add no field extraction to a hook; read new event fields with `event.fetch(:key)` or `event[:key]`." - [ ] Remove the cause: refactor commits update this paragraph in place. Find the instruction or habit that sends those updates to `CLAUDE.md`, and point it at the reference file. - [ ] Root `CLAUDE.md`: decide on a trim of the type (c) sections ("Token counting", "CRC refactor") and of the rule "When the change alters how a user runs an os-sdlc tool, update `plugins/os-sdlc/README.md`", which `plugins/os-sdlc/CLAUDE.md` already holds. Rejected: restore an older version of either file — each older version is as long and has facts that are now false. ## Origin - Trigger: Jared read `plugins/os-sdlc/CLAUDE.md` on 2026-11-13 and asked for an assessment and a possible revert. - Improvised this session: none - Chain: Hook contract is 75% of the file ← refactor commits rewrite the paragraph in place since 2026-09-27 (git log of `plugins/os-sdlc/CLAUDE.md`) ← no reference file owns the hook contract ← DESIGN (`plugins/os-sdlc/CLAUDE.md`, section "Hook contract", first added in 86f36f2a7) - Root candidate: none found; searched CLAUDE.md, hook contract, progressive disclosure, doc hygiene, context size, baseline tokens - Where: `plugins/os-sdlc/CLAUDE.md`, `CLAUDE.md` - Session: 74660e62-c65e-4fd6-98dd-4b93559cd779 - Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os-plugins-os-sdlc/74660e62-c65e-4fd6-98dd-4b93559cd779.jsonl VERDICT: CREATE — No open ticket covers moving the Hook contract out of plugins/os-sdlc/CLAUDE.md or a CLAUDE.md best-practices ruling; the user named this work.

jared added the

plugin/os-sdlc

filed-by/agent

category/owner-ruling

labels

2026-11-13 12:39:50 +00:00