lywsvip/ironclaw
1
0
Fork 0
mirror of https://github.com/nearai/ironclaw.git synced 2026-09-02 23:56:24 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
docs/webui-design-system-governance
ironclaw/CLAUDE.md
Henry Park 3fd143933a docs(guidance): repo-wide agent-guidance audit — fix drift, prune 21.5k lines, consolidate tests/ onto AGENTS.md convention (#7797) 
* docs(guidance): repo-wide agent-guidance audit — fix drift, prune 21.5k lines, consolidate tests/ onto AGENTS.md convention

Full-layer audit of the agent-guidance system (root contracts, .claude rules/
skills/commands, family and crate AGENTS.md, CONTRACT specs, tests guidance,
docs/internal), verified reference-by-reference against HEAD.

- Fix stale/ghost references: UserSandboxProcessPort, ProductSurfaceError,
  LlmError::ContextLengthExceeded, INVERTED_PORT_IMPLEMENTORS, split channel
  traits (ChannelIngress/ChannelReply/ChannelDelivery), memory-native's
  never-implemented EmbeddingProvider seam, wrong layer/crate/module counts.
- Convert unpinned prose numbers to regeneration commands or pinning-test
  citations across root, family, and crate guidance (drift-proofing).
- tests/: rename CLAUDE.md -> AGENTS.md with CLAUDE.md symlinks (crates/
  convention), extend scripts/ci/check-guidance.py discovery to tests/,
  delete stale e2e scenario tables, dedupe tier taxonomy against
  .claude/rules/testing.md.
- Commands/skills: delete six dead v1 commands (add-tool, review-pr,
  review-crate, fix-issue, respond-pr, add-sse-event) and the v1-teaching
  architecture-video skill; convert ironclaw-reborn-skill-maintainer into
  the auto-loading rule .claude/rules/guidance-maintenance.md; fix clippy
  -D warnings and portable date in surviving commands; triggers-only
  frontmatter; add automations section to reborn-feature.
- Rules: rename gateway-events.md -> events.md; revive
  scripts/check-type-duplicates.py (glob matched zero types since the
  family reorg); index all 15 rules in root AGENTS.md for Codex parity.
- docs/internal: delete 70 superseded plans/specs/design docs (~21.5k
  lines, each re-verified unreferenced); fix misleading v1-migration
  status lines; rewrite the contracts index as a recipe; restore two docs
  that proved live-referenced.
- Trim composition CONTRACT.md route-mirror sections (invariants kept).

Verified: check-guidance.py (384 files, 0 grandfathered),
docs_publication_boundary.py, cargo test -p ironclaw_architecture_tests,
scripts/ci test-plan suite (87/87) — all green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(guidance): address PR #7797 review comments

Verified each of the ~40 bot/reviewer findings against the tree; applied the
valid mechanical fixes, rebutted the rest with evidence (see PR comment).

- Test planner: add renamed tests/ guidance aliases to IGNORED_GUIDANCE_PATHS
  (reproduced the fail-closed abort on this PR's own changed-file list) and
  extend the planner test to all six guidance paths.
- check-guidance: add self-tests proving tests/-tree discovery and alias
  enforcement (48 tests, was 46); new self-test file for
  check-type-duplicates.py (4 tests).
- Portability: replace GNU-only date -d in triage commands with a python3
  one-liner (works on macOS BSD and Linux).
- Count/claim accuracy: product_contracts manager-port prose 4 -> 3 (matches
  INVERTED_PORT_IMPLEMENTORS), kernel grep -cF for literal #[test] (was regex
  char class, 2 vs 23), rg -o|wc -l for a true total in architecture.md,
  Rust-scoped LlmProvider count (catches 5 generic impls), measured
  1/73-crate dual-backend claim in pr-shepherd, executable wc -l in
  assistant guidance, AST/pytest recipes for the e2e test-count figures.
- Content: deslop co-author line no longer hardcodes an address; ship.md
  surfaces Postgres-skip counts; risk-label guidance documents the crates/**
  labeler blind spot; e2e authoring recipe leads with reborn_v2_* fixtures;
  stale CLAUDE.md line citation replaced with a stable anchor; ✎ provenance
  notes for two deleted-plan citations; unified-channel-model status text
  reconciled with an explicit ChannelDelivery-only exception note.

Gates: check-guidance (384 files, 0 grandfathered), docs boundary, planner
tests 87/87, check-guidance self-test 48/48, type-dup self-test 4/4 - green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(ci): classify scripts/test-check-type-duplicates.py in the PR test planner

The self-test added in 77bc8f8c5 was never registered in
PR_STATIC_CONTROL_PATHS, so the planner's fail-closed unmapped-path arm
aborted 'Detect Reborn test scope' and cascaded into the whole Reborn
matrix skipping. Classified like its subject (deliberately CI-unwired
local dev tool, per the existing entry's rationale) and pinned in the
static-control planner test alongside it.

Verified: planner tests OK; planner run against this PR's full
changed-file list now returns mode=selected with the path owned by
static checks.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(docs): drop parity-QA path reference from tests/integration/AGENTS.md

The guidance dedup in this PR added a literal
tests/support/reborn_parity_qa reference to tests/integration guidance,
which scripts/ci/check-test-suite-boundaries.sh correctly flags: the
one-way dependency guard covers docs too, and origin/main's version of
this file carried no such reference. Fix the content, not the check -
the tier comparison is reworded to describe the RebornBinaryE2EHarness
seam difference without naming the parity/QA tree.

Verified: check-test-suite-boundaries.sh OK; check-guidance OK; the
full 'Detect Reborn test scope' job reproduced locally end-to-end.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci: run the type-duplicates self-test in Code Style; exercise the production report path

Address the two follow-up review findings on 77bc8f8c5/9ed30caf8:

- Wire scripts/test-check-type-duplicates.py into code_style.yml's
  Static-check self-tests step (next to test-check-guidance.py) so the
  regression test is actually enforced; update the planner's
  PR_STATIC_CONTROL_PATHS comment accordingly (classification unchanged
  - Code Style is the static lane).
- Strengthen the semantic-duplicate self-test to also drive the
  production main() report path and assert on its printed candidate
  output, instead of only re-computing similarity locally. Strictly
  stronger; the other three tests are untouched.

Verified: self-test 4/4, planner tests 87/87, workflow-contract
self-test 94/94, planner simulation over both changed paths classifies
cleanly (no unmapped-path abort).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci: trigger fast-checks on type-duplicates script changes; symbol recipe for the tier reference

- code_style.yml's has_code filter covered scripts/ci/ but not the bare
  scripts/ type-duplicates pair, so a diff touching only the new
  self-test skipped the fast-checks job that runs it (the previous
  commit's 'runs unconditionally' claim was wrong - corrected the
  planner comment too). Added the two files to the filter following the
  check_no_panics precedent and pinned them as in_scope probes in the
  ws12 workflow-contracts routing test.
- tests/integration/AGENTS.md tier reference is now re-verifiable via a
  single-hit symbol recipe (rg 'struct RebornBinaryE2EHarness') instead
  of a path citation, which the test-suite boundary guard forbids from
  this subtree.

Verified: ws12 workflow contracts 94/94, planner tests 87/87,
check-test-suite-boundaries OK, check-guidance OK.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Henry Park <16583448+henrypark133@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-21 21:26:50 +00:00

2.5 KiB
Raw Permalink Blame History

IronClaw — Claude Code adapter

@AGENTS.md

Everything above (from AGENTS.md) is the canonical, tool-neutral contract. The rest of this file is Claude-specific.

Skills and rules

  • Project skills live in .claude/skills/ — start from ironclaw-reborn-orientation; use reborn-feature for cross-layer product work, reborn-extension-surfaces for integrations, ironclaw-reborn-testing for test tiers, and ironclaw-reborn-architecture-review for boundary changes.
  • Path-scoped rules in .claude/rules/*.md load automatically when you read matching files — they are canonical for their topics (testing, database, types, cargo-features, review discipline, guidance maintenance, …); do not restate them here. Guidance edits (.claude/**, any AGENTS.md/CLAUDE.md, runtime skills/) are governed by .claude/rules/guidance-maintenance.md.

Codebase knowledge graph (MCP)

The codebase-memory MCP server indexes crates/ into a knowledge graph; prefer it over Grep for code structure (cross-crate call chains are invisible to text search). .codebase-memory/graph.db.zst is the committed bootstrap snapshot; local databases and .codebase-memory/artifact.json stay git-ignored (per-environment state, deliberately untracked). Check freshness first: bash scripts/codebase-graph.sh status.

  • Missing → index_repository(repo_path=".", persistence=true) once.
  • Stale → detect_changes(since="<indexed-commit>"), or re-run index_repository to refresh the shared snapshot.
  • Where is a symbol → search_graph(name_pattern=…), then get_code_snippet(qualified_name=…).
  • Who calls X / what X calls → trace_path(function_name=…, mode="calls"); value flow → mode="data_flow"; cross-crate feature path → mode="cross_service".
  • Structure of an area → get_architecture(…); graph-augmented text search → search_code(pattern=…); arbitrary queries → query_graph(<Cypher>).

The graph is a point-in-time index — verify anything it asserts against live code before acting. Grep/Glob/Read remain correct for text, config, and non-code files. For narrative what/why orientation, read the relevant openwiki/ page (generated — never hand-edit).

REPL/TUI logging rule

info! and warn! output appears in the REPL and corrupts the terminal UI. Use debug! for internal diagnostics (trace analysis, reflection results, engine internals); reserve info! for user-facing status the REPL intentionally renders. Background tasks must NEVER use info!.

Reference in New Issue View Git Blame Copy Permalink