@cxi-lmai/ci-agent-platform 3.0.1 → 3.1.0

package/README.md

@@ -8,7 +8,8 @@ checks the result. The input is a spec, the output is code. Details in
 [docs/issue-to-code.md](https://gitlab.com/cxi-lmai/ci-agent-platform/-/blob/main/docs/issue-to-code.md).
 
 - **15 generic agents**: triage, coding, review, tests, docs, release.
-- **7 skills**, configured per project.
+- **12 skills**, configured per project.
+- **13 top-level runner scripts** and **65 CI `PIPE_*` variables**.
 - **Project specifics live outside the agents**, in `.claude/pipeline-config.md` and `PIPE_*` variables.
 
 > [!NOTE]
@@ -16,7 +17,11 @@ checks the result. The input is a spec, the output is code. Details in
 > - the **review loop** (`review`, `review-fix`, `test-fix`, and the shared escalation `/postmortem-mr`),
 > - the **issue-to-code loop** (`orchestrate`, `code`, skills `triage-issue` and `implement-issue`).
 >
-> The other agents are installed too but have no CI job of their own. You invoke them by hand from the command line.
+> Seven opt-in jobs are wired by the GitLab CI template and are off by default:
+> `docs-sync`, `coverage-ratchet`, `cve-fix`, `e2e-test-gen`, `codebase-audit`,
+> `agent-architect`, and `metrics-snapshot`.
+> The other agents are installed too but have no CI job of their own. You invoke
+> them by hand from the command line.
 
 > [!CAUTION]
 > The coder runs with `--dangerously-skip-permissions` and treats issue content
@@ -44,6 +49,7 @@ checks the result. The input is a spec, the output is code. Details in
 - [How it fits together](#how-it-fits-together)
 - [Possible extensions: changing agents and skills](#possible-extensions-changing-agents-and-skills)
 - [Reference: secrets and variables](https://gitlab.com/cxi-lmai/ci-agent-platform/-/blob/main/docs/reference-variables.md)
+- [Reference: metrics and snapshots](https://gitlab.com/cxi-lmai/ci-agent-platform/-/blob/main/docs/metrics.md)
 
 ## The full cycle
 
@@ -67,15 +73,17 @@ untouched file from one the project has edited.
 ├── payload/                              # everything that ships into your repo
 │   ├── INSTALL.md                        #   instructions for Claude, copied to your root
 │   ├── agents/                           #   15 agent definitions (.md)
-│   ├── skills/                           #   7 skills (folder with a SKILL.md)
+│   ├── agents-omp/                       #   15 omp-native agent definitions (.md)
+│   ├── skills/                           #   12 skills (folder with a SKILL.md)
 │   ├── templates/                        #   3 templates: config, spec issue, suppressions
 │   └── ci-templates/                     #   CI jobs and runner scripts (wired by the wizard)
 │       ├── claude-pipeline.gitlab-ci.yml #     GitLab CI template
 │       ├── github/                       #     GitHub Actions workflows
-│       └── scripts/                      #     shared runner scripts (both platforms)
+│       └── scripts/                      #     13 top-level runner scripts (both platforms)
 ├── docs/                                 # supplementary documentation, not shipped
 │   ├── diagrams/
 │   ├── issue-to-code.md
+│   ├── metrics.md
 │   ├── reference-variables.md
 │   └── superpowers/                      #   this repository's own plans and specs
 ├── examples/unitconv/                    # a filled-in example config, not shipped

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cxi-lmai/ci-agent-platform",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Autonomous dev pipeline on plain GitLab CI or GitHub Actions, driven by Claude Code. A labeled issue goes in, an open merge request comes out.",
   "keywords": [
     "claude",
@@ -41,7 +41,7 @@
   "scripts": {
     "test": "npm run test:lint && npm run test:gates && npm run test:unit",
     "test:lint": "shellcheck -S warning test/*.sh payload/ci-templates/scripts/*.sh payload/ci-templates/scripts/lib/*.sh",
-    "test:gates": "bash test/coherence-gate.sh all && bash test/restructure-invariants.sh verify && bash test/harness-dispatch.sh all",
+    "test:gates": "bash test/coherence-gate.sh all && bash test/restructure-invariants.sh verify && bash test/harness-dispatch.sh all && bash test/failure-notice.sh && bash test/decompose-validation.sh && bash test/platform-helpers.sh && bash test/coverage-ratchet.sh && bash test/cve-fix.sh && bash test/e2e-test-gen.sh && bash test/agent-architect.sh",
     "test:unit": "node --test \"test/*.test.mjs\""
   }
 }

package/payload/INSTALL.md

@@ -56,7 +56,13 @@ never has to enter this conversation.
    The reviewer agents read it on every run, and without the file they read a
    missing path on a repository that has just been told the pipeline is
    installed.
-4. Copy the CI template and runner scripts. The runner scripts go to the same
+4. Create `.claude/memory/MEMORY.md` from
+   `<src>/templates/memory-index.template.md` **when it does not already
+   exist**, and never touch it when it does: it is a project-owned index.
+   The three tiers are `CLAUDE.md` for hardwired instructions and an index,
+   `docs/` for long-term patterns and architecture, and `.claude/memory/` for
+   active project state and cross-agent signals.
+5. Copy the CI template and runner scripts. The runner scripts go to the same
    place on both platforms, `.claude-pipeline/scripts/`, which is the default
    `PIPE_SCRIPTS_DIR` the CI template already points at. Only the CI definition
    differs:
@@ -67,7 +73,7 @@ never has to enter this conversation.
      `<src>/ci-templates/scripts/` to `.claude-pipeline/scripts/`. Ask before
      replacing a workflow file that already exists; `claude-pipeline.yml` is an
      ordinary enough name to collide.
-5. Check `.gitignore`. The bootstrapper already added `.ci-agent-platform-src/`,
+6. Check `.gitignore`. The bootstrapper already added `.ci-agent-platform-src/`,
    `.claude/onboarding-state.md` (the wizard's progress marker, see the skill's
    ground rules) and `build/pipeline/` (the default `PIPE_CONTEXT_DIR`, the
    runner's working files). Add any that are missing. The source folder is a

package/payload/ci-templates/claude-pipeline.gitlab-ci.yml

@@ -82,12 +82,71 @@ variables:
   PIPE_VERIFY_CMD: ""                   # compile + unit tests, run after a fix
   PIPE_COMPILE_CMD: ""                  # compile only (defaults to PIPE_VERIFY_CMD)
   PIPE_TEST_REPORT_GLOB: ""             # e.g. build/test-results/**/TEST-*.xml
+  PIPE_COVERAGE_RATCHET: "0"            # set to "1" to gate MR coverage against the target branch
+  PIPE_COVERAGE_REPORT: ""              # path to the coverage report generated by the project
+  PIPE_COVERAGE_REPORT_KIND: "jacoco"   # report parser; only jacoco is currently supported
   PIPE_COVERAGE_SIGNAL: ""              # path to a coverage-drop signal file
+  # To enable the gate, configure both report and signal paths. Its baseline is
+  # the target branch's latest successful pipeline `coverage` value; the
+  # project's test job must publish that value (through `coverage:` or a report)
+  # or the baseline is 0 and no drop can fire.
+
+
+  # --- CVE remediation (optional) -------------------------------------------
+  # A project-local security scanner supplies PIPE_CVE_LIST. The platform does
+  # not select a scanner or prescribe its severity filtering.
+  PIPE_CVE_FIX: "0"                     # set to "1" to enable CVE remediation on MR/PR pipelines
+  PIPE_DEPENDENCY_MANIFEST: "build.gradle"
+  PIPE_CVE_SUPPRESSIONS: "owasp-suppressions.xml"
+
+  # --- Issue-driven E2E test generation (optional) --------------------------
+  # A scheduled run selects test-ready issues. PIPE_E2E_VERIFY_CMD must be the
+  # project's explicit E2E command and accept the generated test path as its
+  # final argument. This generic template does not choose a framework, runtime
+  # image, install command, credentials, or URL.
+  PIPE_E2E_TEST_GEN: "0"
+  PIPE_LABEL_TESTREADY: "test-ready"
+  PIPE_LABEL_E2E_SCOPE: ""
+  PIPE_E2E_TEST_DIR: "e2e/tests"
+  PIPE_E2E_BASE_URL: ""
+  PIPE_E2E_VERIFY_CMD: ""
+
+  # --- Documentation sync (optional) ----------------------------------------
+  PIPE_DOCS_SYNC: "0"                   # set to "1" to enable the docs-sync job
+  PIPE_DOCS_ROOTS: "docs,CLAUDE.md,.claude/memory"   # paths docs-sync may edit and commit
+
+  # --- Codebase audit (optional) ---------------------------------------------
+  PIPE_CODEBASE_AUDIT: "0"              # set to "1" in a schedule to run the periodic audit
+  PIPE_LABEL_AUDIT: "codebase-audit"    # label on the findings issue and its auto-fix MR/PR
+
+  # --- Agent architect (optional) --------------------------------------------
+  # A scheduled evidence-backed review of agent definitions. Default to
+  # report-only; set this false or 0 only after reviewing a dry-run report.
+  PIPE_AGENT_ARCHITECT: "0"
+  PIPE_ARCHITECT_WINDOW_DAYS: "7"
+  PIPE_ARCHITECT_DRY_RUN: "true"
+  PIPE_LABEL_IMPROVEMENT: "pipe-improvement"
+
+  # --- Metrics aggregation (optional) ---------------------------------------
+  PIPE_METRICS_SNAPSHOT: "0"            # set to "1" in a schedule to aggregate
+  PIPE_METRICS_OUTPUT_DIR: "data/metrics/snapshots"
+  PIPE_METRICS_WINDOW_DAYS: "1"
+  PIPE_METRICS_COMMIT_REPO: "false"     # "true" also commits the snapshot
+  PIPE_METRICS_REVIEW_AGENTS: "code-reviewer,review-verdict,review-fix"
+  PIPE_METRICS_DEFECT_REVERT: "Reverts !"
+  PIPE_METRICS_DEFECT_REGRESSION: "Fixes regression from !"
+  PIPE_METRICS_DEFECT_REINTRODUCE: "Reintroduces work from !"
+  PIPE_METRICS_SNAPSHOT_DATE: ""        # override the snapshot date, replay only
+  PIPE_METRICS_RAW_DIR: ""              # OFFLINE only: pre-staged records
+  PIPE_METRICS_MRS_FILE: ""             # OFFLINE only: merge request list
 
   # --- Commit subjects (drive the fix-loop cap counters) ---------------------
   PIPE_COMMIT_TESTFIX: "Fix test errors"
   PIPE_COMMIT_REVIEWFIX: "Fix review findings"
   PIPE_COMMIT_COVERAGE: "Add coverage tests"
+  PIPE_COMMIT_DOCSSYNC: "Update docs per docs-sync findings"
+  PIPE_COMMIT_AUDIT: "docs: apply convention audit findings"
+  PIPE_COMMIT_CVEFIX: "Update dependencies to resolve CVEs"
 
   # --- Caps + models ---------------------------------------------------------
   PIPE_FIX_LOOP_CAP: "2"
@@ -99,6 +158,7 @@ variables:
   # --- Result files (defaults live under PIPE_CONTEXT_DIR) --------------------
   PIPE_RESULT_REVIEW: "$PIPE_CONTEXT_DIR/code-review-result.txt"
   PIPE_RESULT_REVIEWFIX: "$PIPE_CONTEXT_DIR/review-fix-result.json"
+  PIPE_RESULT_DOCSSYNC: "$PIPE_CONTEXT_DIR/docs-sync.json"
 
 # --- Hidden base job: shared config + runtime variable mapping ---------------
 # Maps GitLab's CI_ runtime variables onto the PIPE_ names the scripts read, and
@@ -123,6 +183,14 @@ variables:
     # ship it, plain docker images (node:22-bookworm) do not, so install it
     # here (finding from the GitLab pilot: silent HTTP 400s + exit 127).
     - command -v jq >/dev/null 2>&1 || (apt-get update -qq && apt-get install -y -qq jq)
+    # node:22-bookworm does not include xmllint. Install it only for the
+    # opt-in ratchet. Unsupported custom-image installation stays non-fatal so
+    # coverage-ratchet can issue its explicit missing-tool error when it runs.
+    - |
+      if [ "$PIPE_COVERAGE_RATCHET" = "1" ] && ! command -v xmllint >/dev/null 2>&1; then
+        command -v apt-get >/dev/null 2>&1 &&
+          (apt-get update -qq && apt-get install -y -qq libxml2-utils) || true
+      fi
     - |
       if [ "$PIPE_HARNESS" = "omp" ]; then
         command -v omp >/dev/null 2>&1 || npm install -g @oh-my-pi/pi-coding-agent
@@ -176,6 +244,42 @@ review-fix:
     - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $PIPE_TARGET_BRANCH && $CI_MERGE_REQUEST_LABELS =~ $PIPE_LABEL_WIP'
       when: on_failure
 
+# =============================================================================
+# docs-sync: check whether the MR's code changes need documentation updates.
+# Optional and off by default, because it spends tokens on every MR: enable it
+# by setting PIPE_DOCS_SYNC=1. On a wip MR the agent applies the updates and
+# this job commits and pushes them; on any other MR it posts an advisory
+# comment only. It never gates the pipeline.
+# =============================================================================
+docs-sync:
+  extends: .claude-base
+  stage: review
+  timeout: 30m
+  variables:
+    GIT_STRATEGY: clone
+  script:
+    - bash "$PIPE_SCRIPTS_DIR/docs-sync.sh"
+  allow_failure: true
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $PIPE_TARGET_BRANCH && $PIPE_DOCS_SYNC == "1"'
+
+# =============================================================================
+# cve-fix: optionally remediate HIGH/CRITICAL vulnerabilities supplied by a
+# project-local scanner in PIPE_CVE_LIST. The coder only runs on an autonomous
+# MR/PR; human-authored MRs receive a manual-update comment instead.
+# =============================================================================
+cve-fix:
+  extends: .claude-base
+  stage: review
+  timeout: 45m
+  variables:
+    GIT_STRATEGY: clone
+  script:
+    - bash "$PIPE_SCRIPTS_DIR/cve-fix.sh"
+  allow_failure: true
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $PIPE_TARGET_BRANCH && $PIPE_CVE_FIX == "1"'
+
 # =============================================================================
 # orchestrate: triage ready issues and fire the coder (issue -> code loop).
 # Runs on a scheduled pipeline that sets PIPE_ORCHESTRATE=1 (kept off by default
@@ -198,6 +302,45 @@ orchestrate:
     - if: '$CI_PIPELINE_SOURCE == "web" && $PIPE_ORCHESTRATE == "1"'
 
 # =============================================================================
+# codebase-audit: periodic convention-drift scan. Scans recently merged MRs/PRs
+# and compares patterns against documented conventions via the codebase-auditor
+# agent. Posts findings as an issue labeled $PIPE_LABEL_AUDIT. If the report
+# suggests documentation updates and a push-capable identity is configured,
+# spawns the coder agent to implement them and opens an MR/PR.
+# Opt-in and off by default: enable by setting PIPE_CODEBASE_AUDIT=1 on a
+# separate scheduled pipeline (e.g. monthly).
+# =============================================================================
+codebase-audit:
+  extends: .claude-base
+  stage: orchestrate
+  timeout: 30m
+  variables:
+    GIT_STRATEGY: clone
+  script:
+    - bash "$PIPE_SCRIPTS_DIR/codebase-audit.sh"
+  allow_failure: true
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "schedule" && $PIPE_CODEBASE_AUDIT == "1"'
+
+
+# =============================================================================
+# agent-architect: weekly, evidence-backed improvement proposals for shipped
+# agent definitions. Schedule-only and opt-in because it spends model tokens;
+# set DRY_RUN=true for an initial report-only trial.
+# =============================================================================
+agent-architect:
+  extends: .claude-base
+  stage: review
+  timeout: 30m
+  variables:
+    GIT_STRATEGY: clone
+    DRY_RUN: "$PIPE_ARCHITECT_DRY_RUN"
+  script:
+    - bash "$PIPE_SCRIPTS_DIR/agent-architect.sh"
+  allow_failure: true
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "schedule" && $PIPE_AGENT_ARCHITECT == "1"'
+# =============================================================================
 # code: implement one issue and open the MR (issue -> code loop).
 # Triggered by orchestrate via the Pipeline Trigger API with CODER_ISSUE and
 # CODER_BRANCH set. The coder agent runs with --dangerously-skip-permissions on
@@ -214,6 +357,48 @@ code:
   rules:
     - if: '$CODER_ISSUE && $CODER_BRANCH'
 
+# =============================================================================
+# e2e-test-gen: scheduled, opt-in generation for issues carrying the configured
+# test-ready label (and optional E2E scope label). The project supplies the
+# verification command and any framework/runtime setup through its own CI.
+# =============================================================================
+e2e-test-gen:
+  extends: .claude-base
+  stage: test
+  timeout: 45m
+  variables:
+    GIT_STRATEGY: clone
+  script:
+    - bash "$PIPE_SCRIPTS_DIR/e2e-test-gen.sh"
+  allow_failure: true
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "schedule" && $PIPE_E2E_TEST_GEN == "1"'
+
+# =============================================================================
+# coverage-ratchet: optional MR coverage gate. Reads the project's coverage
+# artifact and, for a wip coverage drop, fails into test-fix with its signal.
+# =============================================================================
+coverage-ratchet:
+  extends: .claude-base
+  stage: test
+  needs:
+    - job: test
+      artifacts: true
+      optional: true
+  variables:
+    GIT_STRATEGY: clone
+  script:
+    - bash "$PIPE_SCRIPTS_DIR/coverage-ratchet.sh"
+  artifacts:
+    paths:
+      - $PIPE_CONTEXT_DIR/metrics/
+      - $PIPE_COVERAGE_SIGNAL
+    when: always
+    expire_in: 60 days
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $PIPE_TARGET_BRANCH && $PIPE_COVERAGE_RATCHET == "1"'
+      when: always
+
 # =============================================================================
 # test-fix: on failure of YOUR project's `test` job, on a wip MR, fix tests /
 # compilation / coverage. Consumes the test job's artifacts via needs.
@@ -226,6 +411,9 @@ test-fix:
     - job: test
       artifacts: true
       optional: true
+    - job: coverage-ratchet
+      artifacts: true
+      optional: true
   variables:
     GIT_STRATEGY: clone
   script:
@@ -234,3 +422,25 @@ test-fix:
   rules:
     - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $PIPE_TARGET_BRANCH && $CI_MERGE_REQUEST_LABELS =~ $PIPE_LABEL_WIP'
       when: on_failure
+
+# =============================================================================
+# metrics-snapshot: aggregates one day of pipeline metrics into a JSON snapshot.
+# Optional and off by default. Enable by setting PIPE_METRICS_SNAPSHOT=1 on a
+# scheduled pipeline. Writes an artifact; set PIPE_METRICS_COMMIT_REPO=true to
+# also commit the snapshot to the target branch.
+# =============================================================================
+metrics-snapshot:
+  extends: .claude-base
+  stage: orchestrate
+  timeout: 30m
+  variables:
+    GIT_DEPTH: "0"
+  script:
+    - bash "$PIPE_SCRIPTS_DIR/metrics-snapshot.sh"
+  artifacts:
+    paths:
+      - $PIPE_METRICS_OUTPUT_DIR/
+    when: always
+    expire_in: 90 days
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "schedule" && $PIPE_METRICS_SNAPSHOT == "1"'

package/payload/ci-templates/scripts/agent-architect.sh

@@ -0,0 +1,233 @@
+#!/bin/bash
+# Runner for the opt-in weekly agent-architect job. It collects bounded,
+# forge-neutral evidence; the /agent-architect skill performs the analysis.
+set -e
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib/pipeline-common.sh
+source "$SCRIPT_DIR/lib/pipeline-common.sh"
+# shellcheck source=lib/issue-loop.sh
+source "$SCRIPT_DIR/lib/issue-loop.sh"
+pipe_defaults
+
+ARCHITECT_ENV="$PIPE_CONTEXT_DIR/architect.env"
+CONTEXT_FILE="$PIPE_CONTEXT_DIR/architect-context.md"
+REPORT_FILE="$PIPE_CONTEXT_DIR/architect-report.md"
+PROPOSALS_FILE="$PIPE_CONTEXT_DIR/architect-proposals.json"
+if [ "${DRY_RUN+x}" = x ]; then
+  DRY_RUN="$DRY_RUN"
+else
+  DRY_RUN="${PIPE_ARCHITECT_DRY_RUN:-true}"
+fi
+WINDOW_DAYS="${PIPE_ARCHITECT_WINDOW_DAYS:-7}"
+
+write_marker() {
+  printf 'ARCHITECT_STATUS=%s\nARCHITECT_PROPOSALS=%s\nARCHITECT_ISSUES_FILED=%s\n' \
+    "$1" "$2" "$3" > "$ARCHITECT_ENV"
+}
+
+if [ "${PIPE_AGENT_ARCHITECT:-0}" != "1" ]; then
+  write_marker disabled 0 0
+  pipe_log "Agent architect is disabled"
+  exit 0
+fi
+
+if ! [[ "$WINDOW_DAYS" =~ ^[1-9][0-9]*$ ]]; then
+  write_marker invalid_window 0 0
+  pipe_log "ERROR: PIPE_ARCHITECT_WINDOW_DAYS must be a positive integer"
+  exit 1
+fi
+
+if date --version >/dev/null 2>&1; then
+  SINCE=$(date -u -d "$WINDOW_DAYS days ago" '+%Y-%m-%dT%H:%M:%SZ')
+else
+  SINCE=$(date -u -v-"$WINDOW_DAYS"d '+%Y-%m-%dT%H:%M:%SZ')
+fi
+WEEK_TAG=$(date -u +%G-W%V)
+
+# The updated-since helper has the window semantics the source job needs. It
+# returns both states, so retain only merged MRs/PRs targeting this project’s
+# configured integration branch and cap the prompt input before any per-item IO.
+RECENT_MRS=$(platform_merge_requests_updated_since "$SINCE") || {
+  write_marker fetch_failed 0 0
+  pipe_log "ERROR: failed to fetch recently updated MRs/PRs"
+  exit 1
+}
+MRS=$(jq -c --arg target "$PIPE_TARGET_BRANCH" \
+  '[.[] | select(.state == "merged" and .target_branch == $target)] | .[0:30]' <<< "$RECENT_MRS") || {
+  write_marker fetch_failed 0 0
+  pipe_log "ERROR: unexpected merged MR/PR response"
+  exit 1
+}
+MR_COUNT=$(jq -r 'length' <<< "$MRS")
+if ! [[ "$MR_COUNT" =~ ^[0-9]+$ ]]; then
+  write_marker fetch_failed 0 0
+  pipe_log "ERROR: could not count merged MRs/PRs"
+  exit 1
+fi
+if [ "$MR_COUNT" = 0 ]; then
+  write_marker no_evidence 0 0
+  pipe_log "No merged MRs/PRs in the last $WINDOW_DAYS days"
+  exit 0
+fi
+
+# Stuck issues are current actionable context. Stuck MRs/PRs are selected from
+# the same bounded recent window, so neither evidence source can expand prompt
+# size without a hard limit.
+STUCK_ISSUES=$(issues_by_labels "$PIPE_LABEL_STUCK" "" opened 20) || {
+  pipe_log "WARNING: failed to fetch open $PIPE_LABEL_STUCK issues; continuing without them"
+  STUCK_ISSUES='[]'
+}
+STUCK_MRS=$(jq -c --arg label "$PIPE_LABEL_STUCK" \
+  '[.[] | select((.labels // []) | index($label))] | .[0:20]' <<< "$RECENT_MRS") || STUCK_MRS='[]'
+OPEN_IMPROVEMENTS=$(issues_by_label_created "$PIPE_LABEL_IMPROVEMENT" opened 10) || {
+  pipe_log "WARNING: failed to fetch open $PIPE_LABEL_IMPROVEMENT issues; continuing without dedup context"
+  OPEN_IMPROVEMENTS='[]'
+}
+
+# Resolve the configured bot identity once so automatic comments do not become
+# evidence. A failed lookup merely leaves the filter empty rather than failing a
+# read-only scheduled analysis.
+platform_resolve_bot_user || true
+
+MR_EVIDENCE=""
+while IFS= read -r IID; do
+  TITLE=$(jq -r --argjson iid "$IID" '.[] | select(.iid == $iid) | .title' <<< "$MRS")
+  AUTHOR=$(jq -r --argjson iid "$IID" '.[] | select(.iid == $iid) | .author' <<< "$MRS")
+  LABELS=$(jq -r --argjson iid "$IID" '.[] | select(.iid == $iid) | (.labels // []) | join(",")' <<< "$MRS")
+  FILES=$(platform_mr_changes "$IID" 15 2>/dev/null | sed 's/^/  /' || true)
+  NOTES=$(platform_mr_notes "$IID" 20 asc 2>/dev/null \
+    | jq -r --arg bot "${PIPE_BOT_USER:-}" \
+      '[.[] | select($bot == "" or .author != $bot)
+       | "  [" + .author + "]: " + ((.body | gsub("[\\r\\n]+"; " "))[0:200])]
+       | .[0:20] | join("\n")' 2>/dev/null || true)
+  MR_EVIDENCE="${MR_EVIDENCE}
+### MR/PR !${IID}: ${TITLE}
+Author: ${AUTHOR} | Labels: ${LABELS}
+Changed files:
+${FILES:-  (none)}
+Human review comments:
+${NOTES:-  (none)}
+"
+done < <(jq -r '.[].iid' <<< "$MRS")
+
+STUCK_EVIDENCE=""
+while IFS= read -r IID; do
+  TITLE=$(jq -r --argjson iid "$IID" '.[] | select(.iid == $iid) | .title' <<< "$STUCK_ISSUES")
+  DESCRIPTION=$(jq -r --argjson iid "$IID" '.[] | select(.iid == $iid) | .description // "(none)"' <<< "$STUCK_ISSUES" | head -c 400)
+  STUCK_EVIDENCE="${STUCK_EVIDENCE}
+### Stuck issue #${IID}: ${TITLE}
+${DESCRIPTION}
+"
+done < <(jq -r '.[].iid' <<< "$STUCK_ISSUES")
+while IFS= read -r IID; do
+  TITLE=$(jq -r --argjson iid "$IID" '.[] | select(.iid == $iid) | .title' <<< "$STUCK_MRS")
+  NOTES=$(platform_mr_notes "$IID" 15 asc 2>/dev/null \
+    | jq -r --arg bot "${PIPE_BOT_USER:-}" \
+      '[.[] | select($bot == "" or .author != $bot)
+       | "  [" + .author + "]: " + ((.body | gsub("[\\r\\n]+"; " "))[0:200])]
+       | .[0:15] | join("\n")' 2>/dev/null || true)
+  STUCK_EVIDENCE="${STUCK_EVIDENCE}
+### Stuck MR/PR !${IID}: ${TITLE}
+Human comments:
+${NOTES:-  (none)}
+"
+done < <(jq -r '.[].iid' <<< "$STUCK_MRS")
+
+OPEN_CONTEXT=$(jq -r '.[] | "Issue #\(.iid) (\(.created_at[0:10])): \(.title)\n\(.description[0:500])\n---"' <<< "$OPEN_IMPROVEMENTS" 2>/dev/null | head -c 6000 || true)
+rm -f "$ARCHITECT_ENV" "$REPORT_FILE" "$PROPOSALS_FILE"
+{
+  echo "# Agent architect context"
+  echo
+  echo "Time window: last $WINDOW_DAYS days (since $SINCE)"
+  echo "Week: $WEEK_TAG"
+  echo "Ready label: $PIPE_LABEL_READY"
+  echo "Improvement label: $PIPE_LABEL_IMPROVEMENT"
+  echo
+  echo "## Merged MRs/PRs"
+  printf '%s\n' "$MR_EVIDENCE"
+  echo "## Stuck items"
+  printf '%s\n' "${STUCK_EVIDENCE:-(none)}"
+  if [ -n "$OPEN_CONTEXT" ]; then
+    echo
+    echo "## Already-open improvement issues — do not re-propose these"
+    printf '%s\n' "$OPEN_CONTEXT"
+  fi
+} > "$CONTEXT_FILE"
+
+REPORT=$(pipe_run_agent agent-architect "/agent-architect" "Agent,Read,Glob,Grep" "$PIPE_MODEL_REVIEW" < /dev/null)
+printf '%s\n' "$REPORT" > "$REPORT_FILE"
+if [ ! -s "$REPORT_FILE" ]; then
+  write_marker no_output 0 0
+  pipe_failure_log_notice_files "the weekly agent-architect analysis" \
+    "review the recent changes and stuck items by hand" \
+    "$PIPE_AGENT_STDERR" "$REPORT_FILE" | while IFS= read -r line; do pipe_log "$line"; done
+  exit 0
+fi
+
+# Retain at most five complete delimiter blocks. The JSON file keeps body text
+# out of shell words and is also the sole source for issue creation below.
+if ! command -v python3 >/dev/null 2>&1; then
+  write_marker parser_failed 0 0
+  pipe_log "WARNING: python3 is unavailable; cannot parse architect proposals"
+  exit 0
+fi
+if ! python3 - "$REPORT_FILE" "$PROPOSALS_FILE" <<'PY'
+import json
+import re
+import sys
+
+report_path, proposals_path = sys.argv[1:]
+text = open(report_path, encoding="utf-8").read()
+proposals = []
+for block in re.findall(r"<!-- ISSUE-START -->(.*?)<!-- ISSUE-END -->", text, re.S)[:5]:
+    title = next((line[7:].strip() for line in block.splitlines() if line.startswith("Title: ")), "")
+    if not title or len(title) > 72:
+        continue
+    proposals.append({"title": title, "body": block.strip()[:8000]})
+with open(proposals_path, "w", encoding="utf-8") as output:
+    json.dump(proposals, output)
+PY
+then
+  rm -f "$PROPOSALS_FILE"
+  write_marker parser_failed 0 0
+  pipe_log "WARNING: could not parse architect proposals"
+  exit 0
+fi
+if ! jq -e 'type == "array"' "$PROPOSALS_FILE" >/dev/null 2>&1; then
+  rm -f "$PROPOSALS_FILE"
+  write_marker parser_failed 0 0
+  pipe_log "WARNING: architect proposal parser produced invalid output"
+  exit 0
+fi
+PROPOSAL_COUNT=$(jq -r 'length' "$PROPOSALS_FILE")
+if [ "$PROPOSAL_COUNT" = 0 ]; then
+  write_marker no_proposals 0 0
+  pipe_log "No concrete architect proposals"
+  exit 0
+fi
+
+case "$DRY_RUN" in
+  false|0) ;;
+  *)
+    write_marker ok "$PROPOSAL_COUNT" 0
+    pipe_log "DRY RUN: $PROPOSAL_COUNT proposal(s), no issues filed"
+    cat "$REPORT_FILE"
+    exit 0
+    ;;
+esac
+
+issue_ensure_label "$PIPE_LABEL_IMPROVEMENT" "#6F42C1" "Agent improvement proposals"
+ISSUES_FILE="$PIPE_CONTEXT_DIR/architect-issue.md"
+ISSUES_FILED=0
+while IFS= read -r proposal; do
+  TITLE=$(jq -r '.title' <<< "$proposal")
+  jq -r '.body' <<< "$proposal" > "$ISSUES_FILE"
+  ISSUE_IID=$(issue_create_file "$TITLE" "$ISSUES_FILE" "$PIPE_LABEL_READY,$PIPE_LABEL_IMPROVEMENT")
+  if [ -n "$ISSUE_IID" ]; then
+    ISSUES_FILED=$((ISSUES_FILED + 1))
+    pipe_log "Filed architect proposal as #$ISSUE_IID"
+  else
+    pipe_log "WARNING: could not file architect proposal: $TITLE"
+  fi
+done < <(jq -c '.[]' "$PROPOSALS_FILE")
+write_marker ok "$PROPOSAL_COUNT" "$ISSUES_FILED"