ALP

ALP stands for Agent Learning Pipeline. Nova uses ALP to move from observed website work to reviewed, explainable, and revalidatable knowledge.

ALP sits between live observations and PKS. It looks for repeated evidence, proposes learning opportunities, writes candidates, checks promotion gates, records feedback, and revalidates stored knowledge against a current page.

The important boundary is simple: repeated behavior is not automatically reliable knowledge. ALP separates a useful signal from an executable orientation by making the evidence state explicit.

ALP also supports Learn Mode. When an agent maps a platform, Nova can require a structured playbook and coverage floors before the learning task is treated as complete.

In short

• ALP is Nova’s quality path for learning from repeated website work.
• Suggestions and proposals are evidence, not permission to act.
• Generated candidates can start as review knowledge and only become active after promotion gates pass.
• Active PKS knowledge still needs current-page confirmation before it can guide action.
• Revalidation checks whether stored signals still fit without executing the stored playbook.
• Learn Mode adds coverage floors and a fixed platform-playbook deliverable for exploration tasks.

What ALP decides

ALP is a review loop. It decides whether observed work is only noise, a learning opportunity, a candidate, active guidance, or stale knowledge that needs repair.

1. Pattern Is the same website situation, selector behavior, blocker, or successful action recurring often enough to deserve attention?
2. Proposal Can the evidence become a structured PKS candidate, domain hint, or patch without guessing unsupported selectors or outcomes?
3. Promotion Does the candidate have enough support, success evidence, confidence, and low drift to move from candidate to shadow or active knowledge?
4. Regression Has active knowledge started failing, drifting, or disappearing often enough to be demoted, deprecated, or revalidated before use?
5. Coverage Has a Learn Mode task explored enough surfaces and interactions to produce a useful platform playbook instead of a shallow tour?

When this matters

ALP matters when Nova should leave useful knowledge behind: platform mapping, repeated automation work, consent or login friction, selector repair, recurring blockers, or any task where future agents should understand why a pattern is reliable instead of rediscovering it from scratch.

Knowledge model for agents

For an agent, ALP answers four questions: what evidence exists, what maturity state it has, what gate is blocking or approving it, and what feedback must be written after use or rejection?

Observation cluster

A repeated pattern of website events, such as successful dismissals, selector failures, drift signals, or action outcomes grouped by domain context.

Learning opportunity

A ranked signal returned in opportunities[] when ALP sees a pattern worth reviewing.

Proposal

A generated candidate item returned in proposals[]. It can describe a new phenomenon, a domain hint, or a patch to existing knowledge.

Stable ID

A durable identifier such as stableId used for promotion, explanation, feedback, and revalidation.

Learning level

The maturity state of PKS knowledge: candidate, shadow, active, demoted, deprecated, or revived into review.

Gate

A deterministic check behind nova.learn_promote or nova.explain. Gates compare support, success, failure, drift, sessions, and confidence.

Semantic opportunity

A runtime prompt in pksSemanticLearning for richer patterns such as consent dialogs, login walls, or risky repeats.

Learn Mode coverage

The exploration counters in learnMode.progress that prevent a platform-learning task from ending too early.

How agents use ALP information

ALP gives agents a learning route, not a shortcut. The agent reads evidence, generates or reviews candidates, promotes only through gates, and treats active knowledge as orientation that still needs current-page proof.

1. Start Learn Mode when mapping a platform For exploration tasks, the agent calls nova.get_instructions with mode="learn". The expected final artifact is PLATFORM_PLAYBOOK, and learnMode.progress tells whether coverage floors are met.
2. Read learning opportunities The agent calls nova.learn_suggest with optional scope and limit. The response ranks patterns by support, success, failure, recency, and drift signals.
3. Generate candidates only for an open scope When an opportunity is worth preserving, nova.learn_generate turns evidence into proposals[] and staged PKS candidates. A write needs a concrete domain scope that is open in a current tab or sandbox.
4. Explain before promotion Before relying on a candidate, the agent can call nova.explain with stableId and optional observedSignals to see gate status and match confidence.
5. Promote, demote, or deprecate through gates The agent uses nova.learn_promote. dryRun=true evaluates without writing; a non-dry-run call applies only approved transitions and reports approved, rejected, applied and writeFailed.
6. Resolve semantic prompts explicitly When a tool response includes pksSemanticLearning, the agent either writes the suggested PKS entry or calls nova.learn_resolve_opportunity with a clear verdict.
7. Revalidate before trusting stale knowledge The agent calls nova.revalidate with targetId to check stale fingerprints without executing playbooks. The response reports results[], telemetry status, remaining budget, and denial reasons.
8. Read feedback after changes The agent uses nova.learn_feedback to inspect recent learning events and understand what changed, when, and why.

When ALP state applies

ALP state is about knowledge maturity. It can explain whether a pattern is promising, usable, blocked, stale, or retired, but it does not replace current-page observation or safety approval.

Failure and guard conditions

These are the hard edges an agent or integration should expect from ALP tools.

Agent interpretation example

The example shows ALP as a promotion contract: the agent asks for a dry-run promotion, reads the gate decision, and only writes later if the review is correct.

Promotion dry-run request

{
  "tool": "nova.learn_promote",
  "arguments": {
    "scope": "example.com",
    "stableIds": ["lcj_8c1a2f9d44ab"],
    "transition": "l1_to_l2",
    "dryRun": true
  }
}

Relevant response fields

{
  "structuredContent": {
    "ok": true,
    "scope": "example.com",
    "dryRun": true,
    "approved": 1,
    "rejected": 0,
    "applied": 0,
    "writeFailed": 0,
    "total": 1,
    "decisions": [
      {
        "stableId": "lcj_8c1a2f9d44ab",
        "approved": true,
        "applied": false,
        "skippedBecause": "dry_run",
        "reasonKind": "l1_to_l2",
        "fromLevel": 1,
        "toLevel": 2
      }
    ]
  }
}

Agent interpretation

{
  "treatAs": "gate-approved review signal",
  "writeStatus": "not applied because dryRun=true",
  "beforeUse": "confirm the current page still matches the phenomenon",
  "nextStep": "run non-dry-run only if the scope is open and the promotion is intended"
}

MCP contract

This is the deterministic layer below the explanation. It lists ALP fields that agents and integrators should treat as contract signals rather than free prose.

Execution rule: No ALP field may trigger action by itself; learned guidance needs current-page confirmation and the normal safety gates.