NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist, #4675 most downloaded on Packagist
Reviewable finding, proposal, redaction, and decision-history tooling for coding-agent learning loops.
Latest stable
0.19.0
Last release 13 days ago
09 Nov 2026
Ships on a steady schedule
a new release about every 2 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
5 months old
81 releases · first in 2026
Drag across the ruler to compare, or tap a release to open it.
[*]: update changelog for 0.8.12 release and refactor unit tests to u…
[*]: update changelog for 0.8.12 release and refactor unit tests to u…
Add explicit history-rebuild and history-status commands. They produce deterministic active-guidance.snapshot.json, chronicle.jsonl, and a source-dige
history-rebuild and history-status commands. They produce
deterministic active-guidance.snapshot.json, chronicle.jsonl, and a
source-digest manifest from immutable learning evidence, and fail clearly
when a compact projection is missing, corrupted, or stale.(compilation_id, guidance_id) identities, report no rate for an empty
selection history, count producer decision overlap before deduplication, and
use the reviewable decision population for the stale-candidate rate.Your coding agent can read these notes before it upgrades. Set up the MCP server →
One column per month.
Extend Agent Dreaming replacement detection with explicit newer-finding lineage, harmful-outcome corrected successors, and scope narrowing; extend con
All notable changes to voku/agent-learning will be documented in this file.
The format follows Keep a Changelog, and this project uses semantic versioning where practical.
Include the Dreaming value objects, evaluator, evidence-quality auditor, and replacement/conflict policies in the package archive. Version 0.8.8 wired
agent-loop learn dream to fail at runtime with a missing-class error.dream: a deterministic, human-reviewed guidance-maintenance command. It rebuilds its result from immutable recall-selection and guidance-outcome histo
dream: a deterministic, human-reviewed guidance-maintenance command. It
rebuilds its result from immutable recall-selection and guidance-outcome
histories; audits missing versus unknown outcomes, unresolved file evidence,
and aged findings; reports compact machine-readable or text output; and
writes no durable guidance unless --write-candidates is explicitly passed.
Reports deliberately omit generated timestamps so equal inputs produce
byte-stable output.REPLACEMENT_CANDIDATE production for exact, explicit applied
guidance successors, plus report-only CONFLICT records. A conflict needs
explicit conflicts_with lineage; unrelated wording under one pattern key is
not guessed to be contradictory.guidance-evaluate --write-candidates regenerated a proposal a reviewer had already declined. GuidanceCandidateProposalWriter::findExistingCandidate()
guidance-evaluate --write-candidates regenerated a proposal a reviewer had
already declined. GuidanceCandidateProposalWriter::findExistingCandidate()
only scanned proposals/candidate/, so once a candidate was rejected (and
therefore moved to proposals/rejected/) the next run no longer saw it and
wrote an identical decision under a fresh proposal ID. Rejecting five
auto-generated candidates and re-running the command immediately recreated
all five. The lookup now also scans proposals/rejected/ and
proposals/acknowledged/, so a terminal human decision suppresses
regeneration of the same guidance_id + decision_type + source_tier +
target_tier combination. approved/applied are deliberately not included:
those describe a change that landed, not a decision to stop proposing.ConstraintEngine::PHPCS (phpcs). Repositories that enforce constraints with PHP_CodeSniffer sniffs previously had no honest way to express that: the e
ConstraintEngine::PHPCS (phpcs). Repositories that enforce constraints with
PHP_CodeSniffer sniffs previously had no honest way to express that: the enum
offered only phpstan, php_cs_fixer, test, and ci, and php_cs_fixer
is a different tool (php-cs-fixer) with a different rule location and command,
so reusing it would have mislabeled the constraint. Discovered downstream in
a downstream repository, where a *_UnitCest.php constraint had to be a phpcs
sniff because phpstan.neon excludes *Cest.php from analysis entirely,
making an equivalent PHPStan rule unable to ever fire. ConstraintPromotionValidator
now applies the matching symmetry checks for the new engine: a phpcs
constraint requires a phpcs/codesniffer validation command and a
target_rule_path pointing at a /Sniffs/ location.SkillStalenessPolicy, MemoryToSkillPromotionPolicy, and SkillToConstraintPromotionPolicy did not propagate an approved proposal's scope_justification
SkillStalenessPolicy, MemoryToSkillPromotionPolicy, and
SkillToConstraintPromotionPolicy did not propagate an approved proposal's
scope_justification into the generated candidate's proposalExtras, unlike
MemoryStalenessPolicy (fixed in 0.8.4/d436428 for the memory tier only).
A guidance-evaluate --write-candidates run for a skill-tier STALE_CANDIDATE
or a memory-to-skill / skill-to-constraint PROMOTION_CANDIDATE whose source
proposal's scope was legitimately broader than any single cited finding
(and had a scope_justification explaining why) would hit
ProposalValidator's "proposal scope is broader than source finding
evidence without justification" check and abort the entire
write-candidates batch, including every other pending candidate. All three
policies now build proposalExtras['scope_justification'] from the source
proposal the same way MemoryStalenessPolicy does.guidance-evaluate now warns when history/outcomes.jsonl contains records in the older "outcome.*" session-summary shape (helpful/irrelevant/harmful as
guidance-evaluate now warns when history/outcomes.jsonl contains records
in the older "outcome." session-summary shape (helpful/irrelevant/harmful
as proposal-ID arrays, predating the per-guidance-item "guidance-outcome."
shape). OutcomeRepository::loadAll() already validated both shapes without
error, but GuidanceOutcomeEventRepository::load() -- and therefore every
GuidanceUsageProjector statistic and promotion/staleness decision -- has
always silently skipped anything that is not guidance-outcome.*. A
guidance item whose only recorded usage was in the older shape was
indistinguishable from one that was never used at all, with no signal that
older data was excluded. New GuidanceOutcomeEventRepository::countLegacyRecords()
makes that count explicit; guidance-evaluate now prints it before its
usual summary/decision output when the count is non-zero. This does not
migrate old records into the new shape (that would require fabricating
matching recall-selection linkage that never existed for them) -- it only
makes the existing exclusion visible instead of silent.Preserve an approved memory proposal's non-empty scope_justification when guidance-evaluate --write-candidates creates a stale-review candidate. This
scope_justification when
guidance-evaluate --write-candidates creates a stale-review candidate. This
keeps a valid broader scope reviewable instead of failing candidate validation
after the justification was dropped during projection.add docs about https://github.com/ctxrs/ctx and how to use it for findings existing learnings from your coding agents
backlog CLI command that lists validated findings not yet consolidated into a proposal and
exits non-zero while any remain. This is a deterministic gate for the recurring "only the recent
findings were processed" failure: a learning-loop pass can no longer be reported as done while a
backlog of unconsolidated findings exists. --allow-nonempty makes the listing informational
(exit 0) for reporting without gating. Backed by BacklogCommandTest.Added a retired ProposalStatus, reachable only from applied via the new ProposalTransitionManager::retire() / proposal-retire CLI command. Once a prop
retired ProposalStatus, reachable only from applied via the new
ProposalTransitionManager::retire() / proposal-retire CLI command. Once a proposal's durable
change is fully captured in its target skill/doc/memory home, retiring it moves the file to
proposals/retired/ and appends an immutable record to the new history/retired-proposals.jsonl
(validated by DecisionHistoryValidator). Consuming projects do not need any change in
voku/agent-recall-compiler: its RecallRepository::loadActiveGuidance() already only scans
proposals/approved/ and proposals/applied/, so a retired proposal is simply never read into the
active recall guidance pool again, instead of accumulating there forever.ProposalValidator's source-finding check now also accepts findings with
FindingStatus::ARCHIVED (previously only VALIDATED/CONSOLIDATED), and
ProposalTransitionManager::approve()'s inline check was widened to match, so a finding can be
archived after its proposal already cited it as evidence without breaking that proposal's
validation on a later validate/approve/retire run.Cli::parseOptions() used foreach ($tokens as $index => $token) with a manual $index++ to skip a consumed option value. foreach ignores manual mutation
Cli::parseOptions() used foreach ($tokens as $index => $token) with a manual $index++ to skip
a consumed option value. foreach ignores manual mutation of the loop variable, so the consumed
value was re-read on the next iteration and pushed onto $arguments as a bogus leading positional
argument. Any command that reads its primary ID from $arguments[0] (proposal-approve,
proposal-reject, proposal-mark-applied, finding-transition, and constraint-export/
constraint-activate/constraint-loop when given a bare ID) silently operated on the wrong record
whenever at least one --option value pair preceded it. Switched to an explicit indexed for loop
(matching the already-correct pattern in the sibling voku/agent-recall-compiler package) and added
a regression test that exercises proposal-approve through Cli::run() with space-separated options.Add validating recall history in learning root checks
Add strict recall-selection and per-guidance outcome event models, parsers, and JSONL repositories.
GuidanceUsageProjector summaries for eligibility, selection, application, explicit outcomes, distinct tasks, timestamps, and evidence event IDs.guidance-evaluate CLI to validate event histories, print deterministic usage summaries and decisions, and optionally write reviewable candidate proposals.evolution_decision.OutcomeRepository validation to read new guidance-outcome.* event rows alongside legacy aggregate outcome records.Add typed learning triage with LearningClassification values for CREATE_SKILL, UPDATE_SKILL, ADD_LEARNING_NOTE, and IGNORE.
LearningClassification values for CREATE_SKILL, UPDATE_SKILL, ADD_LEARNING_NOTE, and IGNORE.ValidationCase support so findings, consolidation results, and proposals can carry concrete given / when / then behavior checks.classification, pattern_key, and validation_case fields to findings.learning_decision, pattern_key, validation_case, and overlap_check fields to consolidation results and proposals.ADD_LEARNING_NOTE, prefer UPDATE_SKILL over duplicate skill creation, and reject praise, self-justification, or generic advice.CREATE_SKILL proposals to prove existing skill overlap was inspected and that maximum overlap is not above 50%.Add constraint-activate to write active constraint manifests from approved or applied constraint proposals.
constraint-activate to write active constraint manifests from approved or applied constraint proposals.constraint-loop to export, apply, and activate generated constraints with one explicit tooling command.config.json path settings for project_root, constraint_generation_dir, and active_constraints_dir.Add typed constraint promotion models (ConstraintSpecification, ConstraintEngine, Detectability, FalsePositiveRisk) for hard-constraint candidates.
ConstraintSpecification, ConstraintEngine, Detectability, FalsePositiveRisk) for hard-constraint candidates.constraint-export to write generation packages containing specifications, source findings/proposals, examples, validation plans, and generation prompts.violation_detected, false_positive, rule_suppressed, and rule_disabled.Add Active Guidance modeling and repository to parse/load active guidance files.
ADD, DELETE, REPLACE, REJECT, NO_DURABLE_LEARNING).proposal-import, finding-transition, proposal-approve, proposal-reject, proposal-mark-applied).Add deterministic multi-selector consolidation preparation with repeatable --finding, --task, --ticket, and --scope selectors plus --since and --until
--finding, --task, --ticket, and --scope selectors plus --since and --until date filters.templates/consolidation-prompt.md from the learning root during prepare.ProposalLifecycle.FindingSelection for explicit consolidation input selection.PROJECT-123, GH-123, and TODO@path.DecisionRecorder to DecisionHistoryValidator because the class validates history and does not record decisions yet.validation_status combinations.REJECT with approved.proposals/<status>/ directory.approved_at timestamps on proposals when approval metadata is present.Initial CLI for validating findings, proposals, and decision history.
templates/consolidation-prompt.md from the learning root during prepare.