fix(sync): improve pre-commit cache handling and enhance lessons structure

.github/CHANGELOG.md

@@ -7,14 +7,15 @@ Use this format for new updates:
 - Include file/path scope when useful.
 
 ## 2026-04-12
+- Renamed the repository-root retained-learning ledger to `LESSONS_LEARNED.md`, then realigned the retained-learning contract, sync automation, and tests to use the new canonical path.
 - Aligned `.pre-commit-config.yaml` and expanded `.editorconfig` with file-type defaults for Python, shell, Terraform/HCL, YAML, JSON/TOML, Markdown, Make, and local config files so the repo and synced consumers get a practical editor baseline without the formatter ping-pong that left `pre-commit` failing with no visible git diff.
 - Expanded the cross-repository sync baseline to include `.editorconfig`, `.pre-commit-config.yaml`, and `.github/workflows/terraform-pre-commit.yml`, then updated the sync agent/skill contract and sync planner tests to keep that scope explicit and narrow.
 - Renamed the workflow skill from `internal-cicd-workflow` to `internal-github-actions`, renamed `internal-github-composite-action` to `internal-github-action-composite`, and realigned the GitHub Actions instructions so the umbrella instruction is the family baseline while the composite instruction now carries only composite-specific delta guidance.
-- Added a retained-learning governance contract: root `AGENTS.md` now defines repository-root `LESSONS.md` as a non-canonical ledger for durable lessons learned during completed tasks, `.github/copilot-instructions.md` projects the same behavior into native Copilot flows, `INTERNAL_CONTRACT.md` source-governs the invariant, and the new `LESSONS.md` file records retained lessons with canonical-owner pointers.
+- Added a retained-learning governance contract: root `AGENTS.md` now defines repository-root `LESSONS_LEARNED.md` as a non-canonical ledger for durable lessons learned during completed tasks, `.github/copilot-instructions.md` projects the same behavior into native Copilot flows, `INTERNAL_CONTRACT.md` source-governs the invariant, and the new `LESSONS_LEARNED.md` file records retained lessons with canonical-owner pointers.
 - Slimmed the retained-learning section in root `AGENTS.md` so the bridge keeps only strategic ownership and boundary language while `.github/copilot-instructions.md` remains the detailed operational projection.
-- Expanded the retained-learning contract so `LESSONS.md` may also keep durable corrections to repeated or consequential misapplication of already-codified repository rules, then recorded the bridge-vs-projection lesson for `AGENTS.md` and `.github/copilot-instructions.md`.
-- Restructured `LESSONS.md` into two tables so new or still-pending lessons stay separate from codified rules.
-- Simplified `LESSONS.md` again so it now keeps only pending lessons; once a lesson is codified into a canonical owner, it is removed from the ledger instead of being duplicated there.
+- Expanded the retained-learning contract so `LESSONS_LEARNED.md` may also keep durable corrections to repeated or consequential misapplication of already-codified repository rules, then recorded the bridge-vs-projection lesson for `AGENTS.md` and `.github/copilot-instructions.md`.
+- Restructured `LESSONS_LEARNED.md` into two tables so new or still-pending lessons stay separate from codified rules.
+- Simplified `LESSONS_LEARNED.md` again so it now keeps only pending lessons; once a lesson is codified into a canonical owner, it is removed from the ledger instead of being duplicated there.
 
 ## 2026-04-11
 - Tightened the Python skill split instead of collapsing it: clarified the shared baseline in `.github/instructions/internal-python.instructions.md`, sharpened `internal-project-python` around structured package and application boundaries, and expanded `internal-script-python` plus its layout reference to cover the repository-aligned toolkit pattern used under `.github/scripts/` with shared `lib/`, hash-locked `requirements.txt`, shared `run.sh`, root-level tests, and thin wrapper entrypoints.

.github/agents/internal-sync-global-copilot-configs-into-repo.agent.md

@@ -1,6 +1,6 @@
 ---
 name: internal-sync-global-copilot-configs-into-repo
-description: Use this agent when aligning a consumer repository to the managed GitHub Copilot baseline from this standards repository, plus the explicitly shared repository-hygiene files declared by the paired sync skill. Keep the paired sync skill as the reusable sync-procedure owner, preserve target `local-*` extensions plus any `.github/local-copilot-overrides.md` layer, and keep root-guidance files aligned to their separate ownership layers.
+description: Use this agent when aligning a consumer repository to the managed GitHub Copilot baseline from this standards repository, plus the explicitly shared repository-hygiene files and retained-learning ledger contract declared by the paired sync skill. Keep the paired sync skill as the reusable sync-procedure owner, preserve target `local-*` extensions plus any `.github/local-copilot-overrides.md` layer, and keep root-guidance files aligned to their separate ownership layers.
 tools: ["read", "edit", "search", "execute", "web", "agent"]
 agents: []
 ---
@@ -42,13 +42,14 @@ Treat this agent plus `.github/skills/internal-agent-sync-global-copilot-configs
 - Start in `plan` by default. Move to `apply` only on explicit request and only when the plan is conflict-safe.
 - Keep target assumptions narrow and let the paired skill own the mirrored-scope and plan-file details.
 - Preserve target `local-*` assets plus any consumer-owned `.github/local-copilot-overrides.md` file, exclude repository-owned `internal-sync-*` resources from mirroring, and keep root-guidance files layered according to the paired skill contract.
+- When repository-root `LESSONS_LEARNED.md` is in scope, ensure the target has it and keep it structurally aligned with the source contract while preserving or migrating target-authored lesson rows through the paired skill workflow.
 - Sync only the managed cross-repository baseline declared by the paired skill contract; do not expand beyond that scope unless the user explicitly asks for more.
 - Do not restate reusable sync procedure in this agent; when the contract drifts, update the paired skill first and then realign this agent.
 
 ## Routing
 
 - Use this agent for consumer-repository baseline propagation, drift assessment, `plan`, and `apply` runs.
-- Use this agent when the target must inherit the current bridge model around `AGENTS.md`, `.github/copilot-instructions.md`, `.github/local-copilot-overrides.md`, and `.github/INVENTORY.md`.
+- Use this agent when the target must inherit the current bridge model around `AGENTS.md`, `.github/copilot-instructions.md`, `.github/local-copilot-overrides.md`, `.github/INVENTORY.md`, and repository-root `LESSONS_LEARNED.md`.
 - Do not use this agent for source-side catalog redesign, agent or skill authoring, or governance restructuring in this repository; recommend `internal-planning-leader` instead.
 - Do not use this agent for routine local execution once the sync contract is already settled and only a small target-local edit remains; recommend the appropriate executor for that repository instead.
 - When current platform behavior is the deciding factor, validate it through `internal-copilot-docs-research` before changing the sync policy.
@@ -62,7 +63,7 @@ Treat this agent plus `.github/skills/internal-agent-sync-global-copilot-configs
 ## Output Expectations
 
 - Target analysis and selected mode
-- Root-guidance alignment strategy
+- Root-guidance alignment strategy and `LESSONS_LEARNED.md` sync status
 - Preserved `local-*` assets, `.github/local-copilot-overrides.md` status, and target-only cleanup decisions
 - Boundary or approval decisions that affected the selected mode
 - Validation results, remaining blockers, and the completion-report sections

.github/copilot-instructions.md

@@ -82,19 +82,19 @@ You are an expert software and platform engineer. Protect correctness, security,
 - Also treat a repeated or consequential misapplication of an already-codified repository rule as a lesson when the correction is likely to prevent the same mistake in future work.
 - When a validator, IDE, schema check, or runtime error overturns an earlier assumption, immediately re-check whether that correction is durable enough to retain or codify.
 - Before finalizing such a correction, read the primary documentation for the relevant platform or schema instead of relying on memory or partial recall.
-- Before editing repository-root `LESSONS.md`, read its current on-disk contents and treat them as the source of truth for in-progress local lessons, including uncommitted rows already present on disk.
-- When a durable lesson is clear and still uncodified, append one concise, reusable row to the pending table in `LESSONS.md` instead of waiting for task completion; do not regenerate, reorder, or rewrite unrelated rows.
+- Before editing repository-root `LESSONS_LEARNED.md`, read its current on-disk contents and treat them as the source of truth for in-progress local lessons, including uncommitted rows already present on disk.
+- When a durable lesson is clear and still uncodified, append one concise, reusable row to the pending table in `LESSONS_LEARNED.md` instead of waiting for task completion; do not regenerate, reorder, or rewrite unrelated rows.
 - If you decide not to record a lesson after such a correction, make that decision explicit in the completion report with a short reason.
