Skip to content

docs(jules): curate agent journals, canonicalize .jules casing, remove scratch debris#626

Open
seonghobae wants to merge 9 commits into
mainfrom
seonghobae-fix-pr-checks-and-merge
Open

docs(jules): curate agent journals, canonicalize .jules casing, remove scratch debris#626
seonghobae wants to merge 9 commits into
mainfrom
seonghobae-fix-pr-checks-and-merge

Conversation

@seonghobae

@seonghobae seonghobae commented Jul 23, 2026

Copy link
Copy Markdown
Collaborator

Why

The .Jules agent journals had accumulated systemic quality defects: the repo tracked BOTH .Jules/ and .jules/ as case-duplicate directories with divergent content (colliding on case-insensitive filesystems and causing phantom git add failures), a third fragment lived at backend/.jules/sentinel.md, most entry dates were fabricated (2024/2025 dates predate the repository, whose history starts 2026-02), several entries were duplicated or contradictory, and 13 fix_plan*.txt agent-scratch files were tracked at the repo root.

What

  • Canonicalize casing: remove the capitalized .Jules/ directory; .jules/ (lowercase) is now the single canonical journal path, documented in AGENTS.md along with the journal entry format and an evidence-based dating rule.
  • Curate journals with evidence-based dates: rewrite bolt.md (14 entries), palette.md (13), and sentinel.md (3) as deduplicated, newest-first journals. Every date is derived from first-appearance evidence in git history (git log -S). Overlapping entries merged (export lookup maps, map.set patterns, abbreviation badges, disabled-control semantics, STRIX scope guidance), Korean entries translated to English, and the hot-path-vs-batch Map guidance contradiction resolved with explicit cross-references between the two entries.
  • De-weaponize security guidance: the palette entry that advised avoiding vulnerable files "to dodge STRIX CI" now instructs fixing or reporting findings instead of evading scanners.
  • Absorb fragments: fold backend/.jules/sentinel.md (HKDF entry) into the root sentinel journal; restore the share-redaction sentinel entry whose heading on main was a literal unexpanded $(date +%Y-%m-%d).
  • Repo hygiene: delete fix_plan3-15.txt scratch files; add .codegraph/ to .gitignore.
  • Backend validation hardening (runtime behavior change): review surfaced that the sentinel journal promised C0/C1 control-character blocking while backend/app/schemas.py only rejected C0+DEL. The project_name, member_subject, and conn_name patterns now reject the full C0/C1 ranges (^[^\x00-\x1F\x7F-\x9F]+$), with C1 rejection cases added to backend/tests/test_schema_validation.py. Names containing C1 bytes (U+0080-U+009F) are now rejected with 422; legitimate names are unaffected.

Review notes

  • Earlier commits in this PR address the five Copilot review threads on the original journal content (control-char regex C0+C1 + Pydantic v2 APIs, aria-disabled pattern, benchmark normalization); the curation commits supersede the raw journals with the corrected content.
  • Full backend suite (379 tests) and mypy pass locally on the final head.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings July 23, 2026 02:19

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Documentation-only update to the repository’s .Jules guidance notes, consolidating recent performance, accessibility, and security learnings for future reviewers/agents.

Changes:

  • Replaced .Jules/sentinel.md entry with guidance on hardening Pydantic string validation against control characters.
  • Updated .Jules/palette.md accessibility notes (disabled button guidance, table-row input labeling, abbreviation announcements).
  • Expanded .Jules/bolt.md with a larger set of performance lessons and action patterns.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File Description
.Jules/sentinel.md Updates security guidance for validating user-provided strings (control characters).
.Jules/palette.md Refreshes accessibility guidance for UI patterns and screen reader behavior.
.Jules/bolt.md Adds/refreshes performance optimization learnings and recommended patterns.
Comments suppressed due to low confidence (1)

.Jules/bolt.md:13

  • The guidance here duplicates the later entry “2024-07-01 - Avoid O(N^2) Complexity in Graph Exporters” (both advise precomputing lookup Maps/Sets to avoid nested .find()/.some() loops). Keeping both makes the notes harder to scan and increases the chance future edits diverge. Consider consolidating into a single entry (or cross-referencing one from the other).
## 2026-06-20 - O(N^2) loops for finding items in export
**Learning:** Nested array `.find()` iterations within loops parsing graph connections result in O(N^2) complexity, significantly degrading UI performance for large outputs.
**Action:** Always pre-compute a lookup `Map` in O(N) when multiple specific node lookups are needed within iterative processes.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread .Jules/sentinel.md Outdated
Comment thread .Jules/palette.md Outdated
Comment thread .Jules/bolt.md Outdated
Comment thread .Jules/bolt.md Outdated
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings July 23, 2026 02:24

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

Comment thread .Jules/bolt.md Outdated
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings July 23, 2026 02:27

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

@seonghobae
seonghobae enabled auto-merge (squash) July 24, 2026 07:26
seonghobae and others added 4 commits July 24, 2026 17:05
Rewrite .jules/{bolt,palette,sentinel}.md as deduplicated, newest-first
journals. All entry dates are now derived from first-appearance evidence
in git history (git log -S); the previous 2024/2025 dates predated the
repository and were fabricated. Merge overlapping entries (export lookup
maps, map.set patterns, abbreviation badges, disabled-control semantics,
STRIX scope guidance), translate the remaining Korean entries to English,
resolve the hot-path-vs-batch Map guidance contradiction with explicit
cross-references, absorb the backend HKDF sentinel fragment, and restore
the share-redaction sentinel entry whose heading on main was a literal
unexpanded date command. AGENTS.md now documents the journal format and
the evidence-based dating rule.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Its single HKDF entry now lives in the root .jules/sentinel.md journal;
agents must not grow per-package journal copies.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Delete fix_plan3-15.txt planning debris from the repo root and add the
CodeGraph index directory to .gitignore; both are agent working artifacts
that never belonged in version control.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Delete the capitalized .Jules/ index entries that collided with the
canonical lowercase .jules/ on case-insensitive filesystems (Windows,
default macOS), causing phantom git add failures and divergent journal
content. AGENTS.md now documents .jules/ as the only allowed path.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings July 24, 2026 08:06
@seonghobae seonghobae changed the title chore: update .Jules guidance notes docs(jules): curate agent journals, canonicalize .jules casing, remove scratch debris Jul 24, 2026

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 21 out of 22 changed files in this pull request and generated 2 comments.

Comment thread AGENTS.md
Comment thread .jules/sentinel.md
Extend the project_name, member_subject, and conn_name validation
patterns from C0+DEL to the full C0/C1 control ranges so the implemented
validation matches the sentinel journal guidance on log/terminal escape
injection, with C1 rejection tests. Also fix the backend/.jules casing
example in AGENTS.md flagged in review.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings July 24, 2026 08:17
@opencode-agent
opencode-agent Bot disabled auto-merge July 24, 2026 08:17

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 23 out of 24 changed files in this pull request and generated 1 comment.

Comment thread backend/app/schemas.py
@seonghobae
seonghobae enabled auto-merge July 24, 2026 08:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants