docs: apply Claude 5 context-engineering audit fixes - #44
Open
Jmeg8r wants to merge 1 commit into
Open
Conversation
Rewrite CLAUDE.md (439 -> 73 lines) to describe THIS repo instead of jdex-premium's. The prior file was largely cloned from jdex-premium/CLAUDE.md and never fully adapted: its Repository Structure, Database key-tables list, Premium vs. Free Features table, and entire "Ironclad 4-Phase Process" section (132 lines) all described directories, tables, and scripts (components/, services/, context/, licenseService.js, scripts/verify.js, scripts/ship.js, scripts/ai-review.js, .workflow/checklists/) that do not exist anywhere in this repo (verified via find/grep/wc against app/src, db.js, scripts/, and .workflow/). Also fixed along the way: - Doc pointers for code signing were pointing at docs/DISTRIBUTION-SETUP.md and docs/NOTARIZATION-SETUP.md, which don't exist; the real files are at app/DISTRIBUTION-SETUP.md and app/NOTARIZATION-SETUP.md. - "Two remotes: origin/premium" was factually wrong -- this repo only has origin; jdex-premium is a separate repo/checkout, not a remote of this one. - Dropped hardcoded file line-counts and the wrong DB table list rather than updating them, per the audit rubric's staleness guidance. - Kept the feature/* branch-naming divergence from global's feat:/fix:/docs: convention explicit (it's load-bearing, not filler). Absorbs a pre-existing uncommitted edit to this file (removal of the jdex-cursor-config/ line from the repo tree -- that directory no longer exists) that predates this session; it is fully subsumed by this rewrite. package-lock.json has unrelated pre-existing local changes, left unstaged. Audit source: claude-md-audit/findings/JDEX.md (rubric v1, 2026-07-26). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
📝 WalkthroughSummary by CodeRabbit
WalkthroughCLAUDE.md was rewritten from a comprehensive project context and workflow document into a concise JDEX-focused reference covering repository structure, conventions, hierarchy, operational gotchas, known debt, commands, and workflow limitations. ChangesJDEX documentation rewrite
Estimated code review effort: 1 (Trivial) | ~5 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CLAUDE.md`:
- Around line 27-32: Update the fenced hierarchy diagram in CLAUDE.md to declare
the text language, changing its opening fence to use text while preserving the
diagram content unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 842b1981-5a5f-44a8-9abd-79b9ba57146a
📒 Files selected for processing (1)
CLAUDE.md
📜 Review details
⏰ Context from checks skipped due to timeout. (1)
- GitHub Check: Analyze (javascript-typescript)
⚠️ CI failures not shown inline (8)
GitHub Actions: CI / 1_Code Quality.txt: docs: apply Claude 5 context-engineering audit fixes
Conclusion: failure
##[group]GITHUB_TOKEN Permissions
Contents: read
Metadata: read
PullRequests: read
##[endgroup]
Secret source: Actions
Prepare workflow directory
Prepare all required actions
Getting action download info
##[error]The actions actions/checkout@v6 and actions/setup-node@v6 are not allowed in As-The-Geek-Learns/JDEX because all actions must be pinned to a full-length commit SHA.
GitHub Actions: CI / Code Quality: docs: apply Claude 5 context-engineering audit fixes
Conclusion: failure
##[group]GITHUB_TOKEN Permissions
Contents: read
Metadata: read
PullRequests: read
##[endgroup]
Secret source: Actions
Prepare workflow directory
Prepare all required actions
Getting action download info
##[error]The actions actions/checkout@v6 and actions/setup-node@v6 are not allowed in As-The-Geek-Learns/JDEX because all actions must be pinned to a full-length commit SHA.
GitHub Actions: CI / 3_Security Scan (Semgrep).txt: docs: apply Claude 5 context-engineering audit fixes
Conclusion: failure
##[group]GITHUB_TOKEN Permissions
Contents: read
Metadata: read
PullRequests: read
##[endgroup]
Secret source: Actions
Prepare workflow directory
Prepare all required actions
Getting action download info
##[error]The action actions/checkout@v6 is not allowed in As-The-Geek-Learns/JDEX because all actions must be pinned to a full-length commit SHA.
GitHub Actions: CI / 2_Secrets Scan.txt: docs: apply Claude 5 context-engineering audit fixes
Conclusion: failure
##[group]GITHUB_TOKEN Permissions
Contents: read
Metadata: read
PullRequests: read
##[endgroup]
Secret source: Actions
Prepare workflow directory
Prepare all required actions
Getting action download info
##[error]The action actions/checkout@v6 is not allowed in As-The-Geek-Learns/JDEX because all actions must be pinned to a full-length commit SHA.
GitHub Actions: CI / Security Scan (Semgrep): docs: apply Claude 5 context-engineering audit fixes
Conclusion: failure
##[group]GITHUB_TOKEN Permissions
Contents: read
Metadata: read
PullRequests: read
##[endgroup]
Secret source: Actions
Prepare workflow directory
Prepare all required actions
Getting action download info
##[error]The action actions/checkout@v6 is not allowed in As-The-Geek-Learns/JDEX because all actions must be pinned to a full-length commit SHA.
GitHub Actions: CI / Security Scan: docs: apply Claude 5 context-engineering audit fixes
Conclusion: failure
##[group]GITHUB_TOKEN Permissions
Contents: read
Metadata: read
PullRequests: read
##[endgroup]
Secret source: Actions
Prepare workflow directory
Prepare all required actions
Getting action download info
##[error]The actions actions/checkout@v6 and actions/setup-node@v6 are not allowed in As-The-Geek-Learns/JDEX because all actions must be pinned to a full-length commit SHA.
GitHub Actions: CI / Secrets Scan: docs: apply Claude 5 context-engineering audit fixes
Conclusion: failure
##[group]GITHUB_TOKEN Permissions
Contents: read
Metadata: read
PullRequests: read
##[endgroup]
Secret source: Actions
Prepare workflow directory
Prepare all required actions
Getting action download info
##[error]The action actions/checkout@v6 is not allowed in As-The-Geek-Learns/JDEX because all actions must be pinned to a full-length commit SHA.
GitHub Actions: CI / 4_Security Scan.txt: docs: apply Claude 5 context-engineering audit fixes
Conclusion: failure
##[group]GITHUB_TOKEN Permissions
Contents: read
Metadata: read
PullRequests: read
##[endgroup]
Secret source: Actions
Prepare workflow directory
Prepare all required actions
Getting action download info
##[error]The actions actions/checkout@v6 and actions/setup-node@v6 are not allowed in As-The-Geek-Learns/JDEX because all actions must be pinned to a full-length commit SHA.
🧰 Additional context used
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
Repo: As-The-Geek-Learns/JDEX
Timestamp: 2026-07-26T21:07:04.106Z
Learning: Use `feature/*` for feature branch names in this repository; do not apply the global `feat:`/`fix:`/`docs:` commit-prefix convention as a branch naming rule.
Learnt from: CR
Repo: As-The-Geek-Learns/JDEX
Timestamp: 2026-07-26T21:07:04.106Z
Learning: Run commands from `app/`; before commits, run `npm run lint:fix && npm run format`.
Learnt from: CR
Repo: As-The-Geek-Learns/JDEX
Timestamp: 2026-07-26T21:07:04.106Z
Learning: Do not assume the premium repository’s `verify.js`, `ship.js`, AI-review scripts, or `.workflow/checklists/` and `.workflow/state/` directories exist here.
🪛 markdownlint-cli2 (0.23.0)
CLAUDE.md
[warning] 27-27: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (1)
CLAUDE.md (1)
1-9: LGTM!Also applies to: 10-24, 34-48, 49-67, 68-73
Comment on lines
27
to
32
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## Working With This Codebase | ||
|
|
||
| ### Adding a New Feature | ||
| 1. Create a feature branch: `feature/your-feature` | ||
| 2. If it needs UI: Add component(s) in `app/src/components/YourFeature/` | ||
| 3. If it needs business logic: Add service in `app/src/services/yourFeatureService.js` | ||
| 4. If it needs database changes: Add migration in `db.js` (increment `SCHEMA_VERSION`) | ||
| 5. If it's premium-gated: Check license in component via `useLicense()` from `LicenseContext` | ||
| 6. Wire into `App.jsx` (currently all top-level routing/state lives here) | ||
| 7. Run `npm run lint:fix && npm run format` before committing | ||
|
|
||
| ### Adding a Database Migration | ||
| In `db.js`, migrations are numbered. The current schema version is **7**. | ||
| ```javascript | ||
| // In the runMigrations() function: | ||
| if (currentVersion < 8) { | ||
| db.run("ALTER TABLE ... "); | ||
| db.run("UPDATE schema_version SET version = 8"); | ||
| } | ||
| ``` | ||
|
|
||
| ### Key Files to Read First | ||
| When starting a new session, these files give the most context: | ||
| 1. `app/src/App.jsx` - All UI state, navigation, feature integration | ||
| 2. `app/src/db.js` - Database schema, queries, migrations | ||
| 3. `app/src/services/licenseService.js` - Premium feature gating logic | ||
| 4. `app/tailwind.config.js` - Design system tokens | ||
|
|
||
| --- | ||
|
|
||
| ## Environment Setup | ||
|
|
||
| ### Prerequisites | ||
| - **Node.js 20+** (CI uses Node 20) | ||
| - **npm** (lockfile at `app/package-lock.json`) | ||
| - **macOS** for Electron development (primary dev platform) | ||
|
|
||
| ### First-Time Setup | ||
| ```bash | ||
| cd app | ||
| npm install | ||
| npm run electron:dev | ||
| ``` | ||
|
|
||
| ### Code Signing (Release Builds Only) | ||
| - **macOS**: Requires Apple Developer account, certificates, and notarization credentials in env vars | ||
| - **Windows**: Requires EV code signing certificate (FTL Consulting LLC) | ||
| - See `docs/DISTRIBUTION-SETUP.md` and `docs/NOTARIZATION-SETUP.md` for details | ||
|
|
||
| --- | ||
|
|
||
| ## Development Workflow: Ironclad 4-Phase Process | ||
|
|
||
| This project uses a structured workflow with mandatory quality gates and AI-powered code review. | ||
|
|
||
| ### Workflow Phases | ||
|
|
||
| #### Phase 1: PLAN | ||
| Before writing any code, create or update a plan document. | ||
|
|
||
| **Required:** | ||
| - Create `.workflow/sessions/SESSION-YYYY-MM-DD-[slug]/plan.md` using the template | ||
| - Define problem statement and success criteria | ||
| - Complete security considerations section | ||
| - Break down tasks with dependencies | ||
| - Get human approval before proceeding | ||
|
|
||
| **Gate:** Human must approve the plan before EXECUTE phase begins. | ||
|
|
||
| #### Phase 2: EXECUTE | ||
| Implement the planned tasks systematically. | ||
|
|
||
| **Required:** | ||
| - Work through tasks in dependency order | ||
| - Create feature branch for the work | ||
| - Update session documentation as you go | ||
| - Mark tasks complete in plan.md as finished | ||
| - Run linting and fix issues before proceeding | ||
|
|
||
| **Gate:** All planned tasks must be marked complete before VERIFY phase. | ||
|
|
||
| #### Phase 3: VERIFY | ||
| Validate the implementation thoroughly. | ||
|
|
||
| **Required:** | ||
| - Run `node scripts/verify.js` to: | ||
| - Generate file hashes | ||
| - Run automated tests | ||
| - Run linter | ||
| - Run security audit (npm audit) | ||
| - **Run AI code review (Gemini)** | ||
| - Complete verification checklist | ||
| - Address any AI review findings | ||
| - Perform visual verification (capture screenshots if UI) | ||
| - Get human approval of verification results | ||
|
|
||
| **AI Code Review:** | ||
| The verification includes automated AI review using Google Gemini that checks for: | ||
| - Security vulnerabilities (injection, auth issues, data exposure) | ||
| - Code quality issues (clarity, error handling, edge cases) | ||
| - Best practices violations | ||
|
|
||
| If AI review finds issues: | ||
| 1. Review the findings in `.workflow/state/ai-review.json` | ||
| 2. Address CRITICAL and HIGH severity issues before shipping | ||
| 3. Document any accepted risks in the session notes | ||
|
|
||
| **Gate:** Human must approve verification before SHIP phase. | ||
|
|
||
| #### Phase 4: SHIP | ||
| Merge the verified code. | ||
|
|
||
| **Required:** | ||
| - Run `node scripts/ship.js` to validate file integrity | ||
| - File hashes must match verification state | ||
| - Create PR with evidence | ||
| - Include AI review summary in PR | ||
| - **Get human approval for merge** | ||
|
|
||
| **Gate:** File integrity must pass before PR creation. | ||
|
|
||
| ### Human Checkpoints | ||
|
|
||
| The workflow has mandatory human checkpoints: | ||
| 1. **Plan Approval** - Before any code is written | ||
| 2. **Verification Approval** - After testing and AI review, before shipping | ||
| 3. **Ship Approval** - Final merge decision | ||
|
|
||
| Never auto-proceed past these checkpoints. Always ask for explicit approval. | ||
|
|
||
| ### Security Requirements | ||
|
|
||
| For every change: | ||
| - Review `.workflow/checklists/security-review.md` | ||
| - Validate all user inputs | ||
| - Sanitize data before storage/display | ||
| - Use parameterized queries for database operations | ||
| - Never expose sensitive data in errors or logs | ||
| - Run `npm audit` before shipping | ||
| - **Review AI security findings and address issues** | ||
|
|
||
| ### AI Review Configuration | ||
|
|
||
| The AI review requires a Gemini API key: | ||
| ```bash | ||
| export GEMINI_API_KEY="your-api-key" | ||
| ``` | ||
|
|
||
| To run AI review standalone: | ||
| ```bash | ||
| node scripts/ai-review.js # Full review | ||
| node scripts/ai-review.js --diff # Review git changes only | ||
| node scripts/ai-review.js --security-focus # Security only | ||
| Areas (10-19, 20-29, ...) # Broad life/work categories | ||
| └── Categories (11, 12, ...) # Topic groups within an area | ||
| └── Folders (11.01, 11.02, ...) # Container folders | ||
| └── Items (11.01.001, ...) # Individual tracked objects | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Specify a language for the fenced code block.
Add text to the hierarchy diagram fence to satisfy markdownlint MD040.
Proposed fix
-```
+```text
Areas (10-19, 20-29, ...) # Broad life/work categories
└── Categories (11, 12, ...) # Topic groups within an area
└── Folders (11.01, 11.02, ...) # Container folders
└── Items (11.01.001, ...) # Individual tracked objects</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 27-27: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CLAUDE.md` around lines 27 - 32, Update the fenced hierarchy diagram in
CLAUDE.md to declare the text language, changing its opening fence to use text
while preserving the diagram content unchanged.
Source: Linters/SAST tools
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rewrites
CLAUDE.md(439 -> 73 lines) per the Claude 5 context-engineeringaudit (
claude-md-audit/findings/JDEX.md, rubric v1). The file's headlineproblem: most of it described jdex-premium's repo, not this one -- it
read like a partially-adapted clone of
jdex-premium/CLAUDE.md.Per-finding evidence
components/,services/,context/dirs andlicenseService.jsfind app/srcreturns onlyApp.jsx,db.js,index.css,main.jsx,utils/-- none of the documented dirs existfile_organization_rules,statisticsgrep "CREATE TABLE" db.jsshows the real table isorganization_rules; nostatisticstable existslicenseService.js/LicenseContext/useLicense()found anywhere in the reposcripts/verify.js,scripts/ship.js,scripts/ai-review.js,.workflow/checklists/,GEMINI_API_KEYfind/grepconfirm none of these exist;scripts/andapp/scripts/only hold build/notarize/sign scripts;.workflow/only hassessions/; CI has zero references to these scripts or GeminiApp.jsx2,622 /db.js3,344)wc -lshows 2,359 / 3,296 -- already driftedVersion: 2.1.0app/package.jsonsays2.0.1package.json,tailwind.config.js,.github/workflows/ci.ymldocs/DISTRIBUTION-SETUP.md,docs/NOTARIZATION-SETUP.md)app/DISTRIBUTION-SETUP.md/app/NOTARIZATION-SETUP.md(found via repo-wide search)git remote -vshows onlyorigin-- nopremiumremote configuredjdex-premiumis a separate repo/checkout, not a remote of this onefeature/*branch-naming divergence from global'sfeat:/fix:/docs:convention, sql.js-from-CDN + localStorage-limit gotchas[ASTGL CONTENT]flagging line~/.claude/CLAUDE.mdverbatimAbsorbed pre-existing edit
This branch also absorbs a pre-existing uncommitted edit to
CLAUDE.md(removal of the
jdex-cursor-config/line from the repository-structuretree -- that directory no longer exists in the repo). That whole tree is
deleted in this rewrite anyway, so the edit is fully subsumed, not
separately preserved.
package-lock.jsonhas unrelated pre-existing localchanges and is intentionally left out of this PR.
Test plan
find/grep/wc -lonapp/src,db.js,scripts/,app/scripts/,.workflow/,.github/workflows/ci.yml,app/package.jsonAGENTS.mdtwin, no.coderabbit.yamlin this repo)🤖 Generated with Claude Code