Download the PHP package voku/agent-learning without Composer

Agent Learning (voku/agent-learning)

Reviewable finding, precedent, proposal, redaction, and decision-history tooling for coding-agent learning loops.

This library provides core domain logic and validation classes to support structured post-session learning for coding agents. It separates raw experiences (Findings), reusable solved-case precedent (LearningNotes), and potential guideline changes (Proposals), keeping the agent's knowledge extraction workflow structured, secure, and fully auditable.

Requirements

Installation

The package exposes the standalone CLI:

Quick Start

Shipped Assets & PackageResources

The package ships 5 first-party workflow skills under resources/skills/:

• agent-hard-constraint-author
• agent-learning-consumer
• agent-learning-ctx-evidence
• agent-learning-maintainer
• agent-learning-note

Consumers and tool integrations can resolve them programmatically without hard-coding filesystem paths:

Key Concepts

Findings

A Finding represents a single raw experience or observation captured from a task session. It stores:

• An observation and a hypothetical rule or pattern.
• A confidence level.
• Explicit validation metadata (unverified, validated, invalidated).
• A validated conclusion detailing why the pattern was verified or rejected.
• Optional learning triage metadata:
  • classification: CREATE_SKILL, UPDATE_SKILL, ADD_LEARNING_NOTE, or IGNORE.
  • pattern_key: stable dot-separated clustering key such as tests.add_before_change.
  • validation_case: concrete given / when / then behavior check.

ADD_LEARNING_NOTE is the default durable capture. CREATE_SKILL should be rare; prefer UPDATE_SKILL when an existing skill already owns the behavior. IGNORE is valid for praise, vague reflection, one-off details, and already-covered guidance.

LearningNotes

A LearningNote is a durable, evidence-backed solved-case precedent derived from validated Findings classified ADD_LEARNING_NOTE. It preserves useful context such as what happened, what failed, why the resolution worked, and when the lesson does or does not apply without promoting one case into active project guidance.

LearningNotes have stable pattern_key ownership, exact Finding/Proposal lineage, versioned schema, redaction, repository-evidence currentness, and explicit active / retired lifecycle state. The typed LearningNoteService owns prepare, publish, read/status, and retire operations; consumers use LearningNoteProjection instead of reconstructing notes/** paths.

A LearningNote is precedent, not authority. Its existence does not approve mutation, widen task scope, satisfy validation, apply a Proposal, or create/update a Skill or Constraint. voku/agent-recall-compiler may deterministically select current LearningNotes as bounded low-authority precedent, while reviewed active guidance remains stronger.

See agent-learning-note skill over the deterministic owner boundary.

Proposals

A Proposal defines a potential durable mutation to the repository's guidelines or instructions (e.g., in MEMORY.md or dedicated agent skills).

• Can represent actions like ADD, DELETE, REPLACE, REJECT, or NO_DURABLE_LEARNING.
• References one or more validated source findings that back it up.
• Contains metadata about target type, scope, proposed boundary, validation checklist, status, and approval.
• May carry the same learning_decision, pattern_key, and validation_case fields used by consolidation. CREATE_SKILL proposals additionally require an overlap_check proving existing skills were inspected and no overlapping skill owns more than 50% of the behavior.

Constraint Specifications

A ConstraintSpecification is a typed, reviewable bridge from confirmed learning to executable validation. Constraint proposals describe the engine, rule identifier, scope, objective violation, allowed boundaries, false-positive risk, validation commands, local example rules, target rule path, and registration files. The package validates whether the learning is stable and precise enough for a later PHPStan, PHP-CS-Fixer, test, or CI generation step.

Evidence

Findings must be backed by concrete, verifiable evidence. Supported types include:

• file_reference: References to specific files and line numbers.
• commit: Reference to a specific git commit.
• test_result / phpstan_result: Command execution command and summary.
• review_comment: Pull/merge request comments or reviews.
• issue_reference: Bounded issue or ticket tracker reference.
• agent_history_reference: Bounded reference to inspected local agent-history evidence discovered with ctx.
• Others (e.g., schema_reference, runtime_observation, manual_verification).

Using ctx as historical evidence

agent-learning does not index agent history itself. If ctx is installed, use it before writing findings to discover relevant prior sessions, failed attempts, rejected approaches, and validation history.

ctx hits are evidence references, not durable memory. Record only bounded summaries and ctx IDs in findings. Durable learning still flows through validated findings, LearningNotes where appropriate, proposals, and reviewed decisions.

ctx helps find what happened before; agent-learning decides what deserves to survive.

See docs/ctx-integration.md for the evidence schema and the local-history boundary. The related package skill is agent-learning-ctx-evidence; the ctx-side search skill is ctx-agent-history-search.

Decision History

A persistent record of approved or rejected proposals stored in JSON Lines (.jsonl) format.

• decisions.jsonl logs approved and applied mutations.
• rejected-proposals.jsonl logs rejected candidate proposals with detailed reasons.

Dream maintenance cycle

agent-learning dream is a deterministic, read-mostly maintenance pass over immutable recall-selection and guidance-outcome histories. It validates the learning root, previews compact history projections, audits evidence coverage, evaluates promotion/staleness, and produces a byte-stable v1 review report (except explicitly volatile proposal creation timestamps).

The immutable DreamRunResult contains evaluated guidance, bounded evidence/outcome warnings, generated and suppressed decisions, metrics, and remaining uncertainty. Its stable keys include evidence, sources, scope, target tier, wording, and explicit lineage. Outcome completeness joins the selected (compilation_id, guidance_id) identities and is null when no guidance was selected; it never treats an empty history as 100% complete. The stale-candidate rate uses the reviewable decision population, and duplicate decisions measure producer overlap before deduplication.

The maintenance policies require bounded deterministic identity or explicit lineage:

• REPLACEMENT_CANDIDATE requires an approved/applied REPLACE successor for the same target, supported by exact old wording, explicit supersedes_proposal_id, harmful outcome plus corrects_proposal_id, newer validated supersedes_findings, or a strict scope narrowing.
• CONFLICT reports explicit conflicts_with, a later invalidated/superseded finding with contradicts_proposal_id, or exact normalized duplicate active wording with overlapping scope and source evidence across tiers. Different prose alone is never guessed to be contradictory.

The command never approves, applies, retires, deletes, archives, or rewrites guidance. --write-candidates writes review records only; conflict records use NO_DURABLE_LEARNING, so a reviewer can acknowledge or reject the report without an executable mutation. Existing candidate, rejected, and acknowledged records suppress only the same stable decision key.

Review a stale/replacement/conflict result by preserving the decision record first, then explicitly acknowledge/reject it or create/approve/apply a separately reviewed REPLACE/DELETE proposal. Retire previously applied guidance only with proposal-retire and an explicit reason; the proposal remains auditable in proposals/retired/ and immutable history, but is excluded from active recall. Archive or supersede a finding through its lifecycle transition with a recorded reason; a replacement must retain validated source-finding lineage.

An applied memory/skill proposal proves it landed by pinning the whole target file in applied_validation.target_content_hash. A shared home such as MEMORY.md carries many rows, so an edit to any other row - a repository layout move repairing an evidence path, for example - makes every proof on that file report drift it did not cause. Repair them with proposal-reanchor, which takes the target, not one proposal, because the drift belongs to the file:

Every applied memory/skill proof on that target is re-pinned in one transaction, and only while each proposal's own guidance wording is still present - the same assertion the validator makes - so a target that lost a rule is refused and rolled back rather than re-pinned. Proofs are matched by the file they resolve to rather than by how they spell it, so MEMORY.md and ./MEMORY.md are one target and no subset is left stale. Approval, application and validation evidence stay untouched; the repair adds the new hash, an explicit actor and an explicit reason, and one record per proposal in history/reanchored-proposals.jsonl.

Every transition - approve, reject, retire, acknowledge, apply and reanchor - allocates its history id and writes under one root-scoped exclusive lock held at history/.transition.lock, because each allocates that id by scanning the log it is about to append to. Concurrent runs would otherwise agree on the same sequence number and write duplicate ids into immutable history.

Re-anchoring is a proof repair, not a decision. It never makes a target that lost the rule look applied, and it is not a substitute for proposal-retire when the guidance itself should leave the active pool.

When one proof on a shared target drifted semantically - its reviewed wording was later refined - while the others only went stale, neither proposal-retire nor a plain proposal-reanchor can commit: each transition validates the whole root, so the drifted proof and the stale ones block each other. Name the drifted proof and the reviewed proposal that replaces it:

The superseded proof is retired in the same transaction (with superseded_by, an explicit actor and reason, and a history/retired-proposals.jsonl record) instead of being re-pinned; every other proof on the target is re-pinned under the usual wording assertion, and the root is validated once. The replacement must exist, must not be retired or rejected, and must name the same target. It is not approved or applied by this command.

Use --format=json for CI. The report has no generated timestamp, so equivalent immutable inputs yield byte-stable output. It reports outcome completeness, active guidance by tier, candidate queue age, suppressed decisions, outcome signals, and median finding-to-human-decision time. --project-root is optional because the learning-root configuration and legacy layout resolver determine it by default.

Compact history projections

Raw findings, proposals, and event histories remain the audit source. Create compact, reproducible working views only with an explicit write command:

history-rebuild writes history/active-guidance.snapshot.json, history/chronicle.jsonl, and history/projection-manifest.json. The snapshot contains only approved/applied guidance; the chronicle records bounded lifecycle summaries for retired, rejected, acknowledged, superseded, archived, invalidated, and consolidated material. Both retain source IDs and content digests. The manifest hashes every raw input, so history-status fails clearly after source or projection corruption; rebuild to recover from any complete immutable source history. Dream reports expose source files/bytes, projection size, compression ratio, and an opt-in rebuild measurement via --include-runtime.

Core Classes & APIs

The package codebase is organized under the voku\AgentLearning namespace in the following structure:

Value Objects & Enums

• Finding: Read-only entity representing a captured session finding.
• FindingStatus: Enum defining finding lifecycles (candidate, validated, invalidated, rejected, superseded, consolidated, archived).
• LearningNote: Read-only durable solved-case precedent with stable pattern identity and exact source lineage.
• LearningNoteStatus: Enum defining LearningNote lifecycle (active, retired).
• LearningNoteProjection: Compact read-only sibling/Recall projection that hides private storage layout.
• Proposal: Read-only entity representing a proposed modification to guidelines.
• ProposalStatus: Enum defining proposal states (candidate, approved, rejected, applied, retired).
• Action: Enum representing actions (NO_DURABLE_LEARNING, ADD, DELETE, REPLACE, REJECT).
• ConstraintSpecification: Read-only model for hard-constraint promotion candidates.
• GuidanceUsageSummary: Read-only projection of recall eligibility, selection, application, explicit outcomes, task spread, timestamps, and evidence event IDs.
• ConstraintEngine: Enum defining supported hard-constraint engines (phpstan, php_cs_fixer, test, ci).
• Detectability: Enum describing whether the violation is statically, syntax-locally, runtime, or cross-file detectable.
• FalsePositiveRisk: Enum declaring expected false-positive risk (low, medium, high, unknown).

Parsers & Repositories

• FindingParser: Parses a finding JSON record or file.
• ProposalParser: Parses a proposal JSON record or file.
• FindingRepository: Loads validated findings from root directories.
• LearningNoteRepository: Owns private LearningNote persistence and active/retired state; consumers should prefer the service/projection boundary.
• ProposalRepository: Loads proposals under different lifecycle folders.
• RecallSelectionEventRepository: Loads immutable recall-selection JSONL events produced by voku/agent-recall-compiler.
• GuidanceOutcomeEventRepository: Loads immutable per-guidance outcome JSONL events.

Validators

• FindingValidator: Enforces structure, format, and lifecycle consistency for findings.
• ProposalValidator: Validates proposal mutations, targets, actions, and references.
• EvidenceValidator: Inspects list of evidence objects to ensure required fields for each type exist.
• JsonlValidator: Parses and validates JSON Lines log formats.
• RedactionGuard: Scans all content for credentials, secrets, or sensitive configuration keys to prevent accidental leaks.
• DecisionHistoryValidator: Validates log consistency of the decision history.
• ConstraintPromotionValidator: Validates that constraint proposals come from confirmed findings and contain explicit promotion-gate evidence.
• ConstraintManifestActivator: Writes the active manifest consumed by recall tooling after an approved or applied constraint rule exists in the project.

Utilities & Infrastructure

• LearningNoteService: Typed prepare/publish/read/status/retire owner boundary with lineage, redaction, duplicate-pattern and currentness validation.
• ConsolidationPromptBuilder: Assembles validated findings and rejected proposals history into a structured LLM consolidation prompt.
• ConstraintGenerationPackageExporter: Exports specification.json, source findings/proposals, examples, validation plan, and generation prompt for coding-agent rule generation.
• ConstraintLoopRunner: Drives the approved generated-rule close-out path by exporting, applying, and activating a hard constraint with one explicit command.
• GuidanceUsageProjector: Rebuilds deterministic usage summaries from immutable event histories without mutable counters.
• GuidanceEvolutionEvaluator: Applies conservative tier-specific promotion and review policies.
• RecordAccess: Utility helper to extract strongly typed fields from raw array data.
• Json: Helper for decoding files safely.
• ValidationException: Custom runtime exception with file name, line numbers, and record IDs context.

Validation Specifications

Finding Validation

1. Finding ID: Must match finding.YYYY-MM-DD.NNN.
2. Created At: Must be a valid ISO 8601/Atom timestamp string.
3. Task ID: Must match the configured task ID pattern (passed via $taskIdPattern to the FindingValidator constructor; defaults to '/^(?:[A-Z][A-Z0-9_-]*-\d+|TODO@[\w:\/.-]+)$/').
4. Observation/Hypothesis Separation: Both must be non-empty strings and cannot be identical.
5. Confidence: Must be one of low, medium, or high.
6. Validation Status: Must be one of unverified, validated, or invalidated.
7. Lifecycle Enforcements:
   • candidate requires validation_status=unverified.
   • validated and consolidated require validation_status=validated.
   • invalidated requires validation_status=invalidated.
   • superseded and rejected require validation_status=validated or validation_status=invalidated.
   • archived preserves the prior validation state and may use any supported validation_status.
   • A validation_status=validated finding requires a non-empty validated_conclusion.
   • The validated_conclusion must not be identical to the hypothesis.

Proposal Validation

1. Proposal ID: Must match proposal.YYYY-MM-DD.NNN.
2. Created At: Must be a valid ISO 8601/Atom timestamp string.
3. Mutations Constraint: Fields mutations, changes, or targets must contain at most 1 item to prevent overly broad proposals.
4. Source Findings: Must have at least 1 referenced source finding.
5. Action-Specific Constraints:
   • If not a NO_DURABLE_LEARNING action: requires target_type, target, scope (non-empty list), boundary (non-empty), and validation checklist.
   • ADD action requires new wording.
   • DELETE action requires old wording.
   • REPLACE action requires both old and new wording.
6. Status Constraints:
   • Proposal action describes the requested durable change (ADD, DELETE, REPLACE, REJECT, NO_DURABLE_LEARNING).
   • Proposal status describes the human lifecycle decision (candidate, approved, rejected, applied, retired).
   • Durable actions (ADD, DELETE, REPLACE) may be candidate, approved, rejected, applied, or retired.
   • REJECT and NO_DURABLE_LEARNING may only be candidate or rejected.
   • APPROVED, APPLIED, or RETIRED proposal requires approved_by and approved_at timestamp.
   • REJECTED proposal or a REJECT action requires a non-empty reason.
   • RETIRED proposal requires a non-empty reason. Retirement only applies to a previously APPLIED proposal whose durable change is now fully captured in its target skill/doc/memory home; voku/agent-recall-compiler's loadActiveGuidance() only scans proposals/approved/ and proposals/applied/, so a retired proposal stops being read into every future active recall guidance pool without needing any change in that package.
7. Lifecycle Directory Check: Proposal files under proposals/<status>/ must embed the same status value.
8. Scope Broader Check: If proposal scope includes entries not present in the referenced findings, a scope_justification must be provided.
9. Constraint Promotion Gates: Constraint proposals require confirmed source findings, several independent findings or a critical-incident justification, explicit scope, explicit allowed boundaries, objective detectability, validation commands, declared false-positive risk, local example rule references where available, and engine-compatible target paths/commands.
10. Learning Triage Gates: When present, learning_decision must align with the proposal:
    • IGNORE requires NO_DURABLE_LEARNING.
    • ADD_LEARNING_NOTE preserves the raw learning without pretending it is ready for skill promotion.
    • UPDATE_SKILL requires target_type=skill.
    • CREATE_SKILL requires ADD, target_type=skill, pattern_key, validation_case, and an overlap_check with inspected skills and max_overlap_percent <= 50.

Applied Constraint Metadata

When a constraint proposal is marked applied, its validation JSON must include generated_files, registration_file, commit, tests, validation_result, and content_hashes. This preserves lineage from finding to proposal, generated rule, registration, commit, validation, and later outcome.

Active Constraint Manifests

After a generated constraint is approved and implemented, run constraint-activate to create constraints/active/constraint.<rule_id>.json. The command validates the proposal, checks the target rule file and registration files exist relative to the project root, and writes the exact engine, rule identifier, scope, validation commands, and source proposal that voku/agent-recall-compiler selects later.

Learning roots may define config.json to avoid hard-coding one repository layout:

Relative paths are resolved from the learning root. CLI options --project-root, --constraint-generation-dir, and --active-constraints-dir override config.json for one run. Without configuration, the package keeps the legacy project-root inference for infra/doc/agent-learning, .agent-learning, docs/agent-learning, and agent-learning.

Redaction Constraints

All keys and values are checked using RedactionGuard against secret assignment patterns. Any matches of standard credential assignments (e.g. password, token, api_key, ms-Mcs-AdmPwd patterns) throw a validation exception.

JSON Structure Formats

Example Finding

With learning triage:

Example Proposal

Development & Testing

Bundled Agent Skills

This package ships package-specific skills under skills/:

• agent-learning-consumer: for end users setting up a learning root, capturing findings, validating proposals, and preparing consolidation input.
• agent-learning-note: for authoring or updating one evidence-grounded LearningNote from explicit validated Finding IDs through LearningNoteService/CLI owner boundaries; it never promotes the note into active guidance.
• agent-learning-ctx-evidence: for using ctx-backed local agent-history search as bounded evidence references without importing raw transcripts.
• agent-hard-constraint-author: for end users promoting validated findings into executable PHPStan, PHP-CS-Fixer, test, or CI constraints.
• agent-learning-maintainer: for maintainers changing voku/agent-learning source, tests, docs, or local vendor syncs.

Running Tests

To run unit and integration tests for this package:

Or use the local Makefile:

Static Analysis

To run PHPStan checks on the package:

Or use the local Makefile:

CLI

The Composer binaries expose the package workflows without requiring consuming-project classes:

agent-learning-note prepare emits only owner-validated authoring inputs. publish revalidates source Finding lineage, redaction, duplicate pattern ownership, schema, and repository evidence before atomically writing a durable note. status exposes typed currentness without making callers parse private storage.

prepare prints the selected finding IDs before writing the prompt. Empty selections fail unless --allow-empty is passed. If templates/consolidation-prompt.md exists under the learning root, its content is appended to the generated consolidation input as a project-specific prompt addendum.

--root may point either to the learning root itself or to a project root containing one of these directories:

• infra/doc/agent-learning
• .agent-learning
• docs/agent-learning
• agent-learning

Zero-byte .json files are treated as extraction placeholders and skipped. Non-empty finding, proposal, and history records are validated strictly.

Guidance Usage Evaluation

guidance-evaluate consumes immutable event histories produced by voku/agent-recall-compiler, rebuilds deterministic usage summaries, and prints conservative decisions for finding-to-memory, memory-to-skill, skill-to-constraint, and stale/replacement review paths.

It does not edit MEMORY.md, skills, active constraints, PHPStan configuration, or CI. With --write-candidates, it may write only reviewable proposal files under proposals/candidate/; no proposal is approved, applied, or activated automatically.

Schema details, policy gates, and duplicate behavior are documented in examples/guidance-evaluation.