docs(agents): accurate guidance, guardrail map, and check:guidance-refs by waleedlatif1 · Pull Request #8557 · simstudioai/sim

waleedlatif1 · 2026-10-02T03:01:19Z

Summary

New check:guidance-refs audit: scans CLAUDE.md, every AGENTS.md/CLAUDE.md, .claude/rules, and .agents/skills and fails when guidance names a repo path, script, skill, or @//@sim/ import that doesn't exist, or when a rule's paths: glob matches no file (which silently stops it loading). Fixed every stale reference it found
check:application-graph guarded the route wrapper against lib/copilot/, a directory that no longer exists; it now guards lib/mothership/
Guidance accuracy and consolidation: ~60 stale facts corrected against the code, contradictions resolved in favor of what the checks enforce, one source of truth per topic (text scale, 'use client' boundary, testing principles), change-history narration rewritten as current-state rules
CLAUDE.md gets "How your work is checked": the exact local gate (lint, type-check, check:audits, root test, plus check:migrations for migrations), the shrink-only baseline rule, and a table mapping written rules to the check that enforces them (including the new unused-exports, explicit-any, file-names, comment-hygiene, and unused-binding rules)
Comment guidance tightened: no narrating, restating names/types, or change history in comments

Type of Change

Documentation + audit tooling

Testing

bun run check:guidance-refs (76 documents), check:skills, bun run lint, bunx turbo run type-check, bun run check:audits (58), bun run test:scripts
New check proven able to fail on injected fake path/script/skill/import references

Checklist

Code follows project style guidelines
Self-reviewed my changes
Tests added/updated and passing (new tests pass the test-audit authoring gate)
No new warnings introduced
I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

🤖 Generated with Claude Code

vercel · 2026-10-02T03:01:23Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 2, 2026 8:49am UTC

greptile-apps · 2026-10-02T03:05:38Z

Confidence Score: 5/5

[Low risk] Updates agent guidance docs and adds a validation script.

The PR appears safe to merge; no new actionable issue or outstanding previous finding was identified.

Summary

The PR updates agent guidance, adds an audit for stale guidance references, and retargets the application-graph guard to the Mothership directory. The changes since the previous review add a repository-containment check for path references and extend fenced-code scanning to require.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Guidance documents] --> B[Extract paths, scripts, skills, imports, and rule globs]
  B --> C[Resolve against repository files and workspace manifests]
  C --> D{Unresolved reference?}
  D -- Yes --> E[Fail guidance audit]
  D -- No --> F[Pass guidance audit]

_{Reviews (8) · Last reviewed commit: "fix(audits): check require() specifiers ..."}

cubic-dev-ai

All reported issues were addressed across 72 files

_{Tip: instead of fixing issues one by one fix them all with cubic

Re-trigger cubic}

waleedlatif1 · 2026-10-02T04:58:54Z

@greptile

waleedlatif1 · 2026-10-02T07:33:16Z

@greptile

waleedlatif1 · 2026-10-02T07:33:18Z

@cubic-dev-ai review this PR

cubic-dev-ai · 2026-10-02T07:33:25Z

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

cubic-dev-ai

All reported issues were addressed across 73 files

_{Requires human review: Auto-approval blocked because this review re-detected 2 unresolved issues already reported by Cubic.
Tip: instead of fixing issues one by one fix them all with cubic

Re-trigger cubic}

waleedlatif1 · 2026-10-02T07:55:55Z

@greptile

waleedlatif1 · 2026-10-02T07:55:56Z

@cubic-dev-ai review this PR

cubic-dev-ai · 2026-10-02T07:56:03Z

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

cubic-dev-ai

All reported issues were addressed across 73 files

_{Tip: instead of fixing issues one by one fix them all with cubic

Re-trigger cubic}

waleedlatif1 · 2026-10-02T08:09:32Z

@greptile

waleedlatif1 · 2026-10-02T08:09:34Z

@cubic-dev-ai review this PR

cubic-dev-ai · 2026-10-02T08:09:39Z

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

cubic-dev-ai

All reported issues were addressed across 73 files

_{Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic}

…removed lib/copilot The Copilot modules moved to lib/mothership in the v1.0.0 rename, so the route-wrapper graph guard was banning a directory that no longer exists.

…nces it found Agent guidance (CLAUDE.md, every AGENTS.md, .claude/rules, .agents/skills) names paths, scripts, skills, and import specifiers that agents follow literally. The new audit resolves each one and fails on any that no longer exists. Fixes the references it found: lib/copilot -> lib/mothership, stores/workflows/store -> stores/workflows/workflow/store, a relative landing path, deleted selector-provider and legacy landing mentions, and illustrative example imports rewritten as placeholders.

A paths glob that matches nothing silently stops the rule from loading. sim-api-contracts still targeted the removed apps/sim/hooks/selectors; drop it, and name check:api-validation:strict as the gate the rule describes.

- CLAUDE.md: "How your work is checked" (the local gate and a rule-to-check map), sharper comment rules (no narration, restated names, or change history), drop filler, fix the type-check command description. - Rules: one source for the text scale (sim-styling), use-client boundary (sim-queries), testing principles (CLAUDE.md); fix an in-place sort in a list-ordering example and an ESLint directive the repo does not use; drop change-history narration and rotting line-number references.

Restore the connector byte-cap rule's skip list, list every CI gate step, name the real baseline flags and generated-artifact checks, make api-validation strict-only guidance explicit, pass a base ref to check-block-registry, and teach check:guidance-refs about bun run --cwd.

Name the enforcing check on the rule's own bullet instead, and tighten the Comments bullet.

…graph guards check:guidance-refs reuses sync-skills' parseRule, reads workspace manifests once from the root workspaces globs, and matches rule globs against one git listing instead of a filesystem scan per glob (~2.5s to ~0.2s). Markdown links now go through the shared path check. check:application-graph fails when a forbidden prefix matches nothing under apps/sim.

…d files and test-only guards check:guidance-refs now requires a bare @sim/<pkg> import to have a '.' export, checks that a wildcard export match maps to an existing file, and drops index entries missing from the working tree before matching rule path globs. check:application-graph no longer counts a leftover test file as keeping a non-directory forbidden prefix alive.

Scope SSRF, client-boundary, forcedToolUse, canonicalParamId, integration metadata, and HEAD claims to what the code does; fix the ship migration pathspec, the babysit conflict path, enrichment folder placeholders, framer-motion samples, and stale connector and column-type references.

…review-flagged guidance

…ebase

waleedlatif1 · 2026-10-02T08:20:16Z

@greptile

waleedlatif1 · 2026-10-02T08:20:19Z

@cubic-dev-ai review this PR

cubic-dev-ai · 2026-10-02T08:20:26Z

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

cubic-dev-ai

No issues found across 73 files

Confidence score: 5/5

Automated review surfaced no issues in the provided summaries.
No files require special attention.

_{You've manually re-run cubic several times on this PR. Each manual re-review checks the full PR again and counts toward your usage quota. To preserve your usage limits, we recommend letting cubic automatically review new commits.

Re-trigger cubic}

…wn links strictly

waleedlatif1 · 2026-10-02T08:34:43Z

@greptile

waleedlatif1 · 2026-10-02T08:34:44Z

@cubic-dev-ai review this PR

cubic-dev-ai · 2026-10-02T08:34:50Z

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

cubic-dev-ai

All reported issues were addressed across 73 files

_{You've manually re-run cubic several times on this PR. Each manual re-review checks the full PR again and counts toward your usage quota. To preserve your usage limits, we recommend letting cubic automatically review new commits.

Fix all with cubic | Re-trigger cubic}

…de the repo

waleedlatif1 · 2026-10-02T08:47:07Z

@greptile

waleedlatif1 · 2026-10-02T08:47:09Z

@cubic-dev-ai review this PR

cubic-dev-ai · 2026-10-02T08:47:15Z

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

cubic-dev-ai

All reported issues were addressed across 73 files

_{You've manually re-run cubic several times on this PR. Each manual re-review checks the full PR again and counts toward your usage quota. To preserve your usage limits, we recommend letting cubic automatically review new commits.

Fix all with cubic | Re-trigger cubic}

waleedlatif1 requested a review from a team as a code owner October 2, 2026 03:01

vercel Bot deployed to Preview October 2, 2026 03:03 View deployment

greptile-apps Bot reviewed Oct 2, 2026

View reviewed changes

Comment thread scripts/check-guidance-refs.ts Outdated

Comment thread scripts/check-guidance-refs.ts Outdated

Comment thread .agents/skills/add-connector/SKILL.md

cubic-dev-ai Bot reviewed Oct 2, 2026

View reviewed changes

waleedlatif1 force-pushed the improvement/agent-guidance branch from 2dd592f to c307193 Compare October 2, 2026 04:58

vercel Bot deployed to Preview October 2, 2026 05:02 View deployment

greptile-apps Bot reviewed Oct 2, 2026

View reviewed changes

Comment thread CLAUDE.md

vercel Bot deployed to Preview October 2, 2026 07:36 View deployment

greptile-apps Bot reviewed Oct 2, 2026

View reviewed changes

Comment thread scripts/check-guidance-refs.ts

Comment thread scripts/check-guidance-refs.ts

cubic-dev-ai Bot reviewed Oct 2, 2026

View reviewed changes

vercel Bot deployed to Preview October 2, 2026 07:56 View deployment

cubic-dev-ai Bot reviewed Oct 2, 2026

View reviewed changes

vercel Bot deployed to Preview October 2, 2026 08:12 View deployment

cubic-dev-ai Bot reviewed Oct 2, 2026

View reviewed changes

Comment thread scripts/check-guidance-refs.ts Outdated

Comment thread scripts/check-guidance-refs.ts

waleedlatif1 added 4 commits October 2, 2026 01:17

fix(audits): guard the route wrapper against lib/mothership, not the …

7438455

…removed lib/copilot The Copilot modules moved to lib/mothership in the v1.0.0 rename, so the route-wrapper graph guard was banning a directory that no longer exists.

waleedlatif1 added 8 commits October 2, 2026 01:17

docs(agents): map the new ratchets and lint rules in the guardrail table

469e741

docs(agents): drop the hand-kept rule-to-check table from CLAUDE.md

79639a4

Name the enforcing check on the rule's own bullet instead, and tighten the Comments bullet.

fix(audits): resolve import specifiers to module files only; tighten …

351622b

…review-flagged guidance

docs(agents): keep the repo-wide ES2023 ban in sim-components after r…

5c0d278

…ebase

waleedlatif1 force-pushed the improvement/agent-guidance branch from 2973989 to 5c0d278 Compare October 2, 2026 08:20

cubic-dev-ai Bot reviewed Oct 2, 2026

View reviewed changes

vercel Bot deployed to Preview October 2, 2026 08:23 View deployment

fix(audits): require exact export targets to exist and resolve markdo…

30e80f9

…wn links strictly

vercel Bot deployed to Preview October 2, 2026 08:37 View deployment

cubic-dev-ai Bot reviewed Oct 2, 2026

View reviewed changes

Comment thread scripts/check-guidance-refs.ts Outdated

Comment thread scripts/check-guidance-refs.ts Outdated

fix(audits): check require() specifiers and keep path resolution insi…

ffccca6

…de the repo

vercel Bot deployed to Preview October 2, 2026 08:49 View deployment

cubic-dev-ai Bot reviewed Oct 2, 2026

View reviewed changes

Comment thread scripts/check-guidance-refs.ts

waleedlatif1 merged commit 94b879d into staging Oct 2, 2026
41 checks passed

This was referenced Oct 2, 2026

v0.9.11: managed mcp optimizations, instrumentation improvements, mammoth parser bump #8569

Merged

fix(audits): close guardrail detector gaps and correct guidance from release review #8571

Merged

waleedlatif1 deleted the improvement/agent-guidance branch October 2, 2026 16:48

Conversation

waleedlatif1 commented Oct 2, 2026

Summary

Type of Change

Testing

Checklist

Uh oh!

vercel Bot commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greptile-apps Bot commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 5/5

Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

waleedlatif1 commented Oct 2, 2026

Uh oh!

Uh oh!

waleedlatif1 commented Oct 2, 2026

Uh oh!

waleedlatif1 commented Oct 2, 2026

Uh oh!

cubic-dev-ai Bot commented Oct 2, 2026

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

waleedlatif1 commented Oct 2, 2026

Uh oh!

waleedlatif1 commented Oct 2, 2026

Uh oh!

cubic-dev-ai Bot commented Oct 2, 2026

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

waleedlatif1 commented Oct 2, 2026

Uh oh!

waleedlatif1 commented Oct 2, 2026

Uh oh!

cubic-dev-ai Bot commented Oct 2, 2026

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vercel Bot commented Oct 2, 2026 •

edited

Loading

greptile-apps Bot commented Oct 2, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading