legrab · legrab · Aug 9, 2026 · Aug 9, 2026
@@ -4,6 +4,22 @@
 
 ### Added
 
+### Changed
+
+## 1.1.0
+
+Finalized the post-1.0 learning and reasoning improvements for the 1.1.0 release.
+
+### Added
+
+- `agentic-flow/ARTIFACTS.md`, defining optional reasoning artifacts such as questions, research, models, designs, structures, plans, verification, and learning without making them workflow stages.
+- Focused learning rounds and repository-learning guidance that build understanding incrementally and stop when the evidence threshold is met.
+- Human-correction propagation guidance in `agentic-flow/LOCAL.md`, so corrected models and designs are updated rather than silently discarded.
+- Optional `Structure` guidance inside `structured-change` for designs with real architectural impact.
+- `learning-closure` guidance that prefers changed understanding and recommends the smallest persistence surface.
+- `learning-freshness` guidance for checking durable knowledge against current implementation evidence.
+- Shared research guidance for competing designs so common evidence is established once before branching into tradeoffs.
+- Worked two-round discovery material and corresponding evaluation coverage.
 - Two behavioral routing rules in `agentic-flow/AGENTS.md`: treat a user's proposed implementation or architecture as a hypothesis to check against repository evidence rather than a specification to endorse, and distinguish repository-resolvable ambiguity (inspect first) from user-intent ambiguity (ask the smallest useful question).
 - A compact visual decision model for that routing in `agentic-flow/README.md`.
 - Two regression scenarios (proposed design, open-ended ambiguity) in `docs/AGENTIC_WORKFLOW_SANITY.md`, and matching cases in `skill-evals/agentic-cases.yaml`.
@@ -12,8 +28,18 @@
 
 ### Changed
 
+- Tightened the distinction between learning-aware behavior and turning every task into a lesson.
+- Clarified proposal and ambiguity routing so repository evidence is inspected before asking user-intent questions where possible.
+- Added progressive disclosure around lower-frequency rules, provenance details, and architectural boundaries.
+- Added compact flowcharts to make artifact selection, structured change, routing, layer relationships, and learning closure easier to scan.
+- Reduced repeated framework language and softened rules where context-sensitive wording is more accurate than universal mandates.
 - README wording from "learning is the default behavior" to "learning-aware behavior is enabled by default," with routine work stated explicitly as staying routine.
 
+### Fixed
+
+- Corrected the remaining `AGENTS.md` wording that still described learning as unqualified default behavior.
+- Removed a duplicated `LEARN.md` entry from the agentic-flow guide.
+
 ## 1.0.0
 
 First tagged production release. `v0.1.0`/`v0.1.1` on GitHub were release-automation smoke tests and are not part of this line; this release picks up the version sequence documented below, starting at `0.8.0`.

@@ -1,9 +1,9 @@
 .gitattributes	40
 .gitignore	324
 AGENTS.md	2995
-CHANGELOG.md	18727
+CHANGELOG.md	20650
 docs/AGENTIC_WORKFLOW_SANITY.md	9207
-docs/ARCHITECTURE.md	6009
+docs/ARCHITECTURE.md	5689
 docs/DESIGN_NOTES.md	31120
 docs/EDUCATION_MODEL.md	5452
 docs/INITIALIZE_LEARNING_FLOW.md	10880
@@ -16,7 +16,7 @@ docs/references/REFERENCE_REVIEW_LEARNING_FLOW_ADJUSTMENT.md	9505
 docs/references/REFERENCE_REVIEW_LITT.md	2069
 docs/references/REFERENCE_REVIEW_POCOK.md	2155
 LICENSE	2213
-README.md	9012
+README.md	8888
 sample/common/.agents/skills/agentic-workflow/SKILL.md	2686
 sample/common/.agents/skills/learn-anything/agents/openai.yaml	246
 sample/common/.agents/skills/learn-anything/SKILL.md	1756
@@ -27,21 +27,21 @@ sample/common/.agents/skills/structured-change/knowledge/engineering/documentati
 sample/common/.agents/skills/structured-change/knowledge/engineering/maintainability.md	1319
 sample/common/.agents/skills/structured-change/knowledge/engineering/modernization.md	1254
 sample/common/.agents/skills/structured-change/knowledge/engineering/testing.md	1287
-sample/common/.agents/skills/structured-change/SKILL.md	2599
+sample/common/.agents/skills/structured-change/SKILL.md	2770
 sample/common/.agents/skills/structured-change/templates/design.md	649
 sample/common/.agents/skills/structured-change/templates/exploration.md	368
 sample/common/.agents/skills/structured-change/templates/structure.md	175
 sample/common/agentic-flow/.managed-files	183
 sample/common/agentic-flow/.managed-skills	86
 sample/common/agentic-flow/.template-version	6
-sample/common/agentic-flow/AGENTS.md	5447
-sample/common/agentic-flow/ARTIFACTS.md	2333
+sample/common/agentic-flow/AGENTS.md	5443
+sample/common/agentic-flow/ARTIFACTS.md	2605
 sample/common/agentic-flow/CONFIGURE.md	4475
 sample/common/agentic-flow/DECISIONS.md	963
 sample/common/agentic-flow/EDUCATION.md	5232
 sample/common/agentic-flow/LEARN.md	1822
 sample/common/agentic-flow/LOCAL.md	4179
-sample/common/agentic-flow/README.md	2979
+sample/common/agentic-flow/README.md	3074
 sample/common/agentic-flow/REFERENCE_INTEGRATION.md	2183
 sample/common/agentic-flow/ROOT_INTEGRATION.md	3086
 sample/common/agentic-flow/SETTINGS.md	544
@@ -110,7 +110,7 @@ skill-evals/README.md	1667
 skill-evals/structured-change-cases.yaml	4710
 adoption/ADOPT.md	3941
 adoption/README.md	2057
-sample/common/.agents/skills/learning-closure/SKILL.md	3911
-sample/common/.agents/skills/learning-freshness/SKILL.md	1866
+sample/common/.agents/skills/learning-closure/SKILL.md	3605
+sample/common/.agents/skills/learning-freshness/SKILL.md	1904
 skill-evals/learning-lifecycle-cases.yaml	1599
 skill-evals/adoption-cases.yaml	1337
@@ -7,7 +7,7 @@
 Codebase Learning Flow configures a host coding agent. It provides repository-local instructions, focused skills, learning surfaces, and private local continuity. It does **not** provide an agent runtime, sandbox, retry engine, or background worker.
 
 > [!IMPORTANT]
-> **Learning-aware behavior is enabled by default after installation** — that does not mean every task becomes a lesson. Routine work stays routine. A request such as `help me understand <topic>` automatically selects the appropriate learning route, keeps the exchange conversational, builds a compact model, uses a useful example or experiment, and checks back for understanding when that adds value. A proposed design or approach is treated as a hypothesis worth checking against repository evidence, not a specification to endorse.
+> **Learning-aware behavior is enabled by default after installation**. That does not mean every task becomes a lesson. Routine work stays routine. Requests such as `help me understand <topic>` select the appropriate learning route; implementation work remains normal delivery with learning reinforcement only when useful. Proposed designs are hypotheses to check against repository evidence, not specifications to endorse.
 
 > [!WARNING]
 > The regulatory extension is a reasoning and workflow aid, not a compliance determination or substitute for qualified regulatory or quality expertise.
@@ -46,8 +46,8 @@ The installed `AGENTS.md` connects the host repository to `agentic-flow`. The co
 - `help me understand ...`, `explain ...`, `teach me ...` → `learn-anything` for general topics
 - questions about the current codebase → repository learning
 - implementation work → normal delivery, with learning reinforcement when useful
-- a proposed design or approach → treated as a hypothesis, checked against repository evidence before being endorsed or implemented
-- an open-ended consequential question → repository evidence is inspected first; the user is asked only the smallest question evidence can't answer
+- a proposed design or approach → treated as a hypothesis, checked against repository evidence before endorsement or implementation
+- an open-ended consequential question → repository evidence is inspected first; the user is asked only the smallest question evidence cannot answer
 - one consequential or ambiguous change → `structured-change` alongside the active route
 - regulatory reasoning → the optional regulatory lens when installed
 
@@ -59,19 +59,17 @@ The agent should not turn every task into a lesson. Short questions can receive
 
 ### Preferred: packaged release
 
-For team or enterprise use, install a reviewed, versioned release. Substitute
-the current tag from the badge above or the
-[Releases page](https://github.com/legrab/codebase-learning-flow/releases) —
-`--release`/`-Release` intentionally has no "latest" shortcut, so the exact
-tag must be given.
+For team or enterprise use, install a reviewed, versioned release. Substitute the current tag from the badge above or the [Releases page](https://github.com/legrab/codebase-learning-flow/releases).
+
+`--release`/`-Release` intentionally has no `latest` shortcut, so the exact tag must be given.
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.sh -o install.sh
-sh install.sh --release v1.0.0 --profile minimal
+sh install.sh --release v1.1.0 --profile minimal
 ```
 
 ```powershell
-& ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1))) -Release v1.0.0 -Profile Minimal
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1))) -Release v1.1.0 -Profile Minimal
 ```
 
 The installer verifies the release checksum before extraction and reports the resolved `Version:` and `Source:`.
@@ -147,7 +145,7 @@ The model is selective:
 <details>
 <summary>Ownership lens</summary>
 
-When relevant, consider:
+When relevant:
 
 | Question | Why |
 |---|---|

@@ -1,7 +1,6 @@
 # Framework architecture
 
-Codebase Learning Flow is organized as three layers with different ownership and
-adoption boundaries.
+Codebase Learning Flow is organized as three layers with different ownership and adoption boundaries.
 
 ```text
 Codebase Learning Flow
@@ -18,32 +17,23 @@ Codebase Learning Flow
 
 ## 1. Agentic Delivery
 
-The agentic delivery layer is the common collaboration layer. It defines the
-default engineering loop, instruction precedence, planning and verification
-behavior, communication, handoff, and boundaries around consequential actions.
+The agentic delivery layer is the common collaboration layer. It defines the default engineering loop, instruction precedence, planning and verification behavior, communication, handoff, and boundaries around consequential actions.
 
 Its main installed surface is `agentic-flow/`.
 
-This layer should remain small because it is the most invasive layer: its
-instructions influence ordinary coding-agent behavior.
-
-It must not absorb repository-specific architecture rules or task-specific
-procedures that belong elsewhere.
+This layer should remain small because it is the most invasive layer: its instructions influence ordinary coding-agent behavior. Repository-specific architecture rules and task-specific procedures belong elsewhere.
 
 The default engineering loop is:
 
 ```text
 Frame → Inspect → Decide → Act → Verify → Handoff
 ```
 
-The loop is task-scaled. A trivial edit should not acquire a formal learning or
-change-management ceremony merely because the framework supports those things.
+The loop is task-scaled. A trivial edit should not acquire a formal learning or change-management ceremony merely because the framework supports those things.
 
 ## 2. Learning & Ownership
 
-The learning and ownership layer helps a developer understand the system while
-doing real engineering work and retain useful knowledge without turning every
-task into documentation.
+The learning and ownership layer helps a developer understand the system while doing real engineering work and retain useful knowledge without turning every task into documentation.
 
 Its surfaces include:
 
@@ -56,20 +46,15 @@ Its surfaces include:
 
 This layer is independently adoptable into an existing agentic workflow.
 
-Conversation remains the default learning surface. Private continuity is used
-only when meaningful persistence is justified. Shared knowledge is promoted
-deliberately and should be stable, verified, reusable, and non-sensitive.
+Conversation remains the default learning surface. Private continuity is used only when meaningful persistence is justified. Shared knowledge is promoted deliberately and should be stable, verified, reusable, and non-sensitive.
 
-The learning layer must not become a second engineering workflow or silently
-introduce universal execution gates.
+The learning layer should not become a second engineering workflow or silently introduce universal execution gates.
 
 ## 3. Optional Risk Lenses
 
-Risk lenses add domain-specific reasoning to the active workflow without
-replacing it.
+Risk lenses add domain-specific reasoning to the active workflow without replacing it.
 
-The current example is the `regulatory` extension and its
-`regulatory-knowledge` skill.
+The current example is the `regulatory` extension and its `regulatory-knowledge` skill.
 
 A risk lens may strengthen questions around:
 
@@ -82,84 +67,68 @@ A risk lens may strengthen questions around:
 - security;
 - professional responsibility.
 
-Risk lenses are selective. They must not be activated merely because a
-repository happens to contain a regulated or safety-relevant component.
+Risk lenses are selective. They should be activated when the work actually benefits from the lens, not merely because a repository contains a regulated or safety-relevant component.
 
-For a consequential change, a risk lens can work with `structured-change`.
-It does not create a parallel workflow.
+For a consequential change, a risk lens can work with `structured-change`. It does not create a parallel workflow.
 
 > [!WARNING]
-> The regulatory extension is a reasoning and workflow aid, not a compliance
-> determination or substitute for qualified regulatory/quality expertise.
+> The regulatory extension is a reasoning and workflow aid, not a compliance determination or substitute for qualified regulatory/quality expertise.
 
 ## Layer relationships
 
-The layers compose downward without requiring all three to be installed:
-
-```text
-Agentic Delivery
-      │
-      ├── may use ──► Learning & Ownership
-      │
-      └── may use ──► Optional Risk Lenses
-                         │
-                         └── may elaborate the active workflow
+```mermaid
+flowchart TB
+    D[Agentic Delivery] --> L[Learning & Ownership]
+    D --> R[Optional Risk Lenses]
+    L --> K[Private or durable knowledge]
+    R --> C[Risk-aware reasoning]
 ```
 
 A repository may therefore choose:
 
 - **Agentic Delivery only** for a minimal coding-agent setup;
-- **Agentic Delivery + Learning & Ownership** for the normal learning-oriented
-  setup;
-- **Agentic Delivery + Risk Lenses** when a specific domain requires stronger
-  reasoning;
+- **Agentic Delivery + Learning & Ownership** for the normal learning-oriented setup;
+- **Agentic Delivery + Risk Lenses** when a specific domain requires stronger reasoning;
 - **all three** when both learning and risk-aware engineering are useful.
 
-Existing custom agentic workflows may also adopt Layer 2 or Layer 3 without
-adopting the framework's common Layer 1. This distinction is important for
-guided adoption.
+Existing custom agentic workflows may also adopt Layer 2 or Layer 3 without adopting the framework's common Layer 1. This distinction matters for guided adoption.
 
-## Ownership boundaries
+<details>
+<summary>Ownership boundaries</summary>
 
-| Layer | Owns | Must not become |
+| Layer | Owns | Avoid turning it into |
 |---|---|---|
 | Agentic Delivery | common collaboration policy, task routing, verification, handoff | repository-specific architecture documentation or every task's learning procedure |
 | Learning & Ownership | learning routes, durable understanding, private continuity, knowledge promotion | a mandatory lesson plan or universal execution gate |
 | Optional Risk Lenses | domain-specific risk and evidence guidance | a claim of compliance, certification, or mandatory procedure for unrelated work |
 
-The repository itself is the reference implementation of these boundaries.
-Changes should preserve the distinction rather than introduce a fourth
-cross-cutting framework layer for every new concern.
+The repository itself is the reference implementation of these boundaries. Changes should preserve the distinction rather than introduce a new cross-cutting framework layer for every concern.
 
+</details>
 
-## Adoption versus installation
+<details>
+<summary>Adoption versus installation</summary>
 
-The repository deliberately separates complete installation from guided adoption.
+- **Complete installation** consumes the framework payload under `sample/` and establishes the selected layers.
+- **Guided adoption** consumes `adoption/` and adapts selected concepts into an existing agentic setup. It must not silently replace the host delivery workflow or root `AGENTS.md`.
 
-- **Complete installation** consumes the framework payload under `sample/` and
-  establishes the selected Agentic Delivery, Learning & Ownership, and optional
-  Risk Lens layers.
-- **Guided adoption** consumes `adoption/` and adapts selected concepts into an
-  existing agentic setup. It is not an installer profile and must not silently
-  replace the host delivery workflow or root `AGENTS.md`.
+This separation is a trust and context boundary as well as an installation boundary.
 
-This separation is a trust and context boundary as well as an installation
-boundary. The adoption process can inspect the framework without loading its
-entire instruction set into the active agent context.
+</details>
 
 ## Learning lifecycle
 
 Learning is treated as a lifecycle rather than a second engineering process:
 
-```text
-work → observe useful insight → recommend destination → user decides
-     → private continuity or durable shared knowledge → later freshness check
+```mermaid
+flowchart LR
+    W[Work] --> O[Observe useful insight]
+    O --> R[Recommend smallest destination]
+    R --> U[User decides]
+    U --> P[Private or durable knowledge]
+    P --> F[Later freshness check]
 ```
 
-`learning-closure` owns the placement decision at meaningful workflow closure.
-`learning-freshness` periodically checks internal documentation and learning
-claims against implementation evidence. External-source claims remain externally
-sourced and carry provenance for later revalidation.
+`learning-closure` owns the placement decision at meaningful workflow closure. `learning-freshness` periodically checks internal documentation and learning claims against implementation evidence. External-source claims remain externally sourced and carry provenance for later revalidation.
 
-The default is not to persist anything. Durable knowledge must earn its
-maintenance cost.
+The default is not to persist anything. Durable knowledge must earn its maintenance cost.