Resolve current state: explicit active task, session → docs, clear/archive on finish

playbooks/AI_WORKFLOW_PLAYBOOK.md

@@ -17,7 +17,7 @@ Date: 2026-02-20
 ### 2. Finish Branch
 **Goal**: Safely finalize a branch before opening a PR, ensuring all tests pass and docs are up-to-date.
 
-Finishing a branch runs a code review (guided by `docs/ai/code_review_prompt.md`), then a compliance and traceability audit against deterministic standards. The AI waits for you to push and paste any CI or BugBot feedback, loops on fixes until CI is green, and only then proceeds to final spackle: running sync-docs to update any docs that need changes based on the branch diff (SPEC, SCHEMA_REFERENCE, DATA_FLOW_MAP, ADRs, etc.), harvesting new rules into architecture docs, ensuring CHANGELOG is updated for user-facing changes, updating `docs/ROADMAP.md` to mark the completed item as done, and outputting the PR description in a code block. The AI never auto-commits or auto-pushes; it provides the exact `git push` command for you to run.
+Finishing a branch runs a code review (guided by `docs/ai/code_review_prompt.md`), then a compliance and traceability audit against deterministic standards. The AI waits for you to push and paste any CI or BugBot feedback, loops on fixes until CI is green, and only then proceeds to final spackle: running sync-docs to update any docs that need changes (using both the branch diff and the active task session — session is semantically analyzed so domain, decisions, data semantics, and conventions are pushed to the right docs), harvesting new rules from diff, review_ledger, and task session into architecture docs and .cursorrules, ensuring CHANGELOG is updated for user-facing changes, updating `docs/ROADMAP.md` to mark the completed item as done, and outputting the PR description in a code block. The AI never auto-commits or auto-pushes; it provides the exact `git push` command for you to run.
 
 ### 3. Status Check
 **Goal**: Understand blocking issues and re-hydrate the AI's state.
@@ -31,9 +31,9 @@ Finishing a branch runs a code review (guided by `docs/ai/code_review_prompt.md`
 | code-review | code review, run code review, review my changes | Project-specific static analysis and fix loop |
 | status-check | status check, where are we, blocked | Rehydrate context and diagnose blockers |
 | process-feedback | pasting CI logs, Bugbot comments, SonarQube errors | Interrupt subroutine: fix code, log diagnosis to short-term memory, resume previous task |
-| harvest-rules | harvest rules, update docs | Extract new patterns into docs and .cursorrules |
+| harvest-rules | harvest rules, update docs | Extract new patterns from diff, review_ledger, and task session into docs and .cursorrules |
 | audit-compliance | audit compliance, run audit | IV&V audit against deterministic standards |
-| sync-docs | sync docs, sync project docs | Keep docs in sync with branch changes (SPEC, SCHEMA_REFERENCE, DATA_FLOW_MAP, ADRs, etc.) |
+| sync-docs | sync docs, sync project docs | Keep docs in sync with branch diff and task session (semantic analysis → SPEC, SCHEMA_REFERENCE, ADRs, .cursorrules, etc.) |
 | pr-description | PR description, draft PR | Output PR description in a code block |
 | roadmap-manage | roadmap, manage roadmap, add to roadmap | Add, prioritize, catalog roadmap items |
 | roadmap-consult | roadmap status, what's pending, roadmap consult | Read-only view of done/pending/priorities |

playbooks/EXPECTED_PROJECT_STRUCTURE.md

@@ -8,10 +8,11 @@ This document lists every referenced path, its purpose, and how it fits into the
 *Located in `.agenticguild/` (Gitignored)*
 | Path | Purpose |
 |------|---------|
-| `current_state.md` | Tracks the active skill, phase, and step. Used to resume tasks. Format: `<active_task_pointer>` = session filename (e.g. `task_foo.md`) or `[NONE]`; `<execution_context>` contains `<active_skill>`, `<current_phase>`, `<current_step>`. |
+| `current_state.md` | Tracks the active skill, phase, and step. Used to resume tasks. Format: `<active_task_pointer>` = session filename (e.g. `task_foo.md`) or `[NONE]`; `<execution_context>` contains `<active_skill>`, `<current_phase>`, `<current_step>`. When multiple session files exist, the active task pointer MUST be set so status-check and cross-IDE resume work correctly. |
 | `blocker_log.md` | Logs CI/CD failures or missing user inputs. |
 | `pending_refactors.md` | Logs tech debt discovered outside the scope of a current task. |
 | `active_sessions/task_*.md` | The runtime memory for specific features/bugfixes. |
+| `completed_sessions/` | Archived task session files after branch finish (optional). Created when the user confirms clearing the active task; session is moved here with a date suffix (e.g. `task_foo_YYYY-MM-DD.md`). |
 
 ## 2. The Engine (XML Skills)
 *Located in `.cursor/skills/`*
@@ -22,8 +23,8 @@ This document lists every referenced path, its purpose, and how it fits into the
 | `code-review/SKILL.md` | Runs project-specific static analysis. |
 | `audit-compliance/SKILL.md` | IV&V agent that mathematically checks code determinism. |
 | `status-check/SKILL.md` | Reads `.agenticguild/` to diagnose blockers and rehydrate context. |
-| `harvest-rules/SKILL.md` | Scans diffs to update architecture docs and `.cursorrules`. |
-| `sync-docs/SKILL.md` | Keeps project docs in sync with branch changes (SPEC, SCHEMA_REFERENCE, DATA_FLOW_MAP, ADRs, etc.). |
+| `harvest-rules/SKILL.md` | Proposes new rules from git diff, review_ledger, and active task session; writes approved rules to `.cursorrules` and SYSTEM_ARCHITECTURE. |
+| `sync-docs/SKILL.md` | Keeps project docs in sync with branch diff and active task session (SPEC, SCHEMA_REFERENCE, DATA_FLOW_MAP, ADRs, .cursorrules, etc.); session is semantically analyzed and knowledge is placed by type. |
 | `pr-description/SKILL.md` | Outputs a Git-based PR description in a code block for the user to copy. |
 | `roadmap-manage/SKILL.md` | Add, prioritize, catalog items in the project roadmap. |
 | `roadmap-consult/SKILL.md` | Read-only view of roadmap: done, pending, priorities. |
@@ -41,17 +42,20 @@ This document lists every referenced path, its purpose, and how it fits into the
 | `ADRs/` | Architectural Decision Records to bypass `SYSTEM_ARCHITECTURE.md`. |
 
 ## 4. Docs to Sync (sync-docs skill)
-The `sync-docs` skill checks these docs against the branch diff and updates any that need changes. Only existing files are considered.
+The `sync-docs` skill keeps docs in sync with both the branch diff and task memory. It checks these docs against the diff and, when an active task session exists, semantically analyzes the session and proposes updates by knowledge type (domain → SPEC, decisions → ADRs, data semantics → SCHEMA_REFERENCE enrichment, conventions/patterns → .cursorrules and SYSTEM_ARCHITECTURE). Only existing files are considered.
 | Doc | When to update |
 |-----|----------------|
 | `docs/core/SPEC.md` | Domain logic, entities, or requirements changed |
-| `docs/core/SCHEMA_REFERENCE.md` | Schema or migrations changed (generated from raw schema) |
+| `docs/core/SCHEMA_REFERENCE.md` | Schema or migrations changed (structure from raw schema; session can enrich with data semantics — why/when of tables and columns) |
 | `docs/core/DATA_FLOW_MAP.md` | Entity lifecycles or side-effects changed |
 | `docs/core/ADRs/` | New architectural decisions |
 | `docs/core/SYSTEM_ARCHITECTURE.md` | Stack, boundaries, or forbidden libs changed |
+| `.cursorrules` | Conventions, patterns, or project rules changed (from diff or session) |
 
 **To add more docs:** Update this table in `docs/ai/EXPECTED_PROJECT_STRUCTURE.md`. Add the path and the condition that triggers an update. The sync-docs skill reads this list.
 
+**Overlap with harvest-rules:** Both sync-docs and harvest-rules write to `.cursorrules` (and SYSTEM_ARCHITECTURE) by design: sync-docs adds session- and diff-derived conventions/patterns in one batch; harvest-rules proposes rule candidates from diff, review_ledger, and session for user approval, then writes approved ones. They are complementary. Harvest-rules already filters out candidates that duplicate rules already in `.cursorrules`; when both run in the same finish-branch flow, the user may reject harvest-rules candidates that repeat what sync-docs just added.
+
 ## 5. Project-Specific Configuration
 
 ### 5.1 `.cursorrules` &lt;project_config&gt;

skills/audit-compliance/SKILL.md

@@ -9,6 +9,10 @@
     2. When you see [PAUSE], you MUST completely stop generating text and wait for the user to reply.
     3. Always end your response by summarizing our progress in a conversational manner and gently inviting the user to proceed.
   </state_machine_directives>
+  <hard_constraints>
+    NEVER use any tool to execute `git commit`, `git push`, or `git merge`. These commands are STRICTLY FORBIDDEN.
+    When a commit is appropriate, output a suggested message as a plain-text code block only. The user runs all git commands themselves.
+  </hard_constraints>
 
   <persona>
     Act as a highly experienced, composed Principal Architect conducting an objective compliance review. Communicate your strict, unbiased findings in a professional, constructive, and conversational tone. When asking for input, be conversational instead of presenting rigid menus or dictating what the user should type. Hide the technical "phases and steps" of this workflow behind natural conversation.

skills/explore-task/SKILL.md

@@ -36,15 +36,15 @@
         <action>
           First, check if `.agenticguild/current_state.md` points to an active session file.
           If it points to a session file: Verify the file actually exists. If it does, use the `view_file` tool to read it, summarize its current state, and ask what we need to figure out next. If it does not exist, treat this as a new session.
-          If this is a new session (no active task, or file is missing): Ask the user what they want to build or what problem they are trying to solve. Once they reply (in Step 1.2), you will derive `[name]` as a kebab-case slug, create `.agenticguild/active_sessions/task_[name].md`, and silently update `.agenticguild/current_state.md` to point to it.
+          If this is a new session (no active task, or file is missing): Ask the user what they want to build or what problem they are trying to solve. Once they reply (in Step 1.2), you will derive `[name]` as a kebab-case slug, create `.agenticguild/active_sessions/task_[name].md`, and silently update `.agenticguild/current_state.md` by setting `<active_task_pointer>` to `task_[name].md` so the active task is unambiguous across IDEs.
         </action>
         <yield>[PAUSE - AWAIT USER INPUT]</yield>
       </step>
       <step id="1.2">
         <action>
           Process the user's input. 
           1. Converse: Answer questions, propose architectural solutions, or ask clarifying questions to nail down edge cases.
-          2. Update Memory: If this is the first exchange and `task_[name].md` hasn't been created, derive the name, create the file using the `write_to_file` tool, and update `.agenticguild/current_state.md`. You MUST use the `replace_file_content` tool to update the active memory file to reflect any new decisions, requirements, or constraints agreed upon in this exchange. 
+          2. Update Memory: If this is the first exchange and `task_[name].md` hasn't been created, derive the name, create the file using the `write_to_file` tool, and update `.agenticguild/current_state.md` by setting `<active_task_pointer>` to `task_[name].md`. You MUST use the `replace_file_content` tool to update the active memory file to reflect any new decisions, requirements, or constraints agreed upon in this exchange. 
              - If a major pivot occurs (e.g. "let's not use Redis"), move the old plan to `task_[name]_history.md` so the active file stays clean.
           3. Domain Model (CbC): As domain entities and their data requirements become clear during the conversation, maintain a `## Domain Model` section in the memory file. For each entity introduced, document:
              - **Entity name** and its core responsibility

skills/finish-branch/SKILL.md

@@ -71,7 +71,7 @@
       <step id="3.1">
         <action>
           Instruct the user to commit their code, push to the remote branch, and wait for CI feedback.
-          Update `.agenticguild/current_state.md` to indicate waiting status.
+          Update `.agenticguild/current_state.md` to indicate waiting status (e.g. in `<execution_context>`). Retain `<active_task_pointer>` unchanged so status-check and resume still know which task is active.
         </action>
         <yield>
           [PAUSE - AWAIT CI STATUS]
@@ -103,7 +103,19 @@
       </step>
       <step id="4.3">
         <action>Check if user-facing changes exist; if so, ensure `CHANGELOG.md` is updated. Use the `view_file` tool to read the active session file (if any) for `<roadmap_item>`. If this branch corresponds to a roadmap item, update `docs/ROADMAP.md`: move the item to Done, add today's date. If unclear, ask the user which roadmap item (if any) this branch completes. Then use the `view_file` tool to read and follow `.cursor/skills/pr-description/SKILL.md` until it yields. Remind the user to commit `docs/ROADMAP.md` if it was updated.</action>
-        <yield>[PAUSE - BRANCH IS FINISHED]</yield>
+        <yield>[PAUSE - AWAIT CONFIRMATION]</yield>
+      </step>
+      <step id="4.4">
+        <action>
+          The branch is finished and task knowledge has been synced to the docs (sync-docs and harvest-rules). Conversationally tell the user that and ask: "Would you like me to clear the active task from memory? I'll set the active task to none and archive the session file to `.agenticguild/completed_sessions/` so it's no longer the current task — you can delete that folder or file later if you don't need the record. Reply yes to clear and archive, or no to leave it as-is for now."
+        </action>
+        <yield>[PAUSE - AWAIT USER CONFIRMATION TO CLEAR TASK FROM MEMORY]</yield>
+      </step>
+      <step id="4.5">
+        <action>
+          Parse the user's reply. If they confirmed (e.g. "yes", "clear", "archive"): Read `.agenticguild/current_state.md` to get `<active_task_pointer>`. If the pointer contains a session filename (e.g. `task_foo.md`): Create `.agenticguild/completed_sessions/` if it does not exist (e.g. run `mkdir -p .agenticguild/completed_sessions`). Move the session file from `.agenticguild/active_sessions/` to `.agenticguild/completed_sessions/` with a date suffix in the filename (e.g. `task_foo_YYYY-MM-DD.md`). Then update `.agenticguild/current_state.md`: set `<active_task_pointer>` to `[NONE]` and `<execution_context>` to `<active_skill>[NONE]</active_skill>`, `<current_phase>[NONE]</current_phase>`, `<current_step>[NONE]</current_step>`. Confirm to the user that the task was cleared and the session file was archived. If the pointer was already [NONE] or the session file was missing, just update current_state to [NONE] and confirm. If they declined (e.g. "no", "keep"): Acknowledge; no changes. The session stays in active_sessions and the pointer unchanged; they can clear later via status-check or by running finish-branch again.
+        </action>
+        <yield>[PAUSE - FINISH-BRANCH COMPLETE]</yield>
       </step>
     </phase>
   </workflow>

skills/harvest-rules/SKILL.md

@@ -30,19 +30,21 @@
     <phase id="1" name="Pattern Analysis">
       <step id="1.0">
         <action>
-          Check if `.agenticguild/review_ledger.md` exists. 
-          If it exists, read its contents. Synthesize the recorded CI/Review diagnoses into actionable "Gotchas" or "Anti-Patterns" you should avoid in the future.
-          Combine these findings with your standard git diff analysis in the next step to propose a unified list of "New Rule Candidates".
+          Check if `.agenticguild/review_ledger.md` exists. If it exists, read its contents. Synthesize the recorded CI/Review diagnoses into actionable "Gotchas" or "Anti-Patterns" you should avoid in the future.
+          If an active task session exists: Use the `view_file` tool to read `.agenticguild/current_state.md` and parse `<active_task_pointer>`. If it points to a session filename (e.g. `task_foo.md`) and that file exists at `.agenticguild/active_sessions/` + that filename, read the entire session file. Analyze it for rule-worthy content: conventions, patterns, anti-patterns, "we must/must not" decisions, naming or style choices. Treat these as additional candidates to merge with review_ledger and the diff in step 1.1.
+          Combine review_ledger findings (and any session-derived candidates) with your standard git diff analysis in the next step to propose a unified list of "New Rule Candidates".
         </action>
+        <yield>[AUTO-TRANSITION TO 1.1]</yield>
       </step>
       <step id="1.1">
         <action>
           Read the `git diff` of the current branch against the default branch (e.g. `main`). Use the repository's default branch unless the project uses a different convention.
           Analyze the changes for new error handling, naming conventions, UI patterns, or data structures.
+          If you read a session file in step 1.0, include the session-derived rule candidates in your analysis. Merge with diff-based and review_ledger-based candidates into one unified list.
           Scan the `docs/` directory and `.cursorrules` to determine where these new patterns should be codified.
-          Before outputting candidates: Verify proposed rules do not contradict or duplicate rules already in `docs/core/SYSTEM_ARCHITECTURE.md` or `.cursorrules`. Filter out any that do.
+          Before outputting candidates: Verify proposed rules do not contradict or duplicate rules already in `docs/core/SYSTEM_ARCHITECTURE.md` or `.cursorrules`. Filter out any that do. If run after sync-docs in the same workflow (e.g. finish-branch), skip candidates that are semantically equivalent to rules likely just added to `.cursorrules` by sync-docs to avoid near-duplicates.
           If the changes imply future work (e.g. a new pattern that will need follow-up features), consider suggesting adding a roadmap item to `docs/ROADMAP.md` via the roadmap-manage skill.
-          Output a list of "New Rule Candidates" formatted as: `[Target File] -> [Proposed Rule Addition]`.
+          Output a list of "New Rule Candidates" formatted as: `[Target File] -> [Proposed Rule Addition]`. Optionally note which candidates came from diff, review_ledger, or session when it helps the user.
         </action>
         <yield>[PAUSE - WRITE LOCK ACTIVE. AWAIT USER APPROVAL OF CANDIDATES]</yield>
       </step>

skills/pr-description/SKILL.md

@@ -22,6 +22,9 @@
   </pre_flight>
 
   <hard_constraints>
+    NEVER use any tool to execute `git commit`, `git push`, or `git merge`. These commands are STRICTLY FORBIDDEN.
+    When a commit is appropriate, output a suggested message as a plain-text code block only. The user runs all git commands themselves.
+
     1. Do NOT use markdown link syntax for any file references in the PR description. IDEs convert local paths into broken `cci:7://file:///` hyperlinks that are useless when pasted into GitHub.
     2. For files that exist in the repo: use plain backtick code formatting only — e.g. `docs/core/SYSTEM_ARCHITECTURE.md`.
     3. For deleted or renamed files: use backtick formatting only — never link syntax.