README

Reviewable finding, 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) from potential guideline changes (Proposals), keeping the agent's knowledge extraction workflow structured, secure, and fully auditable.

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.

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.

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.
Others (e.g., schema_reference, runtime_observation, manual_verification).

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.

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).
Proposal: Read-only entity representing a proposed modification to guidelines.
ProposalStatus: Enum defining proposal states (candidate, approved, rejected, applied).
Action: Enum representing actions (NO_DURABLE_LEARNING, ADD, DELETE, REPLACE, REJECT).

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.
ProposalRepository: Loads proposals under different lifecycle folders.

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.
DecisionRecorder: Validates log consistency of the decision history.

Utilities & Infrastructure

ConsolidationPromptBuilder: Assembles validated findings and rejected proposals history into a structured LLM consolidation prompt.
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

Finding ID: Must match finding.YYYY-MM-DD.NNN.
Created At: Must be a valid ISO 8601/Atom timestamp string.
Task ID: Must match the configured task ID pattern (passed via $taskIdPattern to the FindingValidator constructor; defaults to '/^(ITPNG-\d+|TODO@[\w:\/.-]+)$/').
Observation/Hypothesis Separation: Both must be non-empty strings and cannot be identical.
Confidence: Must be one of low, medium, or high.
Validation Status: Must be one of unverified, validated, or invalidated.
Lifecycle Enforcements:
- A validated finding status requires validation_status=validated.
- A validation_status=validated finding requires a non-empty validated_conclusion.
- The validated_conclusion must not be identical to the hypothesis.

Proposal Validation

Proposal ID: Must match proposal.YYYY-MM-DD.NNN.
Created At: Must be a valid ISO 8601/Atom timestamp string.
Mutations Constraint: Fields mutations, changes, or targets must contain at most 1 item to prevent overly broad proposals.
Source Findings: Must have at least 1 referenced source finding.
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.
Status Constraints:
- APPROVED or APPLIED proposal requires approved_by and approved_at timestamp.
- REJECTED proposal or a REJECT action requires a non-empty reason.
Scope Broader Check: If proposal scope includes entries not present in the referenced findings, a scope_justification must be provided.

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

{
  "id": "finding.2026-06-08.001",
  "task_id": "ITPNG-1234",
  "session": "session_abc123",
  "created_at": "2026-06-08T10:00:00+00:00",
  "created_by": "agent_alpha",
  "scope": [
    "lib/framework/forms"
  ],
  "observation": "FormElement validation fails when checking numeric bounds if string decimals are passed.",
  "evidence": [
    {
      "type": "file_reference",
      "path": "lib/framework/forms/FormElement.php",
      "line": 42
    },
    {
      "type": "test_result",
      "command": "make test_unit_file FILE=tests/FormElement_UnitCest.php",
      "summary": "Failed asserting that false is true on DecimalBound test"
    }
  ],
  "hypothesis": "String decimal inputs should be normalized to float/int before calling range checks in FormElement.",
  "validated_conclusion": "Normalizing value to float in range validation resolves bounds failures without side-effects.",
  "confidence": "high",
  "validation_status": "validated",
  "status": "validated",
  "sensitivity": "public"
}

Example Proposal

{
  "id": "proposal.2026-06-08.001",
  "created_at": "2026-06-08T11:30:00+00:00",
  "action": "REPLACE",
  "target_type": "skill",
  "target": "itp-form-validation",
  "scope": [
    "lib/framework/forms"
  ],
  "source_findings": [
    "finding.2026-06-08.001"
  ],
  "old": "Validate range bounds directly using the raw inputs.",
  "new": "Ensure numeric inputs are cast/normalized to numeric values before validating range bounds.",
  "reason": "Prevents float/string type comparisons from failing bounds checks.",
  "boundary": "Only run numeric bounds normalization on Decimal and Float FormElement subclasses.",
  "validation": [
    "Ensure unit tests verify decimal string normalization."
  ],
  "status": "candidate",
  "proposed_by": "agent_alpha",
  "approved_by": null,
  "approved_at": null
}

Development & Testing

Running Tests

To run unit and integration tests for this package:

composer test

Or use the local Makefile:

make test

Static Analysis

To run PHPStan checks on the package:

composer phpstan