-- Treat `LESSONS.md` as a learning ledger, not as canonical policy. Do not dump transient notes, full debugging timelines, sensitive content, or conversational noise into it.
-- Preserve unrelated existing lessons in `LESSONS.md`, including local uncommitted ones already on disk.
+- Treat `LESSONS_LEARNED.md` as a learning ledger, not as canonical policy. Do not dump transient notes, full debugging timelines, sensitive content, or conversational noise into it.
+- Preserve unrelated existing lessons in `LESSONS_LEARNED.md`, including local uncommitted ones already on disk.
 - If a lesson is later disproven, narrowed, deduplicated, or codified elsewhere in the same task, update or remove only that lesson's row before completion.
-- If the same task also codifies the lesson into `AGENTS.md`, this file, a scoped instruction, a skill, or an agent, remove that corresponding row from `LESSONS.md` instead of keeping a codified duplicate there.
-- If no durable lesson emerged, do not force a `LESSONS.md` change.
+- If the same task also codifies the lesson into `AGENTS.md`, this file, a scoped instruction, a skill, or an agent, remove that corresponding row from `LESSONS_LEARNED.md` instead of keeping a codified duplicate there.
+- If no durable lesson emerged, do not force a `LESSONS_LEARNED.md` change.
 
 ## Completion Report
 
 - End completed operations with `✅ Outcome`.
 - When used, also include `🤖 Agents`, `📘 Instructions`, `🧩 Skills`, and `📦 Other Resources`.
 - In each included section, state which resources were used and why they were relevant.
-- When `LESSONS.md` was updated, mention it under `📦 Other Resources` with a short reason.
+- When `LESSONS_LEARNED.md` was updated, mention it under `📦 Other Resources` with a short reason.
 - Omit unused categories instead of adding empty or negative sections.

.github/instructions/internal-github-actions.instructions.md

@@ -27,6 +27,7 @@ applyTo: "**/workflows/**,**/actions/**/action.y*ml"
 - Before making or validating workflow changes that depend on expression scope, context usage, or key-specific rules, read GitHub's official workflow syntax and context-availability documentation; do not rely on memory.
 - Do not place runner-derived paths such as `runner.temp` in workflow-root `env` or `jobs.<job_id>.env`; resolve them in step-level keys that allow `runner`, or derive them from default runner environment variables inside `run`.
 - Treat IDE, parser, `actionlint`, and queue-time errors such as `Unrecognized named-value` as mandatory documentation-check triggers.
+- When debugging workflow logs, identify the first failed step before treating an earlier cache or setup line as the root cause; cache misses are informational unless the action or workflow explicitly makes them fatal.
 - Keep cache keys deterministic from lockfiles, tool versions, or other stable inputs instead of timestamps or branch-only entropy.
 - Set explicit artifact `retention-days` when artifacts bridge review, release, or deploy stages.
 - Validate `workflow_dispatch` free-form inputs before shell, deploy, or infrastructure steps consume them.

.github/scripts/lib/shared.py

@@ -24,8 +24,10 @@
 IGNORED_SYNC_FILENAMES = {"README.md", "CHANGELOG.md"}
 IGNORED_SYNC_PARTS = {"__pycache__", ".venv"}
 CONSUMER_SYNC_EXCLUDED_PREFIX = "internal-sync-"
+LESSONS_PATH = "LESSONS_LEARNED.md"
 MANAGED_ROOT_FILES = (
     "AGENTS.md",
+    LESSONS_PATH,
     ".editorconfig",
     ".pre-commit-config.yaml",
     ".github/copilot-instructions.md",
@@ -86,6 +88,7 @@ class SyncPlan:
     operations: tuple[SyncOperation, ...]
     local_assets: tuple[str, ...]
     generated_inventory: str
+    generated_lessons: str | None = None
     generated_gitignore: str | None = None
 
     def to_dict(self) -> dict[str, object]: