Unsupervisedcom
diff --git a/‎.claude/settings.json‎
Lines changed: 4 additions & 2 deletions b/‎.claude/settings.json‎
Lines changed: 4 additions & 2 deletions
diff --git a/‎.deepschema.CHANGELOG.md.yml‎
Lines changed: 6 additions & 0 deletions b/‎.deepschema.CHANGELOG.md.yml‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎CHANGELOG.md‎
Lines changed: 6 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎doc/learning_agents_architecture.md‎
Lines changed: 18 additions & 7 deletions b/‎doc/learning_agents_architecture.md‎
Lines changed: 18 additions & 7 deletions
diff --git a/‎learning_agents/skills/create-agent/.deepschema.SKILL.md.yml‎
Lines changed: 67 additions & 0 deletions b/‎learning_agents/skills/create-agent/.deepschema.SKILL.md.yml‎
Lines changed: 67 additions & 0 deletions
diff --git a/‎learning_agents/skills/identify/.deepschema.SKILL.md.yml‎
Lines changed: 105 additions & 0 deletions b/‎learning_agents/skills/identify/.deepschema.SKILL.md.yml‎
Lines changed: 105 additions & 0 deletions
@@ -100,8 +100,10 @@
       "Write(./.deepwork/**)",
       "Bash(deepwork:*)",
       "Bash(gh pr edit:*)",
-      "Bash(learning_agents/scripts/*)",
-      "Bash(bash learning_agents/scripts/*)",
+      "Bash(gh api:*)",
+      "Bash(learning_agents/scripts/*:*)",
+      "Bash(bash learning_agents/scripts/*:*)",
+      "Bash(bash .deepwork/requirements_traceability_info.sh:*)",
       "WebSearch",
       "Skill(deepwork)",
       "mcp__deepwork__get_workflows",
 
@@ -0,0 +1,6 @@
+requirements:
+  new-entries-in-unreleased: |
+    New changelog entries added in a PR MUST be placed under the `## [Unreleased]`
+    section, not under any already-released version section (e.g., `## [0.13.0]`).
+    Released version sections are immutable historical records — only the release
+    workflow may modify them when cutting a new release.
@@ -10,6 +10,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Integration tests for quality gate review caching (JOBS-REQ-004.5.7)
+- Requirements traceability coverage now at 100% (#346)
+  - Added section-level REQ ID annotations to 32 existing test files for traceability
+  - Wrote 218 new tests across 5 files for learning-agents requirements (LA-REQ-001, 003, 004, 005, 006, 010, 011)
+  - Added 6 anonymous DeepSchemas for judgment-based learning-agents skill requirements (LA-REQ-002, 007, 008, 009, 012)
+  - Added new PLUG-REQ-001.12 tests for session/agent identity injection hooks
+  - New `req-ids-in-comments` requirement in the standard DeepSchema definition: requirement IDs must be placed in YAML comments, not requirement body text
 
 ### Changed
 
 
@@ -91,6 +91,7 @@ Example structure:
 ---
 name: <agent-name>
 description: "<discovery description>"
+model: sonnet
 ---
 
 # Core Knowledge
@@ -108,16 +109,24 @@ Located in `.deepwork/learning-agents/<agent-name>/topics/`
 Learnings are incident post-mortems from past agent sessions capturing mistakes, root causes, and generalizable insights. Review them before starting work to avoid repeating past mistakes. Located in `.deepwork/learning-agents/<agent-name>/learnings/`.
 ```
 
+The frontmatter `model:` field is required (LA-REQ-002.9) and defaults to `sonnet` to keep agent invocations cost-effective.
+
 ### Session Logs (transient, gitignored)
 
 ```
 .deepwork/tmp/agent_sessions/<session_id>/<agent_id>/
 ├── needs_learning_as_of_timestamp      # Flag file (body = ISO 8601 timestamp)
 ├── learning_last_performed_timestamp   # When learning was last run on this conversation
 ├── agent_used                          # Body = LearningAgent folder name
+├── conversation_transcript.jsonl       # Snapshot of the agent's conversation transcript
 └── <brief-name>.issue.yml              # Issues found during learning
 ```
 
+The `conversation_transcript.jsonl` file is the captured agent transcript used by the
+`investigate-issues` skill to research root causes (LA-REQ-008.6). If it cannot be
+found for a session, the learning cycle skips that session and reports the issue in
+the final summary.
+
 See `learning_log_folder_structure.md` for full details.
 
 ## Hooks
@@ -185,7 +194,7 @@ Entry point skill. Dynamically lists existing LearningAgents at load time, then
 - `/learning-agents report_issue <agent_id> <details>` → invokes `report-issue`
 
 #### create-agent
-Creates a new LearningAgent. Accepts an optional `template-path` argument — when provided, the new agent is seeded with the template agent's `core-knowledge.md`, `topics/`, and `learnings/` as a starting point. The skill first invokes a setup script, then guides the user through filling in the content.
+Creates a new LearningAgent. Accepts an optional `template-path` argument — when provided, the new agent is seeded with the template agent's `core-knowledge.md`, `topics/`, and `learnings/` as a starting point. The skill first invokes a setup script, then guides the user through filling in the content. The skill enforces dash-separated lowercase agent names, refuses to overwrite existing agents, and ensures the generated `.claude/agents/<agent-name>.md` frontmatter includes a `model:` field (defaulting to `sonnet`).
 
 **Step 1 — Setup script (`scripts/create_agent.sh`)**
 
@@ -241,21 +250,23 @@ After the script runs, the skill prompts the user to describe what the agent is
 Fills in key files in the LearningAgent directory — initial topics and/or learnings if the user provides seed knowledge about the domain.
 
 #### learn
-Runs the full learning cycle on all sessions needing it. Workflow:
+Runs the full learning cycle on all sessions needing it. The skill takes no arguments — any text after `learn` is ignored. Sessions are processed sequentially (not in parallel) to avoid conflicts when the same agent appears in multiple sessions. Workflow:
 1. Uses `!`find ...`` to inject a list of all paths containing a `needs_learning_as_of_timestamp` file into the prompt
 2. For each such folder, spawns a Task with the `LearningAgentExpert` agent using **Sonnet model** to run the `identify` skill
 3. After identification completes, spawns a Task with the `LearningAgentExpert` to run `investigate-issues` then `incorporate-learnings` in sequence
 
+If no pending sessions are found (or the `.deepwork/tmp/agent_sessions/` directory is missing), the skill informs the user and stops. If a sub-skill Task fails for a session, the skill logs the failure, skips that session, continues processing remaining sessions, and does NOT mark `needs_learning_as_of_timestamp` as resolved. On completion, the skill outputs a summary containing total sessions processed, total issues identified, list of agents updated, key learnings per agent, and any skipped sessions with reasons. The `learn` skill itself MUST NOT modify agent files directly — all knowledge base updates are delegated to the sub-skills.
+
 #### setup
 Configures project permissions for the LearningAgents plugin. Adds required Bash and file access rules to `.claude/settings.json` so hooks and scripts can run without manual approval.
 
 #### prompt-review
-Standalone skill (not routed through the `/learning-agents` dispatcher). Reviews prompt/instruction files against Anthropic prompt engineering best practices. Can be invoked directly as `/learning-agents:prompt-review`.
+Standalone skill (not routed through the `/learning-agents` dispatcher). Reviews prompt/instruction files against Anthropic prompt engineering best practices. Can be invoked directly as `/learning-agents:prompt-review`. Accepts a target file path argument and produces actionable feedback grouped by best-practice category — it does not modify the target file.
 
 ### Hidden Skills (used by LearningAgentExpert during learning)
 
 #### identify
-Reviews a session transcript to find issues. Takes the session/agent_id folder path as an argument.
+Reviews a session transcript to find issues. Takes the session/agent_id folder path as an argument. The skill reads the transcript and surfaces concrete mistakes, underperformance, or knowledge gaps — emitting one issue per finding via `report-issue`. Per-agent identification guidance is loaded dynamically from the agent's `additional_learning_guidelines/issue_identification.md` file (empty file = no extra guidance).
 - Uses `!`cat ...`` to inject `learning_last_performed_timestamp` value into the prompt
 - Reads the transcript and identifies mistakes, underperformance, or knowledge gaps
 - Calls `report-issue` for each issue found
@@ -265,14 +276,14 @@ Reviews a session transcript to find issues. Takes the session/agent_id folder p
 Creates an `<brief-name>.issue.yml` file in the session's agent log folder. Sets initial status to `identified` with the issue description and observed timestamps. See `issue_yml_format.md` for the schema.
 
 #### investigate-issues
-Processes all `identified` issues in a session folder:
+Processes all `identified` issues in a session folder, researching root causes from transcript evidence and the agent's existing knowledge. Per-agent investigation guidance is loaded dynamically from `additional_learning_guidelines/issue_investigation.md`.
 1. Finds issues with status `identified` (includes example bash command in skill prompt)
 2. Uses `!`cat $0/agent_used`` to inject the agent name, then `!`cat`` to load the agent's instructions — avoiding extra round trips
-3. Reads the agent's full expertise and knowledge
+3. Reads the agent's full expertise and knowledge, plus the captured `conversation_transcript.jsonl`
 4. For each issue: reads relevant transcript sections, determines root cause, updates status to `investigated` with `investigation_report`
 
 #### incorporate-learnings
-Integrates investigated issues into the LearningAgent:
+Integrates investigated issues into the LearningAgent. Topics document conceptual reference material (how things work — patterns, APIs, conventions); learnings document incident post-mortems of specific mistakes (what went wrong and why). Per-agent incorporation guidance is loaded dynamically from `additional_learning_guidelines/learning_from_issues.md`.
 1. Finds issues with status `investigated` (includes example bash command)
 2. For each issue, takes a learning action — one of:
    - **Update core knowledge**: Modify `core-knowledge.md` to address the knowledge gap
 
@@ -0,0 +1,67 @@
+# DeepSchema for create-agent skill — validates LA-REQ-002 judgment-based requirements
+requirements:
+  # LA-REQ-002.1
+  skill-invocation-and-name-prompt: >
+    The skill MUST be invocable via /learning-agents create <name>, and if
+    no name is provided, MUST prompt the user for a name.
+
+  # LA-REQ-002.2
+  name-normalization: >
+    The skill MUST normalize agent names by converting spaces and uppercase
+    to lowercase dashes (e.g. "Rails ActiveJob" -> "rails-activejob").
+
+  # LA-REQ-002.3
+  pre-scaffold-validation: >
+    The skill MUST check that .deepwork/learning-agents/ exists (or create it)
+    and verify no agent with the same name already exists before scaffolding.
+
+  # LA-REQ-002.4
+  agent-directory-path: >
+    The skill MUST place the new agent under .deepwork/learning-agents/<name>/.
+
+  # LA-REQ-002.5
+  scaffold-invocation: >
+    The skill MUST invoke the create_agent.sh script to create the directory
+    structure rather than creating files inline.
+
+  # LA-REQ-002.7
+  file-paths-for-scaffold: >
+    The skill MUST pass the correct agent name and plugin root path to the
+    scaffold script so it creates files in the right locations.
+
+  # LA-REQ-002.9
+  claude-agent-file-config: >
+    The skill MUST configure the Claude Code agent file with appropriate
+    name, description, and model settings after scaffolding.
+
+  # LA-REQ-002.12
+  interactive-configuration: >
+    After scaffolding, the skill MUST ask the user about the agent's domain
+    of expertise and update core-knowledge.md and the agent file accordingly.
+
+  # LA-REQ-002.13
+  optional-knowledge-seeding: >
+    The skill MUST offer the user the option to seed initial topics or
+    learnings, creating files following the formats from LA-REQ-003.
+
+  # LA-REQ-002.14
+  creation-summary: >
+    Upon completion, the skill MUST output a summary listing created files,
+    usage instructions for invoking the agent, and a note about the learning
+    cycle.
+
+  # LA-REQ-002.15
+  no-overwrites: >
+    The skill MUST NOT overwrite any existing file without explicit user
+    confirmation.
+
+  # LA-REQ-002.23
+  template-configuration-guidance: >
+    When a template was used, the skill MUST present the copied core-knowledge.md
+    and offer to keep, modify, or replace it, and list copied topics/learnings
+    for review.
+
+  # LA-REQ-002.24
+  template-summary: >
+    When a template was used, the completion summary MUST note which template
+    was used and how many files were seeded from it.
@@ -0,0 +1,105 @@
+requirements:
+  # LA-REQ-007.1
+  not-user-invocable: >
+    The skill frontmatter MUST set `user-invocable: false` so it cannot be
+    directly invoked by the user.
+
+  # LA-REQ-007.2
+  input-argument-path: >
+    The skill MUST accept a single argument: the path to the session/agent_id
+    folder (e.g., `.deepwork/tmp/agent_sessions/<session_id>/<agent_id>/`).
+
+  # LA-REQ-007.3
+  agent-context-loading: >
+    The skill MUST dynamically load the agent name from `$ARGUMENTS/agent_used`,
+    the last learning timestamp from `$ARGUMENTS/learning_last_performed_timestamp`,
+    and additional identification guidelines from
+    `.deepwork/learning-agents/<agent-name>/additional_learning_guidelines/issue_identification.md`.
+
+  # LA-REQ-007.4
+  transcript-location: >
+    The skill MUST instruct the agent to read the transcript from the session
+    folder. The transcript file MUST be located relative to `$ARGUMENTS`.
+
+  # LA-REQ-007.5
+  missing-transcript-handling: >
+    The skill MUST instruct the agent to report an error and stop if no
+    transcript file is found, without creating any issue files.
+
+  # LA-REQ-007.6
+  transcript-format-jsonl: >
+    The skill MUST instruct the agent to parse the transcript as JSONL and focus
+    on `type: "assistant"` messages and `type: "tool_result"` entries to evaluate
+    agent behavior.
+
+  # LA-REQ-007.7
+  incremental-processing: >
+    The skill MUST instruct the agent to skip transcript lines before
+    `learning_last_performed_timestamp` when that value exists, analyzing only
+    interactions since the last learning cycle.
+
+  # LA-REQ-007.9
+  issue-categories: >
+    The skill MUST enumerate all five issue categories: incorrect outputs,
+    knowledge gaps, missed context, poor judgment, and pattern failures.
+
+  # LA-REQ-007.10
+  trivial-issue-filtering: >
+    The skill MUST instruct the agent to skip trivial issues including minor
+    formatting differences, environmental failures, and issues already covered
+    by existing learnings or issue files.
+
+  # LA-REQ-007.11
+  report-via-sub-skill: >
+    The skill MUST instruct the agent to invoke the `report-issue` skill once
+    per issue found, passing the session folder path and a description of the
+    problem.
+
+  # LA-REQ-007.12
+  no-duplicate-issues: >
+    The skill MUST instruct the agent to avoid creating duplicate issue files
+    for the same problem, including by listing existing issue files for
+    reference.
+
+  # LA-REQ-007.13
+  no-root-cause-investigation: >
+    The skill MUST explicitly prohibit root cause investigation, deferring that
+    to the `investigate-issues` skill.
+
+  # LA-REQ-007.14
+  no-knowledge-base-modification: >
+    The skill MUST explicitly prohibit modification of the agent's knowledge
+    base (core-knowledge.md, topics, or learnings).
+
+  # LA-REQ-007.15
+  summary-output: >
+    The skill MUST instruct the agent to output a summary containing session ID,
+    agent name, count of issues found, and a table listing each issue with its
+    category and description (or a message indicating no issues were found).
+
+  # LA-REQ-007.8
+  agent-focus: >
+    The skill MUST focus on interactions involving the agent identified in
+    the agent_used file and SHOULD NOT analyze interactions with other
+    agents.
+
+  # LA-REQ-007, LA-REQ-007.16
+  allowed-tools-only: >
+    The skill MUST restrict tool usage to only: Read, Grep, Glob, Skill.
+
+  # LA-REQ-005.8
+  timestamp-source-accuracy: >
+    The skill MUST instruct that seen_at_timestamps come from either exact
+    transcript line timestamps or the current UTC time when reviewing live
+    sessions.
+
+  # LA-REQ-005.11
+  investigation-report-content: >
+    The skill MUST instruct that investigation_report fields contain specific
+    line numbers from the transcript as evidence.
+
+  # LA-REQ-005.13
+  no-duplicate-issues-lifecycle: >
+    The skill MUST instruct the agent to check for existing issues before
+    creating new ones, preventing duplicate issue files for the same problem
+    within a single session.