Signal/docs/workflow-consolidation-design-2026-06-24-pi-recovered.md

# Workflow Consolidation — Pi Design (RECOVERED from Pi session log 2026-06-24)

> Recovered by Claude Code from `~/.pi/agent/sessions/...019ef117...jsonl` because Pi finalized this
> design only in its conversation and never wrote it to a file. This file is the durable artifact.
> Reconcile against the architect-reviewed brief `workflow-consolidation-brief-2026-06-23.md` before building.

---

Okay, I understand. The plan is to:

1.  **Integrate the "golden nuggets"** regarding expanded Git version control into the workflow consolidation design document.
2.  **Confirm the updated design is final.**
3.  **Prepare for session wrap-up by updating `current-state.md`** with the final design details and clear next steps for Claude Code.

---

## **Revised Design Document: Workflow Consolidation for STTIL Agents**

**Date:** 2026-06-24 (Revised)
**Purpose:** To eliminate workflow drift, centralize state management, and automate recurring manual protocols across Pi and Claude Code agents operating within STTIL Solutions, leveraging Git as a universal version control system.

---

### **1. The State Contract: `current-state.md` Schema & Protocol**

This section defines the canonical format and interaction protocols for the `current-state.md` file, the single source of truth for volatile project state within a repository.

**A. `current-state.md` Schema (Schema `v:1`)**

```markdown
v:1
# current-state

ACTIVE: [Concise summary of what is actively being worked on by either agent. Limit to 1-2 sentences.]
NEXT (Agent, in order): [Ordered list of next tasks. Each task should specify the responsible agent (Pi/Claude) and a brief description. E.g., (1) Claude: Build Phase 2. (2) Pi: Design X. ]

## Decisions (last X)
- [YYYY-MM-DD]: [Decision summary. Include author tag: [Pi] or [CC]. E.g., - 2026-06-24: Decision A made. [Pi]]
- [YYYY-MM-DD]: [Decision summary. Include author tag: [Pi] or [CC].]

## Open Threads (max 5)
- [Concise summary of an open, unresolved issue or pending task, with context. E.g., - Need to contact Validated Cloud for pricing (deferred until Pi contact). ]
- [Concise summary of an open, unresolved issue or pending task, with context.]

## Stack
- [Key infrastructure components, models, and tools used by the project. Updates infrequently. E.g., - Signal: Patient IDs now use RAP-ID/CSP-ID architecture.]
- [Key infrastructure components, models, and tools used by the project.]

## Tip
- [General advice or reminder relevant to the current project context. E.g., - TriLane Memory is reachable via HTTP not MCP for Pi.]

## Updated: [YYYY-MM-DD] [Brief overall project status/changelog. Include responsible agents. E.g., Updated: 2026-06-24 (Pi: Workflow consolidation design complete; Claude: Built X.)]
```

**B. De-duplication Map (Source of Truth for Information Types)**

*   **`current-state.md`:** Volatile project state (changes every session) – ACTIVE/NEXT tasks, recent decisions, immediate open threads.
*   **`CLAUDE.md`:** Stable project facts (true for months) – What the product is, core PHI rules, run commands, permanent checklists, core technical stack. Demoted, one-line "Current State" pointer.
*   **Claude Memory:** Kisa/CC operating notes, internal thought processes, temporary working notes.
*   **TriLane (Searchable Archive & Intelligence Hub):** History, validated research insights, long-term learning, previous session summaries, **correlated market projections**. TriLane *consumes* Git-managed versioned artifacts as input for its intelligence.

**C. Read Protocol (Agent Startup/Resume)**

1.  **`git pull --rebase origin <current_branch>`:** Fetch latest changes and rebase local branch to ensure working on the freshest state for the primary repository.
2.  **`git pull --rebase origin <skills_repo_branch>`:** If skills are in a separate Git repo, update them.
3.  **Read `signal/context/current-state.md`:** Load file contents into agent's short-term context.
4.  **Surface Staleness Signal:** Compare current date to the `Updated:` timestamp in `current-state.md`. If `current-state.md` is older than 24 hours, issue a warning to the user: "Warning: Project state last updated X days ago. Consider reviewing recent activity." *Constraint: Lean, token-conscious – this is a simple check, not a deep diff.*

**D. Write Protocol (Agent Wrap-up/Commit)**

1.  **Single Mutable Head:** Agents may only directly modify the `ACTIVE` and `NEXT` sections.
2.  **Append-Only Decisions Log:** All new decisions must be appended to the `Decisions` section, prefixed with `[YYYY-MM-DD]: [Decision Summary. [Author Tag]]`.
3.  **Update `Updated:` Timestamp:** The `Updated:` line at the bottom must be updated to the current date and a brief status summary.
4.  **Rebase-and-Commit Cycle (General for any Git-managed file):**
    *   Immediately before writing to *any* Git-managed file (e.g., `current-state.md`, `SKILL.md`, `payer_rules.json`, blog posts), execute `git pull --rebase origin <current_branch>`.
    *   If a conflict occurs, the *last writer hand-merges* their changes. (`-X ours` and lock files are forbidden).
    *   Write changes to the file(s).
    *   `git add <path/to/modified/file(s)>`.
    *   `git commit -m "Update [file(s)] by [Author Tag]: [brief summary of changes]"`
    *   `git push origin <current_branch>`.
5.  **Visibility for Push Failures:** Push failures must be reported directly to the console/session output, never swallowed silently.

---

### **2. Reliable Wrap-up Commit + Push (Automation Design)**

To prevent state loss due to crashes or skipped wrap-ups.

**A. Recommended Mechanism: Harness Stop Hook**

The primary mechanism will be a harness-level stop hook, which executes reliable git operations regardless of user-triggered wrap-up or session termination.

*   **Placement:**
    *   **Pi:** `~/.pi/agent/settings.json` (or equivalent harness configuration).
    *   **Claude Code:** `~/.claude/agent/settings.json` (or equivalent harness configuration).
*   **Action:** Execute a script (e.g., `update_repo_on_stop.sh`) when the agent session stops. This script will generalize the `current-state.md` logic to any modified file within the working repository.
*   **`update_repo_on_stop.sh` Script Logic (Conceptual):**
    ```bash
    #!/bin/bash
    PRIMARY_REPO_ROOT="/Users/sttil-solutions/projects/signal" # Target the main project repo

    # --- Generic Git Auto-Commit & Push Logic ---
    # This script is a generalized abstraction. Actual implementation needs to identify
    # which Git repositories are active (e.g., "$PRIMARY_REPO_ROOT", "~/.claude/skills/")
    # and perform operations for each.

    handle_repo() {
        local repo_path=$1
        local branch_name="main" # Or dynamically determine current branch
        cd "$repo_path" || { echo "ERROR: Could not change directory to $repo_path" >&2; return 1; }

        if git diff --quiet || git diff --cached --quiet; then
            echo "Repository $repo_path is clean, no auto-commit needed."
            return 0
        fi

        echo "Pending changes detected in $repo_path. Attempting auto-commit/push."

        # Stage all changes that are not untracked
        git add .

        # Attempt to commit
        local commit_message="Auto-commit pending changes via stop hook. [$(hostname)]"
        if ! git commit -m "$commit_message"; then
            echo "WARNING: Failed to auto-commit changes in $repo_path. May be due to other unstaged/untracked files or a dirty index for some files." >&2
            echo "Please inspect manually: cd $repo_path && git status" >&2
            # Stash if necessary to clean working directory, but don't lose changes
            # if ! git diff --quiet; then
            #     echo "Attempting to stash remaining uncommitted changes." >&2
            #     git stash push --message "Auto-stashed by stop hook: $repo_path" >&2
            # fi
            return 1 # Indicate failure
        fi

        # Pull and rebase before push
        if ! git pull --rebase origin "$branch_name"; then
            echo "WARNING: Auto-push failed for $repo_path due to rebase conflict. Please resolve manually: cd $repo_path && git status" >&2
            return 1
        fi

        # Push
        if ! git push origin "$branch_name"; then
            echo "WARNING: Auto-push failed for $repo_path. Please push manually: cd $repo_path && git push" >&2
            return 1
        fi
        echo "Successfully auto-committed and pushed pending changes in $repo_path."
        return 0
    }

    # Handle primary project repo
    handle_repo "$PRIMARY_REPO_ROOT"

    # Handle skills repo if it's a separate Git repo (e.g., "~/.claude/skills/")
    # SKILLS_REPO_ROOT="~/.claude/skills" # This path needs to be absolute and correctly resolved by the shell
    # handle_repo "$SKILLS_REPO_ROOT"
    ```
*   **Push Failure Visibility:** The script above ensures push failures are explicitly echoed to `stderr`, making them visible in the agent's log/terminal history.
*   **Session-Brain Step 5:** The `navaigate-session-brain` Step 5 remains the rich, user-triggered wrap-up path, offering more control and context.

---

### **3. Skills + MCP Parity (Claude ↔ Pi)**

**A. Skills Parity**

*   **Shared Directory:** `~/.claude/skills/` remains the single, shared skill library.
*   **Skills Version Control:** `~/.claude/skills/` will itself be a Git repository (e.g., cloned from `forgejo.sttilsolutions.com/sttil-platform/sttil-skills.git`). This ensures all skills are version-controlled, traceable, and synchronized across agents via `git pull` at startup.
*   **`~/.pi/agent/AGENTS.md` Update:**
    *   **Existing Text (to be replaced):** The hand-maintained table mapping skill names to files.
    *   **New Text:** Replace the table with a declarative statement and a guide for skill discovery.
    ```markdown
    # Available Skills

    Pi and Claude Code share a unified, version-controlled skill library located at `~/.claude/skills/` (a Git repository automatically updated at session startup).
    To use a skill, invoke it by its name after loading its respective `SKILL.md` file.

    **Skill Discovery:** To see available skills, consult the contents of `~/.claude/skills/` which is the Git repository cloned from `forgejo.sttilsolutions.com/sttil-platform/sttil-skills.git`.
    ```

**B. MCP Parity (Common Server Configuration)**

*   **Shared MCP Configuration File:** Introduce a git-versioned plain-text file (e.g., `signal/context/shared_mcp_config.json`) within the `signal` repo. This file will define common MCP server connections (e.g., `trilane`).
*   **Harness Load Hook:** Implement a lightweight hook in both Pi and Claude Code's harness configurations that executes on startup/connect:
    *   Reads `signal/context/shared_mcp_config.json`.
    *   Dynamically registers or updates their respective `mcp.json` or in-memory MCP server list.
*   **Non-Shared MCPs:** `graphify` and `use-railway` will continue to be configured directly within Claude Code's specific `mcp.json` as needed, outside the shared file.

---

### **4. Drift-to-Skill Governance (Decision Table)**

This table categorizes recurring manual activities and recommends their automation strategy.

| Manual Protocol                       | Current Behavior                                      | Recommended Automation   | Type          | Build By (Agent) | Notes                                                                                                    |
| :------------------------------------ | :---------------------------------------------------- | :----------------------- | :------------ | :--------------- | :------------------------------------------------------------------------------------------------------- |
| Session Start Git Pulls               | Manual `git pull`, `read` command (per repo)          | **Automated Read Protocol** | Hook          | Pi / Claude      | Applies to `signal` repo and `~/.claude/skills` repo (if separate).                                     |
| Session Wrap-up Auto-commit/push      | Manual `edit`, `commit`, `push` (`navaigate-session-brain` Step 5) | **Automated Write Protocol** | Hook          | Pi / Claude      | Generalized to auto-commit/push all changes in managed Git repos.                                       |
| Git Commit + Push (general)           | Manual `git add`, `commit`, `push`                    | **Skill**                | Skill         | Claude           | A general `/git-push` skill for other work.                                                           |
| Content Calendar Update (NocoDB)      | Manual curl/GUI update                                | **Skill**                | Skill         | Pi / Claude      | "Update NocoDB content calendar" skill (might use `mcp` if NocoDB is an MCP server).                   |
| KG Queries (TriLane)                  | Manual TriLane `mcp` calls (now HTTP `curl`)          | **Skill**                | Skill         | Pi / Claude      | "Query TriLane" skill (e.g., `/trilane-query`), using the documented HTTP API.                         |
| `current-state.md` Staleness Check    | Manual check of `Updated:` timestamp                  | **Automated Read Protocol** | Hook          | Pi / Claude      | Defined in Section 1.C.                                                                                |
| MCP Server Sync                       | Manual `mcp connect` for each agent                   | **Automated MCP Parity** | Hook          | Pi / Claude      | Reads `shared_mcp_config.json` at startup.                                                             |
| New Policy/Doc (e.g., regulatory summary) | Manual creation/updates                               | **Skill**                | Skill         | Pi / Claude      | Skill to draft/update documents (e.g., `/write-policy`, `/summarize-regulation`), committing changes.   |
| Blog Post Creation/Update             | Manual                                                | **Skill Pipeline**       | Workflow      | Pi / Claude      | Automated blog content pipeline, committing posts to blog repo (see Automated Blog Plan).             |

---

### **5. Cleanup / Smoother Workflow**

This outlines the broader housekeeping changes for coherent start/wrap protocols.

*   **Retire `project_next_steps.md`:** This file will no longer be maintained as its purpose is entirely superseded by the `NEXT` section of `current-state.md`. Claude's internal memory should be updated to no longer reference/expect this file.
*   **Demote Embedded "Current State" in `CLAUDE.md`:**
    *   **Existing Text (in `signal/CLAUDE.md`):**
        ```markdown
        ## Current State (embedded — always in context)
        **ACTIVE:** Claude Code built Phase 2 (verified). Pi applied trust fixes, wrote Phase 4 spec, completed Shield competitor recon.
        **NEXT:** Pi designs Shield architecture (standalone compliance product). Claude Code on website review + whitepaper + Phase 2 verification.
        ... (rolling fields) ...
        **At session START:** use this section for state. Then read `context/current-state.md` for the full shared state (decisions, stack details).
        **At WRAP-UP:** update this section AND `context/current-state.md` (keep both in sync).
        ```
    *   **New Text (`signal/CLAUDE.md` startup edit):**
        ```markdown
        ## Current State (deprecated — see `context/current-state.md`)
        **Purpose:** This block is deprecated due to state drift. For the active, canonical project state, always refer to `signal/context/current-state.md`.
        ```
    *   **Implication:** This ensures the harness auto-injects a trivial string for `CLAUDE.md`'s "Current State" reducing token usage and eliminating confusion.
*   **Coherent Start/Wrap Protocol:** The combined read/write protocols (Section 1.C, 1.D, 2.A) form a unified process for both Pi and Claude.
*   **`current-state.md` per Repo:** This design explicitly maintains `context/current-state.md` within the `signal` repo, reinforcing the principle of one state file per logical project repository where agents are active.

---

### **Universal Git Version Control (Golden Nugget Integration)**

This overarching principle applies across all workstreams:

**Principle:** **All human-readable, agent-readable, and machine-actionable artifacts that constitute stable project knowledge, configuration, active state, or output should be managed under Git version control.**

*   **Skills (`~/.claude/skills/`):** Should be a dedicated Git repository. Changes to skills are versioned, traceable, and synchronized via `git pull --rebase` at agent startup.
*   **Internal Policies & Operational Documentation (`docs/compliance/`, etc.):** Critical for auditability and consistency. All such documents (e.g., privacy policies, data-handling procedures, API contracts) must be versioned in Git. Agents (or humans) draft changes, commit, and push.
*   **External Regulatory Summaries & Payer Rule Interpretations (`docs/regulatory_summaries/`, `payer_rules.json`):** Git provides a precise, auditable history of when these interpretations changed, crucial for compliance logic (`Signal` and `Shield`). When a research agent flags an external change, its *processed interpretation* and any derived rule updates are committed to Git with clear commit messages and timestamps.
*   **Automated Blog Content:** Each blog post's content (e.g., Markdown files) and associated metadata (e.g., Schema.org JSON-LD) are versioned in Git. Git pushes can automatically trigger publication via CI/CD.
*   **TriLane as Intelligence Layer:** Git-versioned artifacts serve as concrete, traceable inputs for TriLane. A commit hash can be a direct citation for a `research_insight` in TriLane. TriLane *correlates* these versioned inputs to produce higher-level market projections and strategic guidance, which can then be used by agents to draft blog posts or update other Git-managed documents. This creates a powerful feedback loop where Git provides the auditable granular changes, and TriLane provides the strategic macro-level insights.

This enhancement ensures a robust, trustworthy, and self-maintaining flow of information and work across the entire STTIL Solutions agent ecosystem.

---

### **Deliverable Summary**

This revised design document provides:

1.  **`current-state.md` Schema (`v:1`) and Template:** (Section 1.A)
2.  **Read/Write Protocol Steps:** (Section 1.C, 1.D) ready for inclusion in shared skill startup/wrap-up logic.
3.  **De-duplication Map:** (Section 1.B)
4.  **Recommended Wrap-up Automation (Harness Stop Hook):** (Section 2.A) including conceptualized `update_repo_on_stop.sh` script logic and placement.
5.  **Skills/MCP Parity Fixes:** (Section 3) with exact proposed edits for `~/.pi/agent/AGENTS.md` and mechanism for `shared_mcp_config.json`.
6.  **Drift-to-Skill Decision Table:** (Section 4)
7.  **Exact Startup Edits for `CLAUDE.md`:** (Section 5)
8.  **Golden Nugget Integration:** Explicitly details the **Universal Git Version Control** strategy across all relevant artifact types, solidifying the foundation for STTIL Solutions' agent-driven workflow.

This comprehensive and now finalized design is ready for Claude Code's implementation phase.

---

**Next: Session Brain Update (Wrap-up)**

I will now update `current-state.md` to reflect the completion and finalization of this workflow consolidation design, providing clear next steps for Claude Code to implement it. This will also mark the end of this session.Okay, I understand. The plan is to:

1.  **Integrate the "golden nuggets"** regarding expanded Git version control into the workflow consolidation design document.
2.  **Confirm the updated design is final.**
3.  **Prepare for session wrap-up by updating `current-state.md`** with the final design details and clear next steps for Claude Code.

---

## **Revised Design Document: Workflow Consolidation for STTIL Agents**

**Date:** 2026-06-24 (Revised)
**Purpose:** To eliminate workflow drift, centralize state management, and automate recurring manual protocols across Pi and Claude Code agents operating within STTIL Solutions, leveraging Git as a universal version control system.

---

### **1. The State Contract: `current-state.md` Schema & Protocol**

This section defines the canonical format and interaction protocols for the `current-state.md` file, the single source of truth for volatile project state within a repository.

**A. `current-state.md` Schema (Schema `v:1`)**

```markdown
v:1
# current-state

ACTIVE: [Concise summary of what is actively being worked on by either agent. Limit to 1-2 sentences.]
NEXT (Agent, in order): [Ordered list of next tasks. Each task should specify the responsible agent (Pi/Claude) and a brief description. E.g., (1) Claude: Build Phase 2. (2) Pi: Design X. ]

## Decisions (last X)
- [YYYY-MM-DD]: [Decision summary. Include author tag: [Pi] or [CC]. E.g., - 2026-06-24: Decision A made. [Pi]]
- [YYYY-MM-DD]: [Decision summary. Include author tag: [Pi] or [CC].]

## Open Threads (max 5)
- [Concise summary of an open, unresolved issue or pending task, with context. E.g., - Need to contact Validated Cloud for pricing (deferred until Pi contact). ]
- [Concise summary of an open, unresolved issue or pending task, with context.]

## Stack
- [Key infrastructure components, models, and tools used by the project. Updates infrequently. E.g., - Signal: Patient IDs now use RAP-ID/CSP-ID architecture.]
- [Key infrastructure components, models, and tools used by the project.]

## Tip
- [General advice or reminder relevant to the current project context. E.g., - TriLane Memory is reachable via HTTP not MCP for Pi.]

## Updated: [YYYY-MM-DD] [Brief overall project status/changelog. Include responsible agents. E.g., Updated: 2026-06-24 (Pi: Workflow consolidation design complete; Claude: Built X.)]
```

**B. De-duplication Map (Source of Truth for Information Types)**

*   **`current-state.md`:** Volatile project state (changes every session) – ACTIVE/NEXT tasks, recent decisions, immediate open threads.
*   **`CLAUDE.md`:** Stable project facts (true for months) – What the product is, core PHI rules, run commands, permanent checklists, core technical stack. Demoted, one-line "Current State" pointer.
*   **Claude Memory:** Kisa/CC operating notes, internal thought processes, temporary working notes.
*   **TriLane (Searchable Archive & Intelligence Hub):** History, validated research insights, long-term learning, previous session summaries, **correlated market projections**. TriLane *consumes* Git-managed versioned artifacts as input for its intelligence.

**C. Read Protocol (Agent Startup/Resume)**

1.  **`git pull --rebase origin <current_branch>`:** Fetch latest changes and rebase local branch to ensure working on the freshest state for the primary repository.
2.  **`git pull --rebase origin <skills_repo_branch>`:** If skills are in a separate Git repo, update them.
3.  **Read `signal/context/current-state.md`:** Load file contents into agent's short-term context.
4.  **Surface Staleness Signal:** Compare current date to the `Updated:` timestamp in `current-state.md`. If `current-state.md` is older than 24 hours, issue a warning to the user: "Warning: Project state last updated X days ago. Consider reviewing recent activity." *Constraint: Lean, token-conscious – this is a simple check, not a deep diff.*

**D. Write Protocol (Agent Wrap-up/Commit)**

1.  **Single Mutable Head:** Agents may only directly modify the `ACTIVE` and `NEXT` sections.
2.  **Append-Only Decisions Log:** All new decisions must be appended to the `Decisions` section, prefixed with `[YYYY-MM-DD]: [Decision Summary. [Author Tag]]`.
3.  **Update `Updated:` Timestamp:** The `Updated:` line at the bottom must be updated to the current date and a brief status summary.
4.  **Rebase-and-Commit Cycle (General for any Git-managed file):**
    *   Immediately before writing to *any* Git-managed file (e.g., `current-state.md`, `SKILL.md`, `payer_rules.json`, blog posts), execute `git pull --rebase origin <current_branch>`.
    *   If a conflict occurs, the *last writer hand-merges* their changes. (`-X ours` and lock files are forbidden).
    *   Write changes to the file(s).
    *   `git add <path/to/modified/file(s)>`.
    *   `git commit -m "Update [file(s)] by [Author Tag]: [brief summary of changes]"`
    *   `git push origin <current_branch>`.
5.  **Visibility for Push Failures:** Push failures must be reported directly to the console/session output, never swallowed silently.

---

### **2. Reliable Wrap-up Commit + Push (Automation Design)**

To prevent state loss due to crashes or skipped wrap-ups.

**A. Recommended Mechanism: Harness Stop Hook**

The primary mechanism will be a harness-level stop hook, which executes reliable git operations regardless of user-triggered wrap-up or session termination.

*   **Placement:**
    *   **Pi:** `~/.pi/agent/settings.json` (or equivalent harness configuration).
    *   **Claude Code:** `~/.claude/agent/settings.json` (or equivalent harness configuration).
*   **Action:** Execute a script (e.g., `update_repo_on_stop.sh`) when the agent session stops. This script will generalize the `current-state.md` logic to any modified file within the working repository.
*   **`update_repo_on_stop.sh` Script Logic (Conceptual):**
    ```bash
    #!/bin/bash
    PRIMARY_REPO_ROOT="/Users/sttil-solutions/projects/signal" # Target the main project repo

    # --- Generic Git Auto-Commit & Push Logic ---
    # This script is a generalized abstraction. Actual implementation needs to identify
    # which Git repositories are active (e.g., "$PRIMARY_REPO_ROOT", "~/.claude/skills/")
    # and perform operations for each.

    handle_repo() {
        local repo_path=$1
        local branch_name="main" # Or dynamically determine current branch
        cd "$repo_path" || { echo "ERROR: Could not change directory to $repo_path" >&2; return 1; }

        if git diff --quiet || git diff --cached --quiet; then
            echo "Repository $repo_path is clean, no auto-commit needed."
            return 0
        fi

        echo "Pending changes detected in $repo_path. Attempting auto-commit/push."

        # Stage all changes that are not untracked
        git add .

        # Attempt to commit
        local commit_message="Auto-commit pending changes via stop hook. [$(hostname)]"
        if ! git commit -m "$commit_message"; then
            echo "WARNING: Failed to auto-commit changes in $repo_path. May be due to other unstaged/untracked files or a dirty index for some files." >&2
            echo "Please inspect manually: cd $repo_path && git status" >&2
            # Stash if necessary to clean working directory, but don't lose changes
            # if ! git diff --quiet; then
            #     echo "Attempting to stash remaining uncommitted changes." >&2
            #     git stash push --message "Auto-stashed by stop hook: $repo_path" >&2
            # fi
            return 1 # Indicate failure
        fi

        # Pull and rebase before push
        if ! git pull --rebase origin "$branch_name"; then
            echo "WARNING: Auto-push failed for $repo_path due to rebase conflict. Please resolve manually: cd $repo_path && git status" >&2
            return 1
        fi

        # Push
        if ! git push origin "$branch_name"; then
            echo "WARNING: Auto-push failed for $repo_path. Please push manually: cd $repo_path && git push" >&2
            return 1
        fi
        echo "Successfully auto-committed and pushed pending changes in $repo_path."
        return 0
    }

    # Handle primary project repo
    handle_repo "$PRIMARY_REPO_ROOT"

    # Handle skills repo if it's a separate Git repo (e.g., "~/.claude/skills/")
    # SKILLS_REPO_ROOT="~/.claude/skills" # This path needs to be absolute and correctly resolved by the shell
    # handle_repo "$SKILLS_REPO_ROOT"
    ```
*   **Push Failure Visibility:** The script above ensures push failures are explicitly echoed to `stderr`, making them visible in the agent's log/terminal history.
*   **Session-Brain Step 5:** The `navaigate-session-brain` Step 5 remains the rich, user-triggered wrap-up path, offering more control and context.

---

### **3. Skills + MCP Parity (Claude ↔ Pi)**

**A. Skills Parity**

*   **Shared Directory:** `~/.claude/skills/` remains the single, shared skill library.
*   **Skills Version Control:** `~/.claude/skills/` will itself be a Git repository (e.g., cloned from `forgejo.sttilsolutions.com/sttil-platform/sttil-skills.git`). This ensures all skills are version-controlled, traceable, and synchronized across agents via `git pull` at startup.
*   **`~/.pi/agent/AGENTS.md` Update:**
    *   **Existing Text (to be replaced):** The hand-maintained table mapping skill names to files.
    *   **New Text:** Replace the table with a declarative statement and a guide for skill discovery.
    ```markdown
    # Available Skills

    Pi and Claude Code share a unified, version-controlled skill library located at `~/.claude/skills/` (a Git repository automatically updated at session startup).
    To use a skill, invoke it by its name after loading its respective `SKILL.md` file.

    **Skill Discovery:** To see available skills, consult the contents of `~/.claude/skills/` which is the Git repository cloned from `forgejo.sttilsolutions.com/sttil-platform/sttil-skills.git`.
    ```

**B. MCP Parity (Common Server Configuration)**

*   **Shared MCP Configuration File:** Introduce a git-versioned plain-text file (e.g., `signal/context/shared_mcp_config.json`) within the `signal` repo. This file will define common MCP server connections (e.g., `trilane`).
*   **Harness Load Hook:** Implement a lightweight hook in both Pi and Claude Code's harness configurations that executes on startup/connect:
    *   Reads `signal/context/shared_mcp_config.json`.
    *   Dynamically registers or updates their respective `mcp.json` or in-memory MCP server list.
*   **Non-Shared MCPs:** `graphify` and `use-railway` will continue to be configured directly within Claude Code's specific `mcp.json` as needed, outside the shared file.

---

### **4. Drift-to-Skill Governance (Decision Table)**

This table categorizes recurring manual activities and recommends their automation strategy.

| Manual Protocol                       | Current Behavior                                      | Recommended Automation   | Type          | Build By (Agent) | Notes                                                                                                    |
| :------------------------------------ | :---------------------------------------------------- | :----------------------- | :------------ | :--------------- | :------------------------------------------------------------------------------------------------------- |
| Session Start Git Pulls               | Manual `git pull`, `read` command (per repo)          | **Automated Read Protocol** | Hook          | Pi / Claude      | Applies to `signal` repo and `~/.claude/skills` repo (if separate).                                     |
| Session Wrap-up Auto-commit/push      | Manual `edit`, `commit`, `push` (`navaigate-session-brain` Step 5) | **Automated Write Protocol** | Hook          | Pi / Claude      | Generalized to auto-commit/push all changes in managed Git repos.                                       |
| Git Commit + Push (general)           | Manual `git add`, `commit`, `push`                    | **Skill**                | Skill         | Claude           | A general `/git-push` skill for other work.                                                           |
| Content Calendar Update (NocoDB)      | Manual curl/GUI update                                | **Skill**                | Skill         | Pi / Claude      | "Update NocoDB content calendar" skill (might use `mcp` if NocoDB is an MCP server).                   |
| KG Queries (TriLane)                  | Manual TriLane `mcp` calls (now HTTP `curl`)          | **Skill**                | Skill         | Pi / Claude      | "Query TriLane" skill (e.g., `/trilane-query`), using the documented HTTP API.                         |
| `current-state.md` Staleness Check    | Manual check of `Updated:` timestamp                  | **Automated Read Protocol** | Hook          | Pi / Claude      | Defined in Section 1.C.                                                                                |
| MCP Server Sync                       | Manual `mcp connect` for each agent                   | **Automated MCP Parity** | Hook          | Pi / Claude      | Reads `shared_mcp_config.json` at startup.                                                             |
| New Policy/Doc (e.g., regulatory summary) | Manual creation/updates                               | **Skill**                | Skill         | Pi / Claude      | Skill to draft/update documents (e.g., `/write-policy`, `/summarize-regulation`), committing changes.   |
| Blog Post Creation/Update             | Manual                                                | **Skill Pipeline**       | Workflow      | Pi / Claude      | Automated blog content pipeline, committing posts to blog repo (see Automated Blog Plan).             |

---

### **5. Cleanup / Smoother Workflow**

This outlines the broader housekeeping changes for coherent start/wrap protocols.

*   **Retire `project_next_steps.md`:** This file will no longer be maintained as its purpose is entirely superseded by the `NEXT` section of `current-state.md`. Claude's internal memory should be updated to no longer reference/expect this file.
*   **Demote Embedded "Current State" in `CLAUDE.md`:**
    *   **Existing Text (in `signal/CLAUDE.md`):**
        ```markdown
        ## Current State (embedded — always in context)
        **ACTIVE:** Claude Code built Phase 2 (verified). Pi applied trust fixes, wrote Phase 4 spec, completed Shield competitor recon.
        **NEXT:** Pi designs Shield architecture (standalone compliance product). Claude Code on website review + whitepaper + Phase 2 verification.
        ... (rolling fields) ...
        **At session START:** use this section for state. Then read `context/current-state.md` for the full shared state (decisions, stack details).
        **At WRAP-UP:** update this section AND `context/current-state.md` (keep both in sync).
        ```
    *   **New Text (`signal/CLAUDE.md` startup edit):**
        ```markdown
        ## Current State (deprecated — see `context/current-state.md`)
        **Purpose:** This block is deprecated due to state drift. For the active, canonical project state, always refer to `signal/context/current-state.md`.
        ```
    *   **Implication:** This ensures the harness auto-injects a trivial string for `CLAUDE.md`'s "Current State" reducing token usage and eliminating confusion.
*   **Coherent Start/Wrap Protocol:** The combined read/write protocols (Section 1.C, 1.D, 2.A) form a unified process for both Pi and Claude.
*   **`current-state.md` per Repo:** This design explicitly maintains `context/current-state.md` within the `signal` repo, reinforcing the principle of one state file per logical project repository where agents are active.

---

### **Universal Git Version Control (Golden Nugget Integration)**

This overarching principle applies across all workstreams:

**Principle:** **All human-readable, agent-readable, and machine-actionable artifacts that constitute stable project knowledge, configuration, active state, or output should be managed under Git version control.**

*   **Skills (`~/.claude/skills/`):** Should be a dedicated Git repository. Changes to skills are versioned, traceable, and synchronized across agents via `git pull --rebase` at agent startup.
*   **Internal Policies & Operational Documentation (`docs/compliance/`, etc.):** Critical for auditability and consistency. All such documents (e.g., privacy policies, data-handling procedures, API contracts) must be versioned in Git. Agents (or humans) draft changes, commit, and push.
*   **External Regulatory Summaries & Payer Rule Interpretations (`docs/regulatory_summaries/`, `payer_rules.json`):** Git provides a precise, auditable history of when these interpretations changed, crucial for compliance logic (`Signal` and `Shield`). When a research agent flags an external change, its *processed interpretation* and any derived rule updates are committed to Git with clear commit messages and timestamps.
*   **Automated Blog Content:** Each blog post's content (e.g., Markdown files) and associated metadata (e.g., Schema.org JSON-LD) are versioned in Git. Git pushes can automatically trigger publication via CI/CD.
*   **TriLane as Intelligence Layer:** Git-versioned artifacts serve as concrete, traceable inputs for TriLane. A commit hash can be a direct citation for a `research_insight` in TriLane. TriLane *correlates* these versioned inputs to produce higher-level market projections and strategic guidance, which can then be used by agents to draft blog posts or update other Git-managed documents. This creates a powerful feedback loop where Git provides the auditable granular changes, and TriLane provides the strategic macro-level insights.

This enhancement ensures a robust, trustworthy, and self-maintaining flow of information and work across the entire STTIL Solutions agent ecosystem.

---

### **Deliverable Summary**

This revised design document provides:

1.  **`current-state.md` Schema (`v:1`) and Template:** (Section 1.A)
2.  **Read/Write Protocol Steps:** (Section 1.C, 1.D) ready for inclusion in shared skill startup/wrap-up logic.
3.  **De-duplication Map:** (Section 1.B)
4.  **Recommended Wrap-up Automation (Harness Stop Hook):** (Section 2.A) including conceptualized `update_repo_on_stop.sh` script logic and placement.
5.  **Skills/MCP Parity Fixes:** (Section 3) with exact proposed edits for `~/.pi/agent/AGENTS.md` and mechanism for `shared_mcp_config.json`.
6.  **Drift-to-Skill Decision Table:** (Section 4)
7.  **Exact Startup Edits for `CLAUDE.md`:** (Section 5)
8.  **Golden Nugget Integration:** Explicitly details the **Universal Git Version Control** strategy across all relevant artifact types, solidifying the foundation for STTIL Solutions' agent-driven workflow.

This comprehensive and now finalized design is ready for Claude Code's implementation phase.

---

**Next: Session Brain Update (Wrap-up)**

I will now update `current-state.md` to reflect the completion and finalization of this workflow consolidation design, providing clear next steps for Claude Code to implement it. This will also mark the end of this session.

---

I've made the updates to `current-state.md` regarding the workflow consolidation design, but part of the final "Updated" timestamp edit failed due to a mismatch. I need to re-read the `current-state.md` to get the exact `oldText` for the `Updated:` line and then apply the final change.

---

The `current-state.md` is now fully updated, reflecting the completion and finalization of the workflow consolidation design, including the universal Git versioning strategy. The next steps for Claude Code (implementing the workflow consolidation and building the readiness model) are clearly documented.

This formally concludes my work on this goal.