feat(agent): add a portable learning-capture gate

[ss-o]

Problem

Non-trivial agent sessions can discover reusable decisions, failures, patterns,
and workflow improvements, but the current policy does not provide a consistent
classification step before completion. Valuable findings can remain in chat,
while indiscriminate automatic capture would create noise and competing sources
of truth.

Proposed outcome

• require a lightweight learning and reuse review before non-trivial work is
  claimed complete
• keep the mandatory rule in AGENTS.md
• place detailed classification and destination rules in one canonical runbook
• provide an advisory reusable skill through progressive disclosure
• preserve explicit consent for private memory
• keep hooks optional and non-writing
• evaluate the workflow after 30 non-trivial tasks or four weeks, whichever
  occurs first

Acceptance criteria

• every supported runtime receives the mandatory rule without depending on a
  hook or skill
• No durable learning is a valid silent result
• useful candidates are routed to existing canonical owners
• no central append-only learning log is created
• no hook automatically writes memory, policy, issues, or documentation
• public and private instruction validators pass

[ss-o]

Agent handoff

Status: In progress
Repository: z-shell/.github
Branch/PR: codex/learning-capture-gate
Tracker/Issue: Linear ZSH-29

Current state

• Isolated implementation branch is based on verified origin/main commit 58b6ff6b4f23c57e18dea9c704fb023ed95f1458.
• GitHub feat(agent): add a portable learning-capture gate #482 remains the implementation and acceptance source of truth.
• ZSH-29 is the coordination and pilot mirror.

Verification

• python3 -m unittest scripts/test_validate_agent_policy.py -v: 68 tests passed.
• python3 scripts/validate-agent-policy.py: passed.
• git diff --check: passed.

Blockers

• None.

Next steps

1. Add the public learning-capture policy, runbook, skill, and manifest routing.
2. Verify the advisory skill with fresh-context pressure scenarios.
3. Mirror the reviewed public contract into the private workspace under the approved boundary.

[ss-o]

Instruction impact review

1. Classification: shared mandatory policy plus canonical runbook detail and one optional advisory skill.
2. Consumers: Codex, Claude Code, Copilot, Gemini CLI, and humans receive the baseline and runbook; Copilot directly discovers the public skill.
3. Canonical owners: AGENTS.md owns the mandatory gate, runbooks/learning-capture.md owns workflow detail, and the skill remains advisory.
4. Duplication: no competing learning log or memory owner is introduced.
5. Manifests: the public manifest adds the runbook and skill; the private manifest later adds routing and byte-identical runtime mirrors.
6. Portability: every runtime receives the mandatory rule without relying on the skill or a hook. The public skill contains no private workspace path.
7. Validation: the focused manifest test passes; all 69 public tests pass; the public validator, Trunk checks, and git diff --check pass.

Skill behavior evidence

Five baseline fresh-context scenarios consistently left reusable findings only in transient completion text, and one suggested an unauthorized scope expansion. Five post-skill scenarios correctly selected Candidate identified, proposed the smallest existing owner, preserved authority boundaries, and stated that uncaptured findings were not durable. One intermediate scenario imported unrelated workspace evidence; the skill and runbook were tightened to scope evidence to the reviewed task, and the rerun passed.

[ss-o]

Pilot

Start: 2026-07-26
Stop: after 30 non-trivial tasks or on 2026-08-23, whichever occurs first
Operational tasks reviewed: 1

Current counts

• Silent No durable learning outcomes: 0
• Candidates proposed: 1
• Candidates promoted into an existing owner: 1
• Candidates rejected: 0
• Repeated investigations observed: 0
• Later reuse observations: 0
• Stale or contradictory artifacts introduced: 0
• Review omissions: 0 of 1
• False-reminder observations: 0
• Median review overhead: not yet meaningful after one task

Runtime discovery baseline

• Codex: verified through fresh normal task discovery; memory consent and authority boundaries were reported correctly.

• GitHub Copilot CLI: verified through direct repository-skill discovery with tools disabled.

• Claude Code: unverified; the tool-disabled discovery run exceeded its strict USD 0.10 budget before returning.

• Gemini CLI: deprecated and out of scope. No discovery check or new integration is required.

• count reviewed non-trivial tasks

• count silent No durable learning outcomes

• count candidates proposed

• count candidates promoted

• count candidates rejected or merged into existing owners

• record repeated investigations that still occurred

• record later tasks that reused a promoted item

• estimate median review overhead

• identify stale or contradictory artifacts introduced

• calculate review omission rate

• calculate false-reminder rate

Do not add a Codex command hook unless the review omission rate exceeds
10 percent and a prototype keeps false reminders below 10 percent without
parsing an unstable transcript format.

No automatic memory, issue, ADR, runbook, instruction, skill, or documentation write path was added. The Claude stop reminder remains optional, advisory, and non-writing.

[ss-o]

Implementation phase handoff

The portable learning-capture gate is implemented and verified locally. The measurement pilot remains open.

Public implementation

• Local commit: 4d70f5b07880f1f5491174a3ec2e3f3c2ecf78a3
• 69 policy tests passed.
• The public policy validator passed.
• Trunk reported no issues in the six changed public files.
• No branch was pushed and no pull request was opened.

Private delivery

• The Codex and Claude skill mirrors are byte-identical to the public skill.
• The generated instruction composite is current.
• 75 private contract tests passed.
• Trunk reported no issues in the final status change.
• Private delivery remains local and unpushed.

Runtime discovery

• Codex: verified in a fresh task. The skill was discovered normally and summarized the intended triggers, silent No durable learning outcome, owner routing, and memory-consent boundary.
• GitHub Copilot CLI: verified against the public repository with tools disabled. It discovered the repository skill and its runbook contract.
• Claude Code: unverified. The bounded check exceeded its USD 0.10 budget, so no success is claimed and the runtime status remains unverified.
• Gemini CLI: deprecated and out of scope. No discovery check or new integration is required.

Safety boundaries

• No automatic memory write was added.
• No automatic issue, ADR, runbook, instruction, or skill write was added.
• No Codex hook was added.
• The existing Claude reminder remains advisory and non-writing.

Learning review

Three findings were promoted directly into their canonical owners during implementation: one public source may feed multiple runtime-specific private mirrors while destinations remain unique; ignored runtime skill directories need a narrow allowlist for durable project skills; and skill pressure tests must exclude unrelated workspace evidence from candidate classification.

Keep this issue open until the pilot reaches 30 reviewed non-trivial tasks or 2026-08-23, whichever occurs first.

[ss-o]

Follow-up instruction impact review

1. Classification: private shared mandatory policy for completed-task response behavior.
2. Consumers: active private Codex, Claude Code, Copilot, and human contexts receive the rule. The existing Gemini compatibility adapter is retained for legacy compatibility, but Gemini CLI is deprecated and is not an active verification or integration target.
3. Canonical owner: workspace/agent-policy/private-overlay.md remains the correct private owner.
4. Duplication: the private memory note is a preference cache, not a policy owner. No hook, skill, or public policy duplicates the mandatory rule.
5. Manifests: no route or inventory change is required because the existing private-overlay generation route already covers the rule.
6. Portable delivery: generated AGENTS.md delivers the rule without relying on an optional hook or skill. Import-only adapters remain unchanged.
7. Validation: the focused test completed a RED/GREEN cycle; all 76 private tests pass; generated output is current at 17,648 bytes; scoped diff and adapter checks pass; Trunk reports no issues in the four scoped files.

No public policy, Gemini compatibility surface, hook, or automatic external-write path was added or removed.