legrab · legrab · Aug 9, 2026 · Aug 9, 2026
@@ -25,6 +25,8 @@ Finalized the post-1.0 learning and reasoning improvements for the 1.1.0 release
 - Two regression scenarios (proposed design, open-ended ambiguity) in `docs/AGENTIC_WORKFLOW_SANITY.md`, and matching cases in `skill-evals/agentic-cases.yaml`.
 - `docs/EXAMPLE_WALKTHROUGH.md`, a single compact worked example showing the new routing in practice.
 - A "v1.0 hardening: proposal and ambiguity routing" entry in `docs/DESIGN_NOTES.md` recording the tightened, applied 1.0 behavioral contract in place — change rationale and current-state tracking live only in `DESIGN_NOTES.md` and this changelog, not in a separate status document.
+- A canonical `agentic-flow/AGENTS.md` "Output shape" rule: prefer a compact Mermaid flowchart over prose for flows and relationships, and keep verbose agent-only elaboration inside `<details>` sections rather than the surrounding prose.
+- A compact adoption-flow diagram in `adoption/ADOPT.md`.
 
 ### Changed
 
@@ -34,11 +36,16 @@ Finalized the post-1.0 learning and reasoning improvements for the 1.1.0 release
 - 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.
+- Added missing `<details>` collapsibles to the `structure`, `challenge-debugging`, `change-explainer`, and `ticket-learning-path` templates for consistency with `exploration.md`/`design.md`.
+- Collapsed `docs/DESIGN_NOTES.md`'s v0.5–v0.8.0 history into one section so the current architecture and most recent rationale read first.
 
 ### 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.
+- Removed a redundant "Current architecture boundaries" section in `docs/README.md` that restated the layer table already given earlier in the same file.
+- Removed the skill-routing table duplicated between `sample/profiles/full/learning-flow/AGENTS.md` and `README.md`; the profile README now points to the canonical table.
+- Matched the packaged-release install examples in `scripts/README.md` to the current `v1.1.0` tag referenced in the root README.
 
 ## 1.0.0
 

@@ -1,13 +1,13 @@
 .gitattributes	40
 .gitignore	324
 AGENTS.md	2995
-CHANGELOG.md	20650
+CHANGELOG.md	21735
 docs/AGENTIC_WORKFLOW_SANITY.md	9207
 docs/ARCHITECTURE.md	5689
-docs/DESIGN_NOTES.md	31120
+docs/DESIGN_NOTES.md	31204
 docs/EDUCATION_MODEL.md	5452
 docs/INITIALIZE_LEARNING_FLOW.md	10880
-docs/README.md	4320
+docs/README.md	4016
 docs/references/REFERENCE_INTEGRATION.md	4551
 docs/references/REFERENCE_REVIEW_AWESOME_AGENT_SKILLS.md	2317
 docs/references/REFERENCE_REVIEW_BEST_OF_AGENT_HARNESSES.md	2540
@@ -30,18 +30,18 @@ sample/common/.agents/skills/structured-change/knowledge/engineering/testing.md
 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/.agents/skills/structured-change/templates/structure.md	243
 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	5443
+sample/common/agentic-flow/AGENTS.md	5961
 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	3074
+sample/common/agentic-flow/README.md	2969
 sample/common/agentic-flow/REFERENCE_INTEGRATION.md	2183
 sample/common/agentic-flow/ROOT_INTEGRATION.md	3086
 sample/common/agentic-flow/SETTINGS.md	544
@@ -66,14 +66,14 @@ sample/extensions/regulatory/learning-flow/.extension-name	11
 sample/extensions/regulatory/learning-flow/REGULATORY.md	1882
 sample/profiles/full/.agents/skills/analogous-feature/SKILL.md	1408
 sample/profiles/full/.agents/skills/challenge-debugging/SKILL.md	1426
-sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md	428
+sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md	511
 sample/profiles/full/.agents/skills/change-explainer/SKILL.md	1308
-sample/profiles/full/.agents/skills/change-explainer/templates/change-explainer.md	290
+sample/profiles/full/.agents/skills/change-explainer/templates/change-explainer.md	353
 sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md	1522
 sample/profiles/full/.agents/skills/repository-orientation/SKILL.md	1222
 sample/profiles/full/.agents/skills/safe-refactor/SKILL.md	1373
 sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md	1519
-sample/profiles/full/.agents/skills/ticket-learning-path/templates/ticket-learning-path.md	348
+sample/profiles/full/.agents/skills/ticket-learning-path/templates/ticket-learning-path.md	405
 sample/profiles/full/learning-flow/.managed-files	137
 sample/profiles/full/learning-flow/.managed-skills	132
 sample/profiles/full/learning-flow/.template-profile	5
@@ -82,7 +82,7 @@ sample/profiles/full/learning-flow/AGENTS.md	4716
 sample/profiles/full/learning-flow/BOOTSTRAP.md	1788
 sample/profiles/full/learning-flow/MAP.md	1464
 sample/profiles/full/learning-flow/PLAYBOOKS.md	1327
-sample/profiles/full/learning-flow/README.md	2955
+sample/profiles/full/learning-flow/README.md	2574
 sample/profiles/full/learning-flow/REPOSITORIES.md	439
 sample/profiles/full/learning-flow/TAKEAWAYS.md	970
 sample/profiles/full/learning-flow/UNDERSTANDING_CHECKS.md	2010
@@ -108,7 +108,7 @@ skill-evals/full-cases.yaml	4640
 skill-evals/minimal-cases.yaml	3655
 skill-evals/README.md	1667
 skill-evals/structured-change-cases.yaml	4710
-adoption/ADOPT.md	3941
+adoption/ADOPT.md	4177
 adoption/README.md	2057
 sample/common/.agents/skills/learning-closure/SKILL.md	3605
 sample/common/.agents/skills/learning-freshness/SKILL.md	1904

@@ -3,6 +3,17 @@
 Use this document only for **guided adoption into an existing custom agentic
 setup**. It is deliberately separate from the complete installation payload.
 
+```mermaid
+flowchart LR
+    I[Inspect] --> L[Explain the layers]
+    L --> Q[Ask concrete choices]
+    Q --> P[Build adoption plan]
+    P --> A[Approve]
+    A --> G[Integrate selectively]
+    G --> V[Verify]
+    V --> S[Summarize]
+```
+
 ## 1. Inspect before proposing
 
 Inspect only enough of the target repository to understand:

@@ -18,6 +18,9 @@ The previous five ownership layers remain useful as implementation provenance, b
 
 This distinction is important for adoption. A repository with its own agentic delivery workflow can adopt Learning & Ownership or an Optional Risk Lens without installing or replacing the common Agentic Delivery layer.
 
+<details>
+<summary>Earlier version history (v0.5 – v0.8.0)</summary>
+
 ## v0.5 separation of concerns
 
 Repository agentic content is divided into five ownership layers:
@@ -138,6 +141,8 @@ Regulatory-specific knowledge (traceability, validation, risk management, audit
 
 Engineering judgment content the source proposed (anti-overengineering guidance, AI-collaboration indicators, modernization, maintainability, testing, architecture, dependency management, documentation) is general-purpose, not regulatory-specific, and lives inside `structured-change`'s own knowledge folder instead.
 
+</details>
+
 ## v1.0 hardening: proposal and ambiguity routing
 
 A pre-1.0 sanity review found the remaining gap to be behavioral routing, not architecture. The framework already had strong repository discovery, progressive learning, evidence-based reasoning, structured change, and local/shared learning continuity; what it lacked was an explicit rule distinguishing a request to implement from a request to challenge a proposed approach, and an explicit rule distinguishing an ambiguity the repository can resolve from one only the user can resolve. Without those, a proposal offered together with a task could be interpreted as a request to execute rather than a request to challenge, and an open-ended consequential question ("what's the best way to redesign X?") had no rule stopping the agent from silently picking an interpretation.

@@ -81,21 +81,10 @@ Use [`AGENTIC_WORKFLOW_SANITY.md`](AGENTIC_WORKFLOW_SANITY.md) when changing com
    should remain useful before any agent-facing detail is read.
 
 
-## Current architecture boundaries
-
-The framework is organized into three layers:
-
-1. Agentic Delivery;
-2. Learning & Ownership;
-3. Optional Risk Lenses.
-
-Complete installation uses the payload under `sample/`. Guided adoption uses the
-separate `adoption/` surface and integrates only selected concepts into an
-existing agentic workflow.
+## Learning closure and freshness
 
 Meaningful workflow closure can invoke `learning-closure` to decide whether a
 useful insight belongs in private continuity, a learning-flow surface, or
-module
-documentation. `learning-freshness` provides a periodic internal consistency
-check; external-source claims require retained provenance and external
-revalidation.
+module documentation. `learning-freshness` provides a periodic internal
+consistency check; external-source claims require retained provenance and
+external revalidation.
@@ -10,3 +10,8 @@
 1.
 
 ## Seams that must stay separate
+
+<details>
+<summary>Detailed dependency notes</summary>
+
+</details>
@@ -95,6 +95,10 @@ This is a routing rule, not a fixed sequence: new evidence can change the route
 - Keep temporary state out of stable instructions.
 - Use `.local/` for meaningful private learning continuity.
 
+## Output shape
+
+This applies to learning content, design artifacts, and handoffs alike: prefer a compact Mermaid flowchart over prose when explaining a flow, sequence, boundary, or set of relationships. Put verbose, agent-only elaboration — exact code excerpts, exhaustive rationale, long inventories — inside collapsible `<details>` sections. A short line above the block may say what it contains, but that line must stay factual; it is not a second abstraction that can drift from or contradict what's inside.
+
 ## Handoff
 
 End substantial work with only useful sections:

@@ -62,8 +62,7 @@ New evidence can change the route mid-task. This is a set of behavioral rules, n
 | `ROOT_INTEGRATION.md` | connecting existing or missing root instructions |
 | `REFERENCE_INTEGRATION.md` | extracting value from another source |
 | `ARTIFACTS.md` | optional vocabulary for explicit reasoning outputs |
-| `LEARN.md` + learning skills | understanding the effective harness and building knowledge |
-| `learn-anything` + learning skills | general learning and repository understanding |
+| `learn-anything` | general-topic learning without repository inspection |
 
 <details>
 <summary>Boundary in one sentence</summary>

@@ -21,3 +21,8 @@ _Use at most one when consequential._
 ## Promotion decision
 
 _Keep conversational, update map/takeaways, or create a durable repository artifact. State why._
+
+<details>
+<summary>Detailed evidence and reproduction steps</summary>
+
+</details>
@@ -19,3 +19,8 @@
 - **Model:**
 - **Evidence:**
 - **Boundary:**
+
+<details>
+<summary>Detailed walkthrough</summary>
+
+</details>
@@ -19,3 +19,8 @@
 _Stop at preparation unless implementation was requested. Name one execution skill if needed._
 
 ## Ticket-local detail not to promote
+
+<details>
+<summary>Detailed notes</summary>
+
+</details>
@@ -35,22 +35,7 @@ All skills apply `agentic-flow/EDUCATION.md` selectively. The goal is durable hu
 
 Use `learning-bootstrap` only for a requested baseline or deliberate onboarding pass. An ordinary task in a new repository can start with its matching task skill.
 
-Select one primary learning skill. `agentic-workflow` is only for configuring or understanding the harness itself.
-
-<details>
-<summary>Skill routes</summary>
-
-| Need | Skill |
-|---|---|
-| compact baseline | `learning-bootstrap` |
-| architecture or domain orientation | `repository-orientation` |
-| bug or failing behavior | `challenge-debugging` |
-| feature based on existing behavior | `analogous-feature` |
-| behavior-preserving structural change | `safe-refactor` |
-| non-trivial diff or generated change | `change-explainer` |
-| context before implementation | `ticket-learning-path` |
-
-</details>
+Select one primary learning skill. `agentic-workflow` is only for configuring or understanding the harness itself. See the "Select one primary skill" table in `learning-flow/AGENTS.md` for the full need-to-skill routing.
 
 ## Understanding and assessment
 

@@ -32,11 +32,11 @@ flowchart LR
 ```
 
 ```text
-sh install.sh --release v1.0.0 --profile minimal
+sh install.sh --release v1.1.0 --profile minimal
 ```
 
 ```powershell
-.\install.ps1 -Release v1.0.0 -Profile Minimal
+.\install.ps1 -Release v1.1.0 -Profile Minimal
 ```
 
 `--release`/`-Release` downloads the packaged artifact and `checksums.txt`
@@ -54,7 +54,7 @@ Every install prints which trust boundary it used:
 
 ```text
 Codebase Learning Flow
-Version: v1.0.0
+Version: v1.1.0
 Source: packaged release (checksum verified)
 ```