// Release note / workflow
What’s new in .knowledge 3.4.0: one task-bound workflow
.knowledge 3.4.0 turns one focused engineering task into a clear path: route the task, record the starting files, run real builds and tests, and reuse verified results when the same checks safely apply.
// direct answer
Short answer
3.4.0 brings task routing, a recorded set of starting files, verification with real builds and tests, and safe result reuse into one workflow. The agent starts with a precise task route and finishes with a clear record of what passed and what still needs review.
Understand what changes in 3.4.0, how the integrated workflow works, and what was verified for the release.
// integrated workflow
Start one task before broad exploration
Run agent-task begin with an explicit task, module, and optional path. It creates a task-bound route and records the exact first-read snapshot that the agent should consume before opening the repository broadly.
The snapshot has its own content fingerprint. At finish, .knowledge can confirm that the result refers to the same first read the agent started with, even if the repository changed during the task.
The primary change is still evaluated with physical commands and tests. Current code and current tests remain above generated routing records in the source-of-truth order.
// verified result
Run checks once and reuse the result safely
agent-task finish runs the declared verification commands once and records their actual outcome.
When a maintenance item is covered by those same checks, .knowledge can reuse the verified result instead of repeating the work. Reuse stays limited to the exact item the checks support.
If the process is interrupted, it can resume without duplicating the result. When evidence is missing or no longer matches, the repair simply stays open for review.
// release verification
What was tested for 3.4.0
The 3.4.0 compatibility matrix completed 9/9 OS and Node combinations, 243/243 shipped self-test executions, 12 integration bridges per combination, and 3/3 upgrades from 3.2.11 on Node 22.
The end-to-end verification suite also covered packaging, clean installation, upgrades, routing, Inspector startup, and lock safety. Every check in that suite passed.
Controlled routing stress tests completed 48/48 routes, kept every expected source and dependency in view, reduced 3,584 considered modules to 96 selected modules, and recorded a 90.77% median reduction in local first-read bytes.
Those routing numbers are local physical-byte measurements. They are not provider tokens, API cost, speed, coding accuracy, or a guarantee that every task has the same result.
// concrete example
One scoped task from start to finish
Begin with the task text and the part of the repository it belongs to. The returned first-read snapshot points the agent to the files and tests most likely to matter.
Implement the change and run real verification commands for the requested outcome.
Finish the task. .knowledge records what passed, keeps any unverified repair visible, and reuses a verified result only when the same checks clearly apply.
The final report shows the engineering result, repository health, and local routing measurement separately so reviewers can understand what each number means.
// files you can inspect
Where to inspect the 3.4.0 workflow
Some files appear after you import .knowledge or complete a task; their badges show when each one becomes available.
.knowledge/tools/task-routing.js
This tool creates the task boundary and first-read snapshot used by the integrated workflow.
- Seeing how a task route is created
- Understanding the routed first read
- Replacing current source and tests
.knowledge/docs/trust-evidence-routing-repair.md
This guide explains the source-of-truth order and how routing, evidence, and repair work together.
- Learning the trust model
- Understanding repair safety
- Substituting documentation for current code and tests
.knowledge/routing/tasks/<task_scope_hash>/current.json
The route points to the current task snapshot, selected modules, and first-read material for one explicit task.
- Reading the first-read path
- Checking the active task route
- Replacing the source files it points to
.knowledge/maintenance/pr_summary.md
The summary presents the engineering result, repository health, routing state, and remaining work as separate signals.
- Reviewing the completed task
- Seeing what still needs attention
- Replacing the underlying test output
// commands to try
Start and finish a scoped task
node .knowledge/tools/agent-task.js begin --task="<explicit task>" --scope-module=<module> --scope-path=<path> --json - what it does
- A task-bound workflow and exact first-read snapshot are created for the explicit scope.
- where to look
- begin.route.first_read.content and .knowledge/routing/tasks/<task_scope_hash>/current.json
- before you run it
- Choose the module and path that actually contain the work.
node .knowledge/tools/agent-task.js finish --workflow-id=<ATW-id> --request=<finish.json> --json - what it does
- The real builds and tests, recorded starting context, and any safely reused result are saved together.
- where to look
- The task result, verification output, and review summary
- before you run it
- Use real build, test, migration, security, or UI checks for the task.
From task request to verified result
// release results
3.4.0 evidence snapshot
| Test area | Result | What was checked |
|---|---|---|
| Compatibility matrix | 9 / 9 cells | Windows, Ubuntu, and macOS on Node 18, 20, and 22; 27 shipped self-tests and 12 integration bridges per cell. |
| Upgrade smoke | 3 / 3 | 3.2.11 to 3.4.0 on Node 22, once per operating system. |
| End-to-end verification | All checks passed | Packaging, clean install, upgrade, routing, Inspector startup, and lock safety. |
| Routing stress | 48 / 48 routes | Every expected source and dependency remained available; 3,584 modules were narrowed to 96 selected modules. |
| Local first-read reduction | 90.77% median | Median reduction in physical first-read bytes across the controlled test workspaces. |
// quick FAQ
FAQ
Why acknowledge the exact first read?
The acknowledgement binds the final result to the same task snapshot the agent started with. That makes route changes and repository drift visible instead of silently mixing two different task contexts.
Can .knowledge reuse a verification result?
Yes, when the same checks clearly cover the same repair item. Other repairs remain open and visible.
Does the 90.77% result mean 90.77% fewer model tokens?
No. It is the median reduction in local first-read physical bytes across the controlled routing tests described above. It is not provider-token telemetry, API cost, runtime speed, or a model-accuracy measure.
What happens when a repair cannot be verified?
It stays open in the result instead of being marked complete. The reviewer can see what evidence is missing and decide the next step.
// next step
Use this workflow for meaningful scoped engineering work
Begin with an explicit route, run the relevant engineering checks once, and finish with a result that shows what passed and what still needs attention.