ae791781c22b150baaad9f095c9703ff28fb546c
7 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
| ee248ff5a5 |
docs: describe the boundary check's new outcomes and de-pin stale counts
The gate spec still described the routing-target check as pass/fail against a single-arrow clause. It now documents the three outcomes, the hand-invocation carve-out and the one-arrow rule, so a contributor hitting a SUGGESTION can tell whether it is a real defect or accepted phrasing. Both files cited skill counts and source line numbers that go stale on the next edit and were already wrong; those citations are removed rather than refreshed. |
|||
| c7c9311d80 |
docs(gates): refresh the retrofit status to measured state
docs/spec/gates.md still described both ADR-0020 gates as "currently red"
and tabled the pre-retrofit figures: 26 of 39 descriptions and 9 of 39
bodies over their FAIL tier, 2 dangling targets, 58 SUGGESTIONs, and 10
Kyberforge.CompositionNote errors across four gitea-* skills. Measured
now: 0, 0, 0, 33 and 0.
The branch correctly left ADR-0020 itself untouched, since it self-pins
every citation to base commit
|
|||
| d42f6368fe |
fix(docs): correct claims the first fix round asserted without measuring
Why: two blind verifiers re-ran the five preceding commits and found four defects of the same class this branch exists to close -- a confidently stated measured claim that does not survive re-measurement -- this time inside the fixes themselves. - AGENTS.md:41 still carried both phrasings |
|||
| c68e864159 |
docs(spec): correct eight claims the trim carried into the new files
Why: the relocation into gates.md and architecture.md moved text faster than it
verified it, and a review found eight assertions that do not survive contact
with the repo.
- gates.md cited docs/research/examples/, which does not exist; the tree is at
plugins/kyberforge/docs/research/examples/. The same wrong string survives at
ADR-0013:98, where it originated, and is tracked separately.
- gates.md's description-budget arithmetic was built on 23,427, a figure
ADR-0020 measured at
|
|||
| b0ef503485 |
docs: correct plugin scope, hook ordering and the setup gap
Why: the review found architecture.md's plugin table and README's plugin list
were both written by enumerating what happened to be in each plugin, so both
went stale immediately — README credited `git` with pull requests it has no
skill for, and both omitted `pc-author`/`pc-run`.
|
|||
| b9c7762463 |
docs: trim CONTEXT.md to a glossary and demote VISION.md
Why: CONTEXT.md is an instructed every-session read at 33,799 bytes (~8,450
tokens), and CONTEXT.md:17 layered docs/VISION.md on top. After the AGENTS.md
trim, that left ~9,650 tokens of instructed reads sitting behind a file whose
own format contract — grill-with-docs/CONTEXT-FORMAT.md:43, "Keep definitions
tight. One sentence max." — it was not following. 22 glossary entries averaged
190 words; the top four were 55% of the file, and one ("Vale audit prefilter")
was 1,444 words of pre-commit forensics filed as a definition.
Implementation notes:
- CONTEXT.md rewritten to CONTEXT-FORMAT.md's prescribed template: ## Language
(five clusters, 22 terms with _Avoid_ aliases), ## Relationships,
## Example dialogue, ## Flagged ambiguities. 33,799 -> 9,762 bytes.
- Vale prefilter forensics moved to docs/spec/gates.md under nine subsections:
the two-copy style layout, vale-wrap.sh and the Vale 3.15.2
text.frontmatter.description limitation, the --config argv defect (E100),
glob scoping, the rule inventory, and 0-files-means-NOT-RUN.
- Instruction-file format and the bidirectional-reference principle moved to
docs/spec/architecture.md, the latter flagged as aspirational: no instruction
file carries a `when:` field, only 2 of 39 skills do, and the reference
scanner script it names does not exist.
- Added a per-plugin scope table to architecture.md so "which plugin owns this
skill" survives the trim, and corrected its claim that the content index
lives in providers/claude-code/CLAUDE.md — that file is now two import lines
and the index sits in core/AGENTS.md.
- "Repo and Gitea are the only source of truth" moved from CONTEXT.md's
Principles into AGENTS.md session rules; it was operative guidance in a
glossary. docs/VISION.md and LESSONS.md added to the on-demand list.
- The apm-consumed install entry (432 words) was deleted outright: all four
consequences are already carried by README.md, ADR-0018, gates.md and
AGENTS.md.
- ADR-0013, ADR-0015 and ADR-0017 each pointed at CONTEXT.md sections that
moved; amended with dated supersession notes rather than left dangling.
Impact: the every-session set drops from ~15,700 to ~4,140 tokens across both
passes (-74%). The deleted "lint plugin" entry was also stale on a safety
claim — it said lint-runner inherits Edit, but ADR-0016 restored
`disallowedTools: Edit, Write, NotebookEdit` and CONTEXT.md was never updated.
Refs: #99
|
|||
| 1929ffd2da |
docs: slim AGENTS.md to per-session context only
Why: AGENTS.md is preloaded into every session via CLAUDE.md's @AGENTS.md import, so every word is a tax paid whether or not it is relevant. It had grown to 3,371 words (~4,550 tokens), 75% of it a single "Setup and testing" section that was mostly neither: roughly 1,600 words were gate forensics — why a hook is shaped the way it is, what was tried and rejected, verification numbers — and only ~390 words were genuine one-time setup. Implementation notes: split three ways by audience rather than by heading. One-time setup, prerequisites and test commands move to a new root README.md, which did not previously exist. The gate forensics move to a new docs/spec/gates.md, preserving every constant, hook ID, error string and tried-and-rejected note (policy.fetch_failure_default, the removed fallback frontmatter reader, extending skill-size-check's files: pattern to agents, tidying .claude/settings.json out of the pretty-format-json exclude list) — these exist to stop settled decisions being re-litigated, so none were dropped. AGENTS.md keeps only what applies every session, at one clause of rationale per rule. The .apm/-mirror section collapses to a pointer because docs/spec/architecture.md already covers it in full. The hot ADR-0020 gate counts stay in AGENTS.md deliberately: they block any skill edit today. Also corrects docs/spec/architecture.md's stale claim of 19 ADRs; ADR-0020 landed without updating the count. Impact: per-session preload drops from ~4,550 to ~1,116 tokens, a 75% cut. agentsmd-audit passes: secrets clean, drift clean, 4 informational findings for sections deliberately relocated to the README. |
