v3.9.0

Upgrade notes — Evaluate by level

What you must do:

• At standard, the default, and at lean, /implement now runs one Evaluate pass and at most one alignment Fix round, with no second Evaluate. Run devflow gates --set full to keep up to two Fix rounds, each checked again.

Stale-install window:

• Until you run devflow init, your installed level reference has no Evaluate row, so Evaluate runs as at full. If the reference is new and the installed Evaluate agent is old, /implement runs one pass at the full report scope.

Upgrade notes — Severity tiers by level

What changes:

• At standard, the default, and at lean, /resolve no longer fixes every finding that the matrix sends to FIX_NOW. Triage sorts each kept item into a severity tier. full keeps today's triage and fixes. At every level, each issue cell in resolution-summary.md starts with its severity in brackets.
  • CRITICAL, HIGH and severe MEDIUM findings in the branch's own code stay FIX_NOW.
  • A prose-only MEDIUM finding is fixed with text edits alone. If Code must change logic to fix it, Code leaves it unedited and the item goes to Fix Separately.
  • Lower MEDIUM and LOW findings go to Fix Separately. One backlog issue records them.
  • A pre-existing finding that is not a security finding goes to Fix Separately, also when the branch touched its file.
  • A security finding stays FIX_NOW or ESCALATED at every severity, LOW and pre-existing included.
• Run devflow gates --set full to keep today's /resolve: Triage applies no tiers, every FIX_NOW item is fixed, and a pre-existing finding in a touched file is fixed.

Stale-install window:

• Until you run devflow init, your installed /resolve and Triage agent have no tiers, so they behave as at full. If Triage is new and the installed reference is missing or unreadable, Triage applies no tier, keeps every verdict and reports Tiers: not applied (reference unreadable).

Changed

• /resolve applies severity tiers at standard and lean (#484).
  • At standard and lean, Triage reads a new reference, triage/severity-tiers.md, once, after its normal checks. It runs a nine-step checklist in order, and the first step that matches decides.
    The checklist only narrows. It never changes a FALSE_POSITIVE, BY_DESIGN or ESCALATED verdict, and it never moves a finding up.
    A duplicate group takes the highest tier of its members. At full, Triage skips the new section, and the rest of the Triage agent text is byte-for-byte what it was.
  • Triage judges a security finding by its label and also by the defect that it reads in the code, at every severity. A security control that fails open or is weakened, and a false security or safety claim, count as security at every severity.
  • A prose-only fix goes to Code issue-fix with the Risk Tier Standard, prose only. No new agent is spawned. If Code leaves an item unedited for a logic change, /resolve records it as Fix Separately with the Reason needs a logic change.
  • A DEFER item goes to Fix Separately with the Reason severity tier: DEFER. The manage-debt step puts the items of one run in one shared backlog issue.
  • At every level, each issue cell in resolution-summary.md starts with its severity in brackets when the issue has one, for example [HIGH]. The **Gate level** header can carry a level note.
  • The gate level hints, the effect text of devflow gates, README.md, docs/cli-reference.md and docs/commands.md name the tiers.
  • Residual risk: the tiers rest on the Triage classification, and no live test checks it. The guards pin the text that the agents read. A finding that Triage ranks too low waits in the backlog issue until a later review brings it back.
• The level references state that a waiting phase starts at once (#600).
  • The Skipped line of resolve-levels.md and implement-levels.md now says: a phase that waits for a skipped phase starts at once.
  • The harden-scope bullet of implement-levels.md no longer says , and Phase 5 starts at once, because the Skipped line now covers it.
  • Behaviour is unchanged. Only the wording moved.
• Validate re-runs each failed test file alone (#477).
  • After a failed test run, Validate re-runs each failed test file alone, once, with verbose output.
    The bound is 20 files.
    Validate waits at most 120 seconds for each re-run, so the worst case is 40 minutes for each Validate run.
    The 120 seconds is a bound on the wait, not on the re-run: the platform moves a foreground command that reaches its timeout to the background, where it runs to the end (see docs/reference/platform-assumptions.md).
    A re-run that times out makes the file REAL.
    A re-run starts only after the path passes a strict check, and it uses the full run's own test command with only that file added.
  • Only the Phase 6 validation in /implement labels files, because only that run is given the branch base.
    In every other run, including the re-validation after QA fixes, the re-runs give failure detail and every failure is REAL.
  • A file is PASSED-ALONE only if all of these hold:
    the path is checked and tracked, neither the branch nor the working tree changed the file, its failure was a timeout, a spawn error or a resource error,
    the re-run used only that file with no name filter, it exited 0, and the tests that failed in the full run ran and passed.
    Every other failure is REAL and goes to Fix.
  • The cause is the failure that the test runner reports.
    An assertion failure is REAL, also when its message names a timeout.
    A child-process timeout that a test reports as a failed assertion is therefore REAL.
    Issue #332 tracks the repair of such tests.
  • The gate and its gate:validate claim pass only when the PASSED-ALONE files explain every failure.
    Only Validate's own report lists them, on one Passed alone: line.
    The /implement summary and the PR body do not show that line.
  • The re-run steps are in the agent reference validate/passed-alone.md.
    After updating, run devflow init.
• /implement runs one Evaluate pass at standard and lean (#483).
  • At standard and lean, Phase 5 runs Evaluate once and spawns Fix at most once. It never spawns Evaluate again. full is unchanged.
    If Fix returns COMPLETE, the report shows MISALIGNED (fixed once, not re-checked) and Phase 6 starts. Any other Fix report sends the misalignments to you for a decision.
  • Evaluate keeps every criterion and plan step in scope, security, data handling, negative and docs ones included. It drops only docs, KB, CHANGELOG, comment or cosmetic items that no criterion or step names.
    /dynamic-build and /dynamic-plan keep the full scope.
  • Evaluate reads the level only from line 1 of its prompt. The level line goes first in every spawn prompt of the phase, right after a leading OPERATION: line.
    The Fix agent no longer says that the command runs Evaluate again after each attempt.
  • Expected effect: about 25-30% less spend on Evaluate and its fixes. This figure comes from the studied episodes and is not measured here.
  • Residual risk: at standard and lean, nothing checks the one Fix round against the criteria again. Phase 6 Validate and Phase 7 QA cover behaviour. A non-behavioural criterion or the removal of unrequested code has no later check before the PR opens.
  • Known limit: no CI test checks where the level line lands in a spawn prompt at run time.
• devflow ignores curation and memory files that git tracks, and says so at session start (#626). When git tracks a file in a curation or memory data folder, or does not answer, devflow reads and writes no file in that folder. One fixed notice at session start says what to run to untrack the files. devflow curation, devflow memory, the HUD and devflow uninstall leave such a folder alone.
  • On a paused project, devflow curation --list, --show, --clear, --reset, --restore and --configure (project scope) print the pause notice and exit 1. devflow curation --status and devflow memory --status print the notice and exit 0.
  • The settings line that resolve-settings.cjs prints when it fails now reads MEMORY=off CURATION=off.
  • A direct Skim delegation that passes no CURATION value now reports (none) under "Active Decisions". An absent value now reads as off.
  • A checkout where a .git entry exists but git does not answer now pauses both features.

Fixed

• Sections marked private stay out of posted summaries (#567).
  • A review or resolution summary can hold a section whose heading starts with the word Private, in any letter case, for example ## Private notes. A heading line inside a code block counts too.
  • The PR comment leaves that section out, up to the next heading of the same or a higher level. This holds for the full report and for the stub.
  • If no public text remains, devflow posts no comment and reports **Status**: DEGRADED (no postable summary).
  • The review and resolution writers now put text that must stay out of the PR comment in a final ## Private notes section.
  • The strip does not edit your local summary file.
  • Run devflow init after you update.
• /resolve adds only triaged items to the tech debt backlog (#630).
  • Under GitHub, Linear and Jira, the manage-debt operation takes backlog items only from the ## Fix Separately and ## Deferred to Tech Debt sections of resolution-summary.md.
  • If resolution-summary.md is missing, the operation returns TRACEABILITY: DEGRADED (resolution summary missing) and leaves the backlog unchanged.
  • Run devflow init after you update.
• The evidence comment is edited in place (#504).
  • A PR keeps one evidence comment across pushes.
    update-pr-evidence edits your own evidence comment in place for each new head.
  • It posts a new comment only when you have none, or when an evidence comment from another user is newer.
  • After the edit, it reads the comment back and prints **Comment**: EDITED.
    If the text read back differs or cannot be read, it prints TRACEABILITY: DEGRADED (comment read-back mismatch).
  • A refused edit prints DEGRADED (comment edit failed).
    An own comment with no readable id prints DEGRADED (comment id unreadable).
    A failed edit never falls back to a new post.
• CI PASSING needs a passing GitHub Actions check on a mergeable PR (#618).
  • The CI wait and the merge-readiness report now read CI as passing only when at least one GitHub Actions check passed on the PR head, no check is pending or failing, and GitHub reports the PR mergeable.
  • These cases now read "status unknown" instead of a pass or "no CI":
    a PR with only external checks (reason=no-workflow-check), a PR with a merge conflict (reason=merge-conflict), and a repository with active workflows but no run on the head (reason=no-workflow-check).
    A PR with a merge conflict reads reason=merge-conflict even when a check fails or is pending.
    The gate does not report those checks until you resolve the conflict.
    A merge state that GitHub does not report in time ends the wait with reason=deadline.
    A PR that is merged or closed ends the wait at once with reason=not-open. It does not wait for a merge state.
  • "No CI" needs a mergeable PR with no checks and no active workflow file under .github/workflows/. A repository with no workflow file still reads "no CI".
    When a PR has no checks and the token cannot read Actions workflows, the wait ends with reason=gh-failed.
  • The merge-readiness report reads CI for the PR head. It counts a pass or "no CI" only when the PR head it read is the head of the evidence.
    It reads CI once and does not wait, so right after a push or a base move it can say "status unknown".
  • If your CI is not GitHub Actions, or your workflow does not run on the PR (stacked PRs, paths filters, release-only workflows, fork PRs that wait for approval), check the CI result on the PR page before merging.
    The gate then reports "CI status unknown — verify manually before merging".
  • Known limit: a passing result shows that a GitHub Actions check passed, not that the test workflow ran by name.
  • Run devflow init after you update.

Commits

• 2c7d23c docs(changelog): keep the 3.8.x notes effect-only (#647)
• 92476a8 fix(curation): pause curation and memory for git-tracked folders (#637)
• 24cd8a3 fix(git): keep private sections out of posted PR summaries (#646)
• b3a0ff9 fix(ci-wait): do not report CI PASSING when the CI workflow has not run (#644)
• 0f98287 feat(resolve): apply Triage severity tiers at standard and lean (#631)
• a53a9aa fix(git): make manage-debt add only triaged review items (#638)
• a779707 fix(evidence): edit the evidence comment in place (#636)
• 8bf560d fix(validate): re-run failed test files alone before the gate (#616)
• 60f1a28 feat(gates): run Evaluate once at standard and lean (#617)
• 123aa88 chore: restore [Unreleased] section

Shipped Issues

• #477
• #483
• #484
• #504
• #567
• #600
• #618
• #626
• #630

Traceability exceptions

Exempt (not attested): release 2 · revert 0 · bot 0 — 2c7d23c, 123aa88