Skip to content

Dogfood knowledge-system: init + curate plugin-design learnings - #13

Merged
gering merged 2 commits into
mainfrom
task/dogfood-knowledge-system
Jun 19, 2026
Merged

Dogfood knowledge-system: init + curate plugin-design learnings#13
gering merged 2 commits into
mainfrom
task/dogfood-knowledge-system

Conversation

@gering

@gering gering commented Jun 18, 2026

Copy link
Copy Markdown
Owner

Summary

  • Bootstraps this repo's own knowledge base with its flagship plugin — meta-dogfooding from architecture review Prio 7.
  • Runs /init, curates 5 learnings by hand, backfills 4 from PR history, and verifies /query + /prime against the new base.
  • Surfaced two /init UX gaps in the process (tracked as a separate follow-up task harden-init-scaffolding).

Changes

Readiness

  • ✅ Knowledge — the entire PR is curation
  • ✅ Version — no plugin functionality changed; no bump needed (plugin.json ↔ marketplace.json in sync)
  • ✅ Structure check — scripts/check-structure.py green (0 errors)
  • ➖ README / Changelog / Tests / Lint / Build — N/A for a project-knowledge change (no plugin/skill add/rename, no test runner, no build step)
  • ℹ️ TASK.md left untracked (work-system working artifact, intentionally not part of this PR)

Test plan

  • /prime loads exactly the 3 architecture/ docs into context
  • /query "why does /query use Haiku?" resolves via the index to model-economics.md
  • CLAUDE.md shows a single ## Project Knowledge System section (marker-wrapped, no duplicate)

🤖 Generated with Claude Code

gering and others added 2 commits June 18, 2026 20:35
@gering @claude
Dogfood knowledge-system: init + curate plugin-design learnings
c93c818 
Bootstrap this repo's own knowledge base with its flagship plugin
(architecture review Prio 7 — meta-dogfooding).

- Run /init: scaffold .claude/knowledge + .claude/rules, plugin-managed
  usage rule, CLAUDE.md marker block (reconcile pre-existing manual
  "Project Knowledge System" section into the block)
- Curate 5 learnings by hand: skill-design conventions, skill
  composition, model economics (architecture/, prime:true); cwd-safety,
  version-sync (rules)
- Backfill 4 from PR history: /backfill-knowledge + origin metadata
  (#2), statusline integration (#3), CI structure checks (#6),
  per-project rule surface (#8)
- Verify /query (Haiku subagent resolves index -> file) and /prime
  (selects the 3 architecture docs) against the new base

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@gering @claude
Fix code-review findings in curated knowledge
5a5b605 
Address an xhigh /code-review of the dogfooding content.

Factual corrections:
- skill-composition: claude-review.sh is shared by 5 skills (check, cycle,
  merge, open, rebase), not "three (/cycle, /check, /fix)" — /fix is not a
  caller; fix the file paths (scripts/, docs/); trim re-encoded /rebase flag
  mechanics to the principle + a pointer to the rebase skill
- skill-composition: the /open vs /merge readiness "anti-pattern" was already
  resolved via the shared docs/READINESS-CHECKS.md — reframe as the remedy
- statusline: correct the callable renderer name (~/.claude/cks-statusline.sh),
  add scripts/statusline-install.sh, drop the unsourced "plugins cannot own
  statusLine.command" claim
- backfill: defer the origin cascade to /reindex step B instead of an
  inaccurate 3-step enumeration that hid the merge-commit fallback

Convention / duplication:
- remove rules/version-sync.md — it duplicated CLAUDE.md's always-loaded
  Versioning section (and its comma-string globs would not scope)
- skill-design-conventions: replace the verbatim convention list with a pointer
  to CLAUDE.md (keep the deeper mechanism/rationale)
- ci-structure-checks: reference the script's DESC_WORDS_* constants instead of
  hardcoding the literal thresholds
- de-link cross-layer [[wikilinks]] that pointed at rule files

Metadata:
- bump pluginVersion 1.7.0 -> 1.8.0 across all six knowledge files

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@gering
gering merged commit 275fc67 into main Jun 19, 2026
1 check passed
@gering
gering deleted the task/dogfood-knowledge-system branch June 19, 2026 10:16
@gering gering mentioned this pull request Jun 21, 2026
Merged
3 tasks
gering added a commit that referenced this pull request Jun 22, 2026
@gering @claude
Improve knowledge curation grounding and staleness detection
0a58931 
Reduce factual-error / duplication / staleness rate of curated knowledge
(systemic follow-up to PR #13 dogfooding defects).

- /curate: add grounding gate (claims must come from a file read this run,
  not memory), prefer linking mutable specifics over copying them
- /curate: extend dedup to always-loaded surfaces (CLAUDE.md, rules, memory)
- /curate: read pluginVersion fresh from plugin.json so it can't go stale
- /curate + /reindex: document link convention (markdown, knowledge<->knowledge,
  no wikilinks)
- /backfill-knowledge: require source-grounded learnings, flag inference vs
  fact, reject unsourced claims
- /reindex: add staleness net (stale-vs-source, verbatim restatement),
  validate link convention and cross-layer dangling, dedup vs always-loaded
- Bump knowledge-system 1.8.0 -> 1.8.1

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
gering added a commit that referenced this pull request Jun 22, 2026
@gering @claude
Improve knowledge curation grounding and staleness detection
7a0147b 
Reduce factual-error / duplication / staleness rate of curated knowledge
(systemic follow-up to PR #13 dogfooding defects).

- /curate: add grounding gate (claims must come from a file read this run,
  not memory), prefer linking mutable specifics over copying them
- /curate: extend dedup to always-loaded surfaces (CLAUDE.md, rules, memory)
- /curate: read pluginVersion fresh from plugin.json so it can't go stale
- /curate + /reindex: document link convention (markdown, knowledge<->knowledge,
  no wikilinks)
- /backfill-knowledge: require source-grounded learnings, flag inference vs
  fact, reject unsourced claims
- /reindex: add staleness net (stale-vs-source, verbatim restatement),
  validate link convention and cross-layer dangling, dedup vs always-loaded
- Bump knowledge-system 1.8.0 -> 1.8.1

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
gering added a commit that referenced this pull request Jul 16, 2026
@gering @claude
Address swarm self-review findings on the lens-set feature
f9bd70f 
First dogfooding run: /swarm:review --fix over its own diff (4 cluster
finders + codex + grok-4.5 + composer; 13 findings, 5 cross-family
consensus). Fixes the agreed findings:

- Keep validly tagged off-cluster lens prefixes: validate against the
  global lens set, not the finder's subset — coercion could flip kind
  and route a real defect through the applicability verifier (#1, consensus critical)
- Verify design clusters even with cross-family consensus: agreement
  attests agreement, not repo-grounded applicability (externals cannot
  open repo files); defect consensus stays auto-accepted (#2)
- Untagged external findings ('unspecified' lens) no longer vote in the
  cluster-kind derivation (#3)
- Derive CANDIDATE_LENSES from LENS_CLUSTERS — one list, no unchecked
  mirror; DRIFT WARNING on the SKILL.md external-prompt copy (#4, #9)
- Finder prompt: "issue (defect or substantive improvement)" + all lens
  prefixes; external prompt lead covers design improvements too (#5, #6)
- pr-post.py owns design-row ordering + [lens] prefixing via optional
  kind/lens row fields, unit-tested; SKILL.md step 5 passes rows through
  verbatim (#13)
- Doc sync: balance-spec finder count, README canonical cluster names +
  preset teaser wording, knowledge-index line trimmed (#8, #10, #11, #12)

Declined: #7 (per-cluster dilutes per-lens depth) — deliberate,
documented cost/coverage trade-off; --max is the depth profile.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0126cGxsBYxqgEFH4AcpriNk
gering added a commit that referenced this pull request Jul 16, 2026
@gering @claude
Address --max swarm self-review findings
005246f 
Second dogfooding round at the deepest profile (/swarm:review --max --fix:
per-lens split live — gate pruned style, 10 xhigh finders + codex
gpt-5.6-sol@xhigh + grok-4.5 + composer; 24 findings, 10 consensus).
Fixes the agreed findings:

- Never auto-accept an all-untagged consensus cluster: no tagged lens
  backs it, so it is verified like a solo. Verify/auto-accept now derive
  from ONE needsVerify predicate (structural exactly-once partition);
  kind vote in clearer every-form (#1, consensus critical; #21, #22)
- Design verifier sees the finding's recommendation — the proposal the
  applicability rubric actually tests — and carries an escape hatch:
  a genuine defect mis-filed under a design lens is not refuted away
  (#12, #3); "solo" dropped from verifier prompts (#4)
- Untagged findings from multi-lens cluster finders fall back to
  'unspecified' (safe defect bucket), not lenses[0] (#7); merge-agent
  free-text lens validated, majority-member fallback (#9)
- Improvement invitation scoped to design finder units — defect-lens
  finders stay defect-only (#8); merge prompt clusters by issue, not
  only defect (#13); schema descriptions generalized for design
  findings (#14)
- LENS_BRIEF startup assertion (#6); gate prompt interpolates
  LENS_CLUSTERS.design (#19); new test_lens_sync.py guards all lens
  mirrors: SKILL HDR prompt, LENS_BRIEF, pr-post DESIGN_LENSES (#5)
- Workflow assigns stable finding num (defects first, shared sequence);
  presenter/pr-post render it verbatim (#20)
- pr-post.py: design lens is the backup kind signal when the handoff
  drops kind (explicit defect still wins); single-pass partition (#17, #24)
- Balance: REFUTED is its own segment (refuted ⊄ solo since design
  consensus can be refuted) (#2); LOCKED design-table column precedence
  in --loop rounds clarified (#11); "verifies solos" doc sweep across
  manifests/README/knowledge (#4); cluster failure-isolation trade-off
  documented (#10); knowledge index line trimmed (#15)

Declined: #16 (JS test harness for sandbox code; lens-sync test covers
the drift class), #18 (gate-fail under --max runs all lenses — the
documented never-silently-narrower degrade), #23 (micro-opt vs readability).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0126cGxsBYxqgEFH4AcpriNk
gering added a commit that referenced this pull request Jul 17, 2026
@gering @claude
Address swarm self-review findings on the lens-set feature
79b75ae 
First dogfooding run: /swarm:review --fix over its own diff (4 cluster
finders + codex + grok-4.5 + composer; 13 findings, 5 cross-family
consensus). Fixes the agreed findings:

- Keep validly tagged off-cluster lens prefixes: validate against the
  global lens set, not the finder's subset — coercion could flip kind
  and route a real defect through the applicability verifier (#1, consensus critical)
- Verify design clusters even with cross-family consensus: agreement
  attests agreement, not repo-grounded applicability (externals cannot
  open repo files); defect consensus stays auto-accepted (#2)
- Untagged external findings ('unspecified' lens) no longer vote in the
  cluster-kind derivation (#3)
- Derive CANDIDATE_LENSES from LENS_CLUSTERS — one list, no unchecked
  mirror; DRIFT WARNING on the SKILL.md external-prompt copy (#4, #9)
- Finder prompt: "issue (defect or substantive improvement)" + all lens
  prefixes; external prompt lead covers design improvements too (#5, #6)
- pr-post.py owns design-row ordering + [lens] prefixing via optional
  kind/lens row fields, unit-tested; SKILL.md step 5 passes rows through
  verbatim (#13)
- Doc sync: balance-spec finder count, README canonical cluster names +
  preset teaser wording, knowledge-index line trimmed (#8, #10, #11, #12)

Declined: #7 (per-cluster dilutes per-lens depth) — deliberate,
documented cost/coverage trade-off; --max is the depth profile.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0126cGxsBYxqgEFH4AcpriNk
gering added a commit that referenced this pull request Jul 17, 2026
@gering @claude
Address --max swarm self-review findings
9ff85f3 
Second dogfooding round at the deepest profile (/swarm:review --max --fix:
per-lens split live — gate pruned style, 10 xhigh finders + codex
gpt-5.6-sol@xhigh + grok-4.5 + composer; 24 findings, 10 consensus).
Fixes the agreed findings:

- Never auto-accept an all-untagged consensus cluster: no tagged lens
  backs it, so it is verified like a solo. Verify/auto-accept now derive
  from ONE needsVerify predicate (structural exactly-once partition);
  kind vote in clearer every-form (#1, consensus critical; #21, #22)
- Design verifier sees the finding's recommendation — the proposal the
  applicability rubric actually tests — and carries an escape hatch:
  a genuine defect mis-filed under a design lens is not refuted away
  (#12, #3); "solo" dropped from verifier prompts (#4)
- Untagged findings from multi-lens cluster finders fall back to
  'unspecified' (safe defect bucket), not lenses[0] (#7); merge-agent
  free-text lens validated, majority-member fallback (#9)
- Improvement invitation scoped to design finder units — defect-lens
  finders stay defect-only (#8); merge prompt clusters by issue, not
  only defect (#13); schema descriptions generalized for design
  findings (#14)
- LENS_BRIEF startup assertion (#6); gate prompt interpolates
  LENS_CLUSTERS.design (#19); new test_lens_sync.py guards all lens
  mirrors: SKILL HDR prompt, LENS_BRIEF, pr-post DESIGN_LENSES (#5)
- Workflow assigns stable finding num (defects first, shared sequence);
  presenter/pr-post render it verbatim (#20)
- pr-post.py: design lens is the backup kind signal when the handoff
  drops kind (explicit defect still wins); single-pass partition (#17, #24)
- Balance: REFUTED is its own segment (refuted ⊄ solo since design
  consensus can be refuted) (#2); LOCKED design-table column precedence
  in --loop rounds clarified (#11); "verifies solos" doc sweep across
  manifests/README/knowledge (#4); cluster failure-isolation trade-off
  documented (#10); knowledge index line trimmed (#15)

Declined: #16 (JS test harness for sandbox code; lens-sync test covers
the drift class), #18 (gate-fail under --max runs all lenses — the
documented never-silently-narrower degrade), #23 (micro-opt vs readability).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0126cGxsBYxqgEFH4AcpriNk
gering added a commit that referenced this pull request Jul 17, 2026
@gering @claude
Address swarm self-review findings on the lens-set feature
5dc3f71 
First dogfooding run: /swarm:review --fix over its own diff (4 cluster
finders + codex + grok-4.5 + composer; 13 findings, 5 cross-family
consensus). Fixes the agreed findings:

- Keep validly tagged off-cluster lens prefixes: validate against the
  global lens set, not the finder's subset — coercion could flip kind
  and route a real defect through the applicability verifier (#1, consensus critical)
- Verify design clusters even with cross-family consensus: agreement
  attests agreement, not repo-grounded applicability (externals cannot
  open repo files); defect consensus stays auto-accepted (#2)
- Untagged external findings ('unspecified' lens) no longer vote in the
  cluster-kind derivation (#3)
- Derive CANDIDATE_LENSES from LENS_CLUSTERS — one list, no unchecked
  mirror; DRIFT WARNING on the SKILL.md external-prompt copy (#4, #9)
- Finder prompt: "issue (defect or substantive improvement)" + all lens
  prefixes; external prompt lead covers design improvements too (#5, #6)
- pr-post.py owns design-row ordering + [lens] prefixing via optional
  kind/lens row fields, unit-tested; SKILL.md step 5 passes rows through
  verbatim (#13)
- Doc sync: balance-spec finder count, README canonical cluster names +
  preset teaser wording, knowledge-index line trimmed (#8, #10, #11, #12)

Declined: #7 (per-cluster dilutes per-lens depth) — deliberate,
documented cost/coverage trade-off; --max is the depth profile.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0126cGxsBYxqgEFH4AcpriNk
gering added a commit that referenced this pull request Jul 17, 2026
@gering @claude
Address --max swarm self-review findings
2be83aa 
Second dogfooding round at the deepest profile (/swarm:review --max --fix:
per-lens split live — gate pruned style, 10 xhigh finders + codex
gpt-5.6-sol@xhigh + grok-4.5 + composer; 24 findings, 10 consensus).
Fixes the agreed findings:

- Never auto-accept an all-untagged consensus cluster: no tagged lens
  backs it, so it is verified like a solo. Verify/auto-accept now derive
  from ONE needsVerify predicate (structural exactly-once partition);
  kind vote in clearer every-form (#1, consensus critical; #21, #22)
- Design verifier sees the finding's recommendation — the proposal the
  applicability rubric actually tests — and carries an escape hatch:
  a genuine defect mis-filed under a design lens is not refuted away
  (#12, #3); "solo" dropped from verifier prompts (#4)
- Untagged findings from multi-lens cluster finders fall back to
  'unspecified' (safe defect bucket), not lenses[0] (#7); merge-agent
  free-text lens validated, majority-member fallback (#9)
- Improvement invitation scoped to design finder units — defect-lens
  finders stay defect-only (#8); merge prompt clusters by issue, not
  only defect (#13); schema descriptions generalized for design
  findings (#14)
- LENS_BRIEF startup assertion (#6); gate prompt interpolates
  LENS_CLUSTERS.design (#19); new test_lens_sync.py guards all lens
  mirrors: SKILL HDR prompt, LENS_BRIEF, pr-post DESIGN_LENSES (#5)
- Workflow assigns stable finding num (defects first, shared sequence);
  presenter/pr-post render it verbatim (#20)
- pr-post.py: design lens is the backup kind signal when the handoff
  drops kind (explicit defect still wins); single-pass partition (#17, #24)
- Balance: REFUTED is its own segment (refuted ⊄ solo since design
  consensus can be refuted) (#2); LOCKED design-table column precedence
  in --loop rounds clarified (#11); "verifies solos" doc sweep across
  manifests/README/knowledge (#4); cluster failure-isolation trade-off
  documented (#10); knowledge index line trimmed (#15)

Declined: #16 (JS test harness for sandbox code; lens-sync test covers
the drift class), #18 (gate-fail under --max runs all lenses — the
documented never-silently-narrower degrade), #23 (micro-opt vs readability).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0126cGxsBYxqgEFH4AcpriNk
gering added a commit that referenced this pull request Jul 25, 2026
@gering @claude
Address swarm review findings on the lane registry
4f29afb 
Apply the agreed findings from a local swarm review (11 ✅ + 1 🟨; the 3 ❌ —
a feature version bump, a README inventory line, and a per-subcommand python3
guard — were deliberately left, see the PR discussion).

herdr-agent.sh:
- Bound herdr list/get/read with a wall-clock timeout (_ha_bounded: timeout →
  gtimeout → perl alarm), honouring the header's "never a hang" promise. wait
  stays governed by its own --timeout. (#6)
- ha_wait now detects the --timeout=MS form too, so a caller's explicit bound in
  either spelling is honoured and no duplicate flag is appended. (#7)
- A missing <target> returns usage code 2, not 4 (server-unreachable), so a
  programmer error is not mistaken for a transient outage. (#12)
- set -u is enabled only on the executed-CLI path, never at source time, so
  sourcing for the prelude/helpers no longer mutates the caller's shell. (#13)
- classify_cwd returns the resolved path as a third tuple element, so a caller
  keying by full path reuses it instead of a second realpath. (#14)

lanes.sh:
- Scrub tab/CR/LF from every TSV cell: agent-derived fields are untrusted, and an
  embedded tab/newline would forge columns/rows. Mirrors herdr-tab-glyph. (#1)
- Guard the agent loop against non-dict (null) elements → never crash, always
  exit 0. (#2)
- flush() now calls the shared classify_cwd instead of re-open-coding the task
  rule, so the classification can't drift between the two consumers. (#15)
- Resolve SCRIPT_DIR via BASH_SOURCE (robust to bare-name invocation). (#5)
- Header wording: exit-0 scope clarified; --json emits [] when no lanes. (#3, #8)

herdr-tab-glyph.sh: consume classify_cwd's new 3-tuple; same BASH_SOURCE fix (#5).
herdr-tab-glyphs.md: point at $HERDR_MATCH_PRELUDE as the shared match SoT. (#10)
Tests extended: null-element + TSV-injection (lanes); --timeout= + missing-target
exit 2 (herdr-agent). Regression: herdr-tab-glyph output byte-identical vs a live
snapshot.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8crYp6tzRKMiwW63Zt3GG
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@gering