mirror of
https://github.com/nearai/ironclaw.git
synced 2026-09-03 08:06:01 +08:00
3fd143933a
* 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>
53 lines
2.5 KiB
Markdown
53 lines
2.5 KiB
Markdown
# 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` <!-- check-guidance: path-ok --> 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!`.
|