Skip to content

docs: update workspace prompt files to reflect current state - #113

Merged
SHA888 merged 5 commits into
mainfrom
docs/workspace-prompt-files
Jul 31, 2026
Merged

docs: update workspace prompt files to reflect current state#113
SHA888 merged 5 commits into
mainfrom
docs/workspace-prompt-files

Conversation

@SHA888

@SHA888 SHA888 commented Jul 30, 2026

Copy link
Copy Markdown
Owner

What

Updates the workspace prompt files (AGENT.md, EVOLUTION.md, SAFETY.md) to
reflect the current state of the project and marks the "Adopt workspace prompt file
conventions" TODO item as done.

Changes

  • EVOLUTION.md: Marked architecture doc (done 2026-07-21), sequence diagram
    (done 2026-07-23), config validation test, and checkpoint save/restore test as
    complete. Updated the maturity caveat to reflect that the co-evolution loop is now
    closed (items 1–6 merged).
  • TODO.md: Flipped the "Adopt workspace prompt file conventions" checkbox from
    - [ ] to - [x]. Updated P3 tracking count (15→16) and total (61→62).

Why

The workspace prompt files were created in a prior run but EVOLUTION.md still listed
completed items as open and had a stale maturity caveat from before the co-evolution
loop was closed. Keeping these files accurate makes the workspace self-documenting
and avoids misleading contributors about project state.

Verification

  • ruff format --check . — ✅ 400 files already formatted
  • ruff check evoseal/ tests/ — ✅ All checks passed
  • No Python files changed, so no pytest needed.

Addresses: TODO.md "Adopt workspace prompt file conventions" (P3)

Summary by CodeRabbit

  • Security

    • Improved model and tokenizer loading by disabling remote code execution by default.
    • Models that require remote code are now rejected safely without completing initialization.
  • Bug Fixes

    • Improved handling when the Transformers library is unavailable or model loading fails.
  • Documentation

    • Updated project maturity guidance, completion dates, remaining gaps, and task progress tracking.
    • Confirmed architecture documentation goals and workspace prompt conventions are complete.

- EVOLUTION.md: mark architecture doc and sequence diagram items done,
  update maturity caveat to reflect closed co-evolution loop, mark config
  validation and checkpoint save/restore tests done
- TODO.md: mark 'Adopt workspace prompt file conventions' done, update
  P3 (15→16) and total (61→62) tracking counts
@coderabbitai

coderabbitai Bot commented Jul 30, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c08c1522-0a0e-44cf-a9bd-f117258da05f

📥 Commits

Reviewing files that changed from the base of the PR and between 7be2ece and 8f7a26b.

📒 Files selected for processing (3)
  • TODO.md
  • evoseal/fine_tuning/model_fine_tuner.py
  • tests/unit/fine_tuning/test_model_fine_tuner.py
🚧 Files skipped from review as they are similar to previous changes (1)
  • TODO.md

📝 Walkthrough

Walkthrough

Model and tokenizer loading now disable remote code execution. Tests cover successful initialization, unavailable Transformers support, and models that require remote code. Documentation updates record the security fix, Phase 3 status, completion dates, and tracking counts.

Changes

Secure model loading

Layer / File(s) Summary
Disable remote code execution and validate initialization
evoseal/fine_tuning/model_fine_tuner.py, tests/unit/fine_tuning/test_model_fine_tuner.py
Tokenizer and model loading pass trust_remote_code=False. Tests cover successful initialization, unavailable Transformers support, and remote-code loading failures.

Project tracking

Layer / File(s) Summary
Update Phase 3 and completion tracking
EVOLUTION.md, TODO.md
Documentation records the Phase 3 references, revised completion dates, completed workspace conventions, completed remote-code security work, and updated P2, P3, and total completion counts.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant initialize_model
  participant AutoTokenizer
  participant AutoModel
  participant ErrorLogger
  initialize_model->>AutoTokenizer: from_pretrained(trust_remote_code=False)
  AutoTokenizer-->>initialize_model: tokenizer or loading error
  initialize_model->>AutoModel: from_pretrained(trust_remote_code=False)
  AutoModel-->>initialize_model: model
  initialize_model->>ErrorLogger: log remote-code loading error
Loading

Possibly related PRs

  • SHA888/EVOSEAL#51: Introduces workspace documentation tracked by this PR and relates to the remote-code security fix.
  • SHA888/EVOSEAL#114: Continues changes to model_fine_tuner.py and its regression tests for trust_remote_code=False.
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately describes the documentation updates, but it emphasizes workspace prompt files rather than the broader project-state updates.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/workspace-prompt-files

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot 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.

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 `@TODO.md`:
- Around line 310-311: Reconcile the P3 tracking row with the Ollama
retry/backoff item still marked incomplete: verify the underlying item and mark
it complete if the fix is present, or remove “Ollama provider retry/backoff fix”
from the completion note if it remains open.
🪄 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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c52ddccd-6290-4510-af4a-1b29b5fa06e1

📥 Commits

Reviewing files that changed from the base of the PR and between b60803f and ed9773a.

📒 Files selected for processing (2)
  • EVOLUTION.md
  • TODO.md

Comment thread TODO.md Outdated
Comment on lines +310 to +311
| 🟢 P3 | 24 | 16 | Makefile, pre-commit, Docker, ADRs, ADR refresh, CHANGELOG complete; +11 hygiene items from 2026-07-22 review; Ollama provider retry/backoff fix; local_models TTL cache; workspace prompt file conventions |
| **Total** | **89** | **62** | |

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Reconcile the P3 completion note with the still-open retry/backoff item.

Line [262] still marks the Ollama retry/backoff issue as incomplete, while this row claims the fix is complete. Either verify and mark the underlying item done, or remove the completion claim from the tracking row.

🤖 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 `@TODO.md` around lines 310 - 311, Reconcile the P3 tracking row with the
Ollama retry/backoff item still marked incomplete: verify the underlying item
and mark it complete if the fix is present, or remove “Ollama provider
retry/backoff fix” from the completion note if it remains open.

SHA888 added 2 commits July 30, 2026 22:49
Address review feedback on PR #113:
- Update caveat date from 2026-07-24 to 2026-07-30 to match PR merge date
- Add references to PRs #73, #89 and TODO.md section so the co-evolution
  loop-closure claim is auditable from the doc itself
… counts

- EVOLUTION.md: fix config-validation test date from 2026-07-24 to 2026-07-30
  (actual commit 85e92c2 was 2026-07-30, not 2026-07-24)
- TODO.md: fix P1 done count from 14 to 13 (13 actual checked boxes)
- TODO.md: fix P2 done count from 21 to 24 (24 actual checked boxes)
- TODO.md: update total from 62 to 64 to match corrected per-priority counts
@SHA888

SHA888 commented Jul 30, 2026

Copy link
Copy Markdown
Owner Author

Review feedback verification

I verified both review points against the actual repo state before applying any changes.

Point 1: TODO.md summary table counts

Not a bug — the PR corrects pre-existing table errors.

I counted the actual - [x] checkboxes in each priority section on both origin/main and the PR branch:

Priority Actual checked (main) Old table (main) Actual checked (PR) New table (PR)
P1 13 14 ❌ (overcounted) 13 13 ✓
P2 24 21 ❌ (undercounted) 24 24 ✓
P3 15 15 ✓ 16 16 ✓
  • No P1 item was unchecked. The old table on main overcounted P1 done by 1 and undercounted P2 done by 3. This PR corrects the numbers to match the actual checkbox states.
  • The only actual checkbox change in the diff is the P3 "workspace prompt file conventions" item ([ ][x]), which accounts for P3 going 15→16.
  • The 4 EVOLUTION.md checkbox changes (2 under Architecture documentation, 2 under Testing coverage) are syncing EVOLUTION.md with TODO.md's already-checked state — they don't represent new work and aren't counted in the TODO.md table.

Point 2: Maturity caveat claims

All claims verified as factually accurate.

  • PR feat: wire generation to consult fine-tuning registry #73: exists, merged 2026-07-24, title "feat: wire generation to consult fine-tuning registry" ✓
  • PR test: add end-to-end bidirectional loop integration test #89: exists, merged 2026-07-25, title "test: add end-to-end bidirectional loop integration test" ✓
  • Daemon runs real EvolutionPipeline: imported and invoked in continuous_evolution_service.py (line 20, 44, 230) ✓
  • ollama create deployment: implemented in version_manager.py:363,421
  • Generator consults fine-tuning registry: registry_model parameter wired through coevolution_manager.py:80-86
  • Model validation serves fine-tuned model: _resolve_model_for_validation() with model_path in model_validator.py:89,202

The reviewer is correct that these claims can't be verified from the diff alone, but they are factually true against the current codebase. The caveat accurately reflects the state of the co-evolution loop.

@SHA888

SHA888 commented Jul 31, 2026

Copy link
Copy Markdown
Owner Author

Verification of review feedback

I verified each point against the actual origin/main state (the base branch) before the PR. Here is what I found:

Point 1: P1 "Done" count drops 14→13

The reviewer is wrong. On origin/main, the P1 tracking table says Done=14, but there are actually only 13 checked [x] items in the P1 section. I counted them:

git show origin/main:TODO.md | sed -n "/## 🟠 P1/,/## 🟡 P2/p" | grep -c "\- \[x\]"
# → 13

The table was overcounting by 1 before this PR. No P1 checkbox was changed because none needed to be — the PR corrects the table from the wrong value (14) to the actual count (13). This is a pre-existing arithmetic error being fixed, not a silent revert.

Point 2: EVOLUTION.md flips 4 checkboxes but TODO.md not synced

The reviewer is wrong. All 4 items are already [x] in TODO.md on origin/main (they were marked done in prior commits):

Item TODO.md state on main
Write architecture doc for Devstral co-evolution [x] (P2 section, line ~227)
Add sequence diagram for Devstral ↔ EVOSEAL message flow [x] (P2 section, line ~228)
Add regression test for config validation [x] (P2 section, line ~236)
Add test for checkpoint save/restore [x] (P2 section, line ~237)

The PR brings EVOLUTION.md into sync with TODO.md, not out of sync. The reviewer was working from the diff alone and could not see the full TODO.md body.

Point 3: P2 Done 21→24 (+3) vs 4 newly-completed items

The reviewer is wrong. On origin/main, the P2 tracking table says Done=21, but there are actually 24 checked items in the P2 section:

git show origin/main:TODO.md | sed -n "/## 🟡 P2/,/## 🟢 P3/p" | grep -c "\- \[x\]"
# → 24

The +3 delta is correcting the table from 21 (wrong) to 24 (actual count). The 4 EVOLUTION.md items being marked were already checked in TODO.md — they are not "newly completed" and do not affect the count. The notes field is unchanged between old and new; only the number is corrected.

Point 4: PRs #73, #89 and items 1–6

Verified and accurate:

The maturity caveat update correctly reflects the current state of merged work.

Summary

All four concerns stem from the reviewer not having access to the full TODO.md body and not realizing the tracking table was already inaccurate. The PR is fixing pre-existing table arithmetic errors, not introducing new ones. No changes are needed to address these points — the diff is correct as-is.

SHA888 added 2 commits July 31, 2026 13:21
* fix: default trust_remote_code to False in model_fine_tuner

Changed both AutoTokenizer.from_pretrained and
AutoModelForCausalLM.from_pretrained calls from trust_remote_code=True
to trust_remote_code=False. The known HF base models (DeepSeek, Qwen,
CodeLlama, Mistral) are standard architectures that do not require
remote code execution.

Removed the # nosec B615 suppression comments since the security flag
is now safe by default.

The _resolve_hf_base_model() fallback still uses model_name verbatim
for unknown families, but without trust_remote_code=True it can no
longer execute arbitrary code from an untrusted repo.

Added 3 regression tests: source inspection for the safe default, and
behavior check when TRANSFORMERS_AVAILABLE is False.

Closes TODO.md item: model_fine_tuner.py:160-178

* fix: restore nosec B615 for revision pinning

B615 flags missing revision= parameter in from_pretrained(), not
trust_remote_code. The PR removed these suppressions along with the
trust_remote_code=True fix, but revision pinning is intentionally left
to the caller. Restore # nosec B615 on both loading calls and update
the regression test accordingly.

* fix: address review feedback on trust_remote_code PR

- Fix TODO.md changelog: nosec B615 comments were relocated, not removed;
  B615 flags missing revision=, not trust_remote_code
- Move tokenizer nosec B615 back to opening from_pretrained( line so bandit
  matches it to the correct line number
- Replace fragile inspect.getsource test with mock-based test that asserts
  trust_remote_code=False on both from_pretrained call kwargs
- Fix test_initialize_returns_false_without_transformers to actually patch
  TRANSFORMERS_AVAILABLE=False via monkeypatch
- Update PR body to correct inaccurate claim about removing nosec comments

* test: add failure-path test for trust_remote_code=False incompatibility

Addresses review feedback on PR #114: the existing tests only asserted the
kwarg value on mocked from_pretrained calls but never exercised the failure
path where a model that needs custom code raises on load.

The new test mocks from_pretrained to raise OSError (what transformers
actually raises when the auto-map can't resolve the architecture without
custom code) and verifies that:
- initialize_model() returns False
- is_initialized stays False
- Model load is not attempted (tokenizer fails first)
- The error is logged at ERROR level for operator diagnosis
# Conflicts:
#	TODO.md
@SHA888
SHA888 merged commit bc24a8c into main Jul 31, 2026
10 checks passed
@SHA888
SHA888 deleted the docs/workspace-prompt-files branch July 31, 2026 06:32
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.

1 participant