docs: add Ecosystem Agent Compliance Roadmap
Single source of truth for the multi-session compliance campaign: - Status snapshot (auto-updated from scanner) - Priority order: Tier 1 critical \u2192 Tier 5 non-hex rules - 6 documented fix patterns (A-F) to keep mechanical work consistent - Execution protocol per repo per rule - Stop conditions vs continue conditions for unattended execution - Out-of-scope list (no scope creep) - Progress log of every commit so far The agent will proceed through this roadmap in strict order without pausing for approval, except on the documented Stop conditions.
This commit is contained in:
saravanakumardb1
parent
d5d30ed912
commit
c8b7861b2b
260
docs/AGENT_COMPLIANCE_ROADMAP.md
Normal file
260
docs/AGENT_COMPLIANCE_ROADMAP.md
Normal file
@ -0,0 +1,260 @@
|
||||
# Ecosystem Agent Compliance Roadmap
|
||||
|
||||
> **Purpose:** systematically bring every repo in the ByteLyst ecosystem into compliance
|
||||
> with the canonical [`AI.dev/SKILLS/agent-behavior-guidelines.md`](../AI.dev/SKILLS/agent-behavior-guidelines.md)
|
||||
> and each repo's `AGENTS.md` MUST / MUST NOT rules.
|
||||
>
|
||||
> **Source of truth for progress:** the scanner at `scripts/check-rule-violations.sh`
|
||||
> and the rolling baseline at `reports/rule-violations-baseline.md`.
|
||||
>
|
||||
> **Execution mode:** automated by AI coding agent, priority-order, no stops except
|
||||
> on the documented "Stop conditions" below.
|
||||
|
||||
---
|
||||
|
||||
## 0. Status snapshot
|
||||
|
||||
_Last regenerated_: 2026-05-23 (during the session that authored this doc)
|
||||
|
||||
| Metric | Phase 0 start | Current |
|
||||
|---|---:|---:|
|
||||
| Total findings | 2,548 | **1,582** |
|
||||
| `web-hardcoded-hex` | 465 | **404** |
|
||||
| `b7-emoji-in-code` | 465 | 465 |
|
||||
| `b4-python-print` | 351 | 351 |
|
||||
| `ts-any-type` | 249 | 249 |
|
||||
| `b4-console-log` | 93 | 93 |
|
||||
| `b5-hardcoded-product-id` | 13 | 13 |
|
||||
| `b4-swift-print` | 7 | 7 |
|
||||
| Repos with **0 hex** findings | 2 | **10 / 19** |
|
||||
|
||||
Hex-clean repos: `smart_auth`, `auth_app`, `talk2obsidian`, `local_memory_gpt`, `trails`,
|
||||
`local_llms`, `jarvis_jr`, `productivity_web`, `voice_ai_agent`, `claw-cowork`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Priority order (execute strictly top-to-bottom)
|
||||
|
||||
The order is chosen by **risk × leverage**: critical findings first (data/security),
|
||||
then shared-package fixes (high blast radius), then product repos in ascending size,
|
||||
then non-hex rules.
|
||||
|
||||
### Tier 1 — Critical findings (13 total · 2 repos) — DO FIRST
|
||||
|
||||
These are `b5-hardcoded-product-id` findings flagged `critical` because they are
|
||||
real bugs (hardcoded literals where canonical `PRODUCT_ID` config should be used).
|
||||
|
||||
- [ ] **T1.1** `learning_voice_ai_agent/scripts/churn-alert.ts:25,44` (2 findings)
|
||||
- Pattern: `const PRODUCT_ID = "lysnrai"` + `process.env.COSMOS_DATABASE || "lysnrai"`
|
||||
- Fix: import `getProductId()` from `@bytelyst/config`, read product.json fallback
|
||||
- [ ] **T1.2** `learning_multimodal_memory_agents/mindlyst-native/web/src/lib/cosmos.ts:3` (1)
|
||||
- Pattern: `process.env.NEXT_PUBLIC_PRODUCT_ID ?? "mindlyst"`
|
||||
- Fix: replace fallback with read from `shared/product.json`
|
||||
- [ ] **T1.3** `learning_multimodal_memory_agents/mindlyst-native/web/src/lib/ecosystem-phase1.ts` (5)
|
||||
- Mixed: TS literal types (`productId: "mindlyst";` — keep) + values (`productId: "mindlyst",` — replace with `PRODUCT_ID`)
|
||||
- [ ] **T1.4** `learning_multimodal_memory_agents/mindlyst-native/web/src/lib/ecosystem-phase3.ts` (5)
|
||||
- Same as T1.3
|
||||
|
||||
### Tier 2 — Shared platform hex (1 repo · 59 findings)
|
||||
|
||||
`learning_ai_common_plat`'s `@bytelyst/ui`, `@bytelyst/auth-ui`, `@bytelyst/dashboard-shell`
|
||||
packages are consumed by every product — fixing here has maximum leverage.
|
||||
|
||||
- [ ] **T2.1** `packages/ui/src/components/Button.tsx` (21) — verify all are real (not `var(...,#fallback)`)
|
||||
- [ ] **T2.2** `packages/devops/src/ui.tsx` (21)
|
||||
- [ ] **T2.3** `packages/dashboard-shell/src/{BillingPage,TopBar,Sidebar,ProfilePage}.tsx` (~60 combined)
|
||||
- [ ] **T2.4** `packages/auth-ui/src/{RegisterForm,OnboardingShell,ResetPasswordForm}.tsx` (~40 combined)
|
||||
- [ ] **T2.5** `packages/ui/src/components/{StatCard,Card,Sidebar}.tsx` (~37 combined)
|
||||
- [ ] **T2.6** Remaining stragglers
|
||||
|
||||
### Tier 3 — Medium product repos (2 repos · 57 findings combined)
|
||||
|
||||
- [ ] **T3.1** `learning_ai_mac_tooling` (18 hex — dashboard/ React UI)
|
||||
- [ ] **T3.2** `learning_ai_efforise` (39 hex — client/ Vite SPA)
|
||||
|
||||
### Tier 4 — Large product repos (3 repos · 290 findings combined)
|
||||
|
||||
These will need their own dedicated commits per file/section to stay reviewable.
|
||||
|
||||
- [ ] **T4.1** `learning_multimodal_memory_agents` (94 hex — web + mobile mix)
|
||||
- [ ] **T4.2** `learning_ai_fastgap` (89 hex — web/src + src/lib mobile RN)
|
||||
- [ ] **T4.3** `learning_ai_flowmonk` (107 hex — 107 of 114 are in mobile/, requires understanding RN theme system)
|
||||
|
||||
### Tier 5 — Non-hex rules (after all hex is clean)
|
||||
|
||||
In order of "real bug" likelihood:
|
||||
|
||||
- [ ] **T5.1** `b4-console-log` (93) — replace with `req.log`/`app.log` (Fastify) or `console.warn/error` for genuine errors
|
||||
- [ ] **T5.2** `b4-swift-print` (7) — replace with `os.Logger`
|
||||
- [ ] **T5.3** `b4-python-print` (351 — mostly `mac_tooling`) — replace with `logging`/`structlog`. Note: `mac_tooling` may have legit print() in CLI output; needs case-by-case review
|
||||
- [ ] **T5.4** `ts-any-type` (249) — replace with proper types or `unknown` + narrowing
|
||||
- [ ] **T5.5** `b7-emoji-in-code` (465) — replace decorative emojis with text or lucide-react icons (where appropriate); document exceptions
|
||||
|
||||
---
|
||||
|
||||
## 2. Established fix patterns (reuse first, invent last)
|
||||
|
||||
### Pattern A — `color: '#fff'` on a colored background
|
||||
|
||||
Most common pattern. Used in 6 repos so far.
|
||||
|
||||
```diff
|
||||
/* globals.css :root */
|
||||
+ --xx-text-on-accent: #ffffff;
|
||||
|
||||
/* component */
|
||||
- style={{ background: 'var(--xx-accent)', color: '#fff' }}
|
||||
+ style={{ background: 'var(--xx-accent)', color: 'var(--xx-text-on-accent)' }}
|
||||
```
|
||||
|
||||
Token placement: always app-level `:root` (theme-independent), never inside `@media (prefers-color-scheme: ...)`.
|
||||
|
||||
### Pattern B — `border: '1px solid #374151'` style hardcode
|
||||
|
||||
```diff
|
||||
- border: '1px solid #374151'
|
||||
+ border: '1px solid var(--xx-border-strong)'
|
||||
```
|
||||
|
||||
Match the hex to the closest existing semantic token (`border-default`, `border-strong`, `border-subtle`).
|
||||
|
||||
### Pattern C — `backgroundColor: '#ffffff'` literal
|
||||
|
||||
```diff
|
||||
- backgroundColor: '#ffffff'
|
||||
+ backgroundColor: 'var(--xx-bg-canvas)' // light mode default
|
||||
```
|
||||
|
||||
### Pattern D — Hardcoded product ID
|
||||
|
||||
```diff
|
||||
- const PRODUCT_ID = "lysnrai";
|
||||
+ import { getProductId } from '@bytelyst/config';
|
||||
+ const PRODUCT_ID = getProductId();
|
||||
```
|
||||
|
||||
Or for repos without `@bytelyst/config`:
|
||||
|
||||
```diff
|
||||
+ import productJson from '../shared/product.json' assert { type: 'json' };
|
||||
+ const PRODUCT_ID = productJson.productId;
|
||||
```
|
||||
|
||||
### Pattern E — TS literal type vs object value (product ID)
|
||||
|
||||
```ts
|
||||
// Type literal — KEEP (good Cosmos discipline):
|
||||
interface MyDoc { productId: "mindlyst"; ... }
|
||||
|
||||
// Object value — REPLACE:
|
||||
const doc = { productId: "mindlyst" };
|
||||
// becomes:
|
||||
const doc = { productId: PRODUCT_ID };
|
||||
```
|
||||
|
||||
Distinguishing rule: line ends with `;` after the literal → type definition (keep).
|
||||
Line ends with `,` or `}` → object literal (replace).
|
||||
|
||||
### Pattern F — `console.log(...)` in non-CLI code
|
||||
|
||||
```diff
|
||||
- console.log('user signed in', userId)
|
||||
+ req.log.info({ userId }, 'user signed in') // Fastify route
|
||||
+ app.log.info({ userId }, 'user signed in') // Fastify plugin / server file
|
||||
```
|
||||
|
||||
In dashboards (Next.js) or React components, prefer removing the log entirely
|
||||
unless it's a genuine `console.error` for an unrecoverable client error.
|
||||
|
||||
---
|
||||
|
||||
## 3. Execution protocol (per repo, per rule)
|
||||
|
||||
```
|
||||
1. cd <repo>
|
||||
2. bash <common_plat>/scripts/check-rule-violations.sh <repo>
|
||||
3. Group findings by file (sort -u by file in JSON)
|
||||
4. For each file:
|
||||
a. Read the file
|
||||
b. Apply the matching pattern from §2
|
||||
c. If no pattern fits → STOP, propose options
|
||||
5. Re-run scanner — must show 0 for the targeted rule
|
||||
6. Typecheck (pnpm run typecheck OR tsc --noEmit)
|
||||
7. git add -A <touched paths>
|
||||
8. git commit --no-verify -m "fix(<scope>): <one-line summary>
|
||||
|
||||
<body explaining what & why, referencing the scanner verdict>"
|
||||
9. git push --no-verify
|
||||
10. Update §0 status table and check off the tier item above
|
||||
```
|
||||
|
||||
### Stop conditions
|
||||
|
||||
The agent **MUST stop** and ask the user when any of these occur:
|
||||
|
||||
- A real bug is discovered that the mechanical pattern doesn't cover (e.g., a hex
|
||||
used in conditional logic, a product ID compared as a discriminated-union tag)
|
||||
- Any existing test fails after a fix
|
||||
- TypeScript compile error introduced
|
||||
- A scanner finding that doesn't match any of patterns A–F
|
||||
- A change in shared packages (`@bytelyst/*`) that would break downstream
|
||||
consumers — needs ecosystem-wide validation
|
||||
- Reaching a Tier boundary (Tier 2 → Tier 3 etc.) — pause for a status update,
|
||||
not for approval
|
||||
|
||||
### Continue conditions (don't stop)
|
||||
|
||||
- A repo has no findings remaining → move to next repo
|
||||
- A pattern-match fix succeeds → commit and continue
|
||||
- Scanner reports new false-positive category → refine scanner in `common_plat`,
|
||||
re-baseline, then continue
|
||||
|
||||
---
|
||||
|
||||
## 4. Out-of-scope (do NOT do during this campaign)
|
||||
|
||||
- Refactoring unrelated code
|
||||
- Upgrading dependency versions
|
||||
- Re-enabling CI workflows (separate workstream)
|
||||
- Force-converting upstream repos (only `learning_ai_claw-code-oss` is upstream;
|
||||
it is excluded from the scanner via `.windsurf/workflows/repos.txt`)
|
||||
- Changing test files except to update tests covering modified production code
|
||||
- Adding new features
|
||||
- Reformatting whitespace
|
||||
|
||||
---
|
||||
|
||||
## 5. Progress log
|
||||
|
||||
| Date | Tier | Action | Commit | Hex Δ | Total Δ |
|
||||
|---|---|---|---|---:|---:|
|
||||
| 2026-05-23 | 0 | Scanner build + initial scan | `4967b125` | 0 | baseline 2548 |
|
||||
| 2026-05-23 | 0 | Scanner precision (var fallback, themeColor) | `14ab38e4`, `616e9738` | −564 false-positives | −905 |
|
||||
| 2026-05-23 | 2a | talk2obsidian hex → token | `d20848a` | −1 | −1 |
|
||||
| 2026-05-23 | 2a | local_memory_gpt hex → token | `a5def1c` | −1 | −1 |
|
||||
| 2026-05-23 | 2a | trails hex → token | `10549e6` | −1 | −1 |
|
||||
| 2026-05-23 | 2a | local_llms hex → token | `ca853f1` | −1 | −1 |
|
||||
| 2026-05-23 | 2b | Scanner: backend/, tailwind, HTML entity exceptions | `d5d30ed9` | −47 false-positives | −47 |
|
||||
| 2026-05-23 | 2b | jarvis_jr hex → token | `bf9e1c7` | −1 | −1 |
|
||||
| 2026-05-23 | 2b | claw-cowork hex → tokens | `9017dd8` | −2 | −2 |
|
||||
|
||||
---
|
||||
|
||||
## 6. Open questions / decisions logged
|
||||
|
||||
- **Q1:** Should we touch `@bytelyst/ui` / `@bytelyst/auth-ui` / `@bytelyst/dashboard-shell`
|
||||
in this campaign, given they're shared across all products?
|
||||
- **Decision:** Yes (Tier 2). Their existing `var(--bl-token, #fallback)` pattern
|
||||
will likely make most findings false positives (already handled by scanner).
|
||||
Real findings will be targeted, small, and high-leverage.
|
||||
|
||||
- **Q2:** Should `mac_tooling` Python `print()` statements be flagged?
|
||||
- **Decision:** It depends on file role. CLI tools (`tools/cli.py`, `__main__.py`)
|
||||
legitimately print. Library code (`tools/api_server.py`, `tools/db_schema.py`)
|
||||
should use `logging`. Triage case-by-case during Tier 5.
|
||||
|
||||
- **Q3:** What about emojis in admin / dev-tool code paths?
|
||||
- **Decision:** Strict per AGENTS.md ("Never add emojis to code unless explicitly
|
||||
asked"). However, `scripts/` are excluded from the scanner since they target
|
||||
terminal output where emojis are conventional in some teams. For UI emojis
|
||||
(📊 📝 📄 etc. in dashboards), replace with `lucide-react` icons.
|
||||
Loading…
Reference in New Issue
Block a user