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

package/payload/skills/agent-architect/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: agent-architect
+description: Analyze bounded recent delivery evidence for concrete improvements to shipped agent definitions. Used by the opt-in scheduled CI job; returns only the report whose proposal blocks the runner files as ready improvement issues.
+---
+
+# agent-architect
+
+This is the CI entry point for the shipped `agent-architect` subagent. The
+runner owns forge reads, label management, issue creation, and all marker
+files. Never call a forge API, create an issue, edit a file, commit, or push.
+
+## Inputs
+
+Read `$PIPE_CONTEXT_DIR/architect-context.md` first. It gives the bounded time
+window, current ready/improvement labels, merged MR/PR summaries with changed
+files and human review excerpts, stuck items, and already-open improvement
+issues. Treat that prepared evidence as authoritative input; do not expand it
+with forge calls or unbounded history scans.
+
+Read `$PIPE_CONFIG_PATH` (default `.claude/pipeline-config.md`) before making
+project-specific recommendations. If it is absent, say so in the report and
+stay conservative.
+
+## Analysis
+
+Spawn the shipped `agent-architect` subagent once. Give it the context-file
+path and require it to use the labels named in that context. It must inspect
+only the repository files needed to validate evidence-backed, surgical changes
+to `.claude/agents/*.md`.
+
+Keep its report verbatim. It must contain exactly one top-level heading,
+`## Section B - Agent Improvements`, and may contain no more than five complete
+`<!-- ISSUE-START -->` / `<!-- ISSUE-END -->` proposal blocks. A proposal needs
+a nonempty `Title: ` line of at most 72 characters and must cite the prepared
+MR/PR or stuck-item evidence. Do not return commentary before or after the
+report.
+
+When no concrete proposal meets that bar, return the heading followed by
+`No significant findings this week.`
+
+## Result
+
+Return only the subagent's markdown report. The runner persists it, bounds and
+parses complete proposal blocks, writes `architect.env`, and in non-dry runs
+creates the resulting issues with the configured ready and improvement labels.

package/payload/skills/codebase-audit/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: codebase-audit
+description: Produce the periodic codebase convention-drift audit report and, when requested, apply its documentation suggestions, in CI. In `audit` mode runs the codebase-auditor agent against a summary of recently merged MRs/PRs and open-audit dedup context, decides the finding status and count, and writes the report and doc-suggestions files plus a machine-readable marker for the pipeline to act on. In `apply-docs` mode runs the coder agent to apply the suggested documentation updates within the configured documentation roots and commits. Use this when a CI job asks to run the codebase audit or apply its documentation suggestions.
+---
+
+# codebase-audit
+
+Generic replacement for the prompt assembly and doc-suggestion extraction in `codebase-audit.sh`. The job runs `claude "/codebase-audit"` instead of building the auditor and coder prompts in bash. This skill does the reasoning; the runner keeps only the API reads that build the MR/PR summary, issue creation, and the push/MR-creation mechanics.
+
+## Step 1: read the project configuration
+
+Read the config file at `$PIPE_CONFIG_PATH` (default `.claude/pipeline-config.md`). In `audit` mode you need nothing from it directly: the `codebase-auditor` subagent reads it and its own Documentation Map itself. In `apply-docs` mode you need the Documentation Map, since the coder is restricted to `$PIPE_DOCS_ROOTS` and should map suggestions onto the right document. If the file is missing, say so on the first line of your output and continue with generic behavior.
+
+## Step 2: inputs
+
+Everything comes from CI variables and the files the job prepared. Do not call the platform API yourself, and never create the issue or the MR/PR — that is mechanical runner work, exactly like every other job in this plan.
+
+- `$PIPE_CONTEXT_DIR` (default `build/pipeline`): where the prepared context lives and where you write outputs.
+- `$PIPE_CONTEXT_DIR/audit-context.md`: the job wrote this, and rewrites it fresh before each invocation — the same path in both modes. Read it first; its `Mode:` line tells you which of the two flows below to run, and the rest of the file is that mode's own content only.
+- `$PIPE_LABEL_AUDIT` (default `codebase-audit`): the label the runner uses for audit issues and MRs/PRs; only relevant if you need to refer to it in your own output.
+- `$PIPE_DOCS_ROOTS` (default `docs,CLAUDE.md,.claude/memory`): comma-separated documentation roots, apply-docs mode only.
+- `$PIPE_COMMIT_AUDIT` (default `docs: apply convention audit findings`): the exact commit subject, apply-docs mode only.
+
+## Mode: audit
+
+The context file lists the recently merged MRs/PRs (with up to 10 changed file paths each) and, when any exist, the currently open audit-labeled issues as dedup context.
+
+### Step 3: run the codebase-auditor agent
+
+Spawn the `codebase-auditor` subagent once. Point it at `$PIPE_CONTEXT_DIR/audit-context.md` for the recently-merged-MR summary and the open-issue dedup context, and tell it to skip any finding already covered by an open issue. The agent reads the config, the documented conventions, and the changed files of each listed MR/PR itself, and returns its report as its final output, exactly the two sections defined in its own instructions (`## Critical violations` and `## Patterns worth documenting`, each either a confidence->=80 bullet list or the literal line `No significant findings.`). Do not restate its internal scoring rules in the prompt.
+
+### Step 4: decide the status and count the findings
+
+Take the agent's report text verbatim (no reformatting) and write it to `$PIPE_CONTEXT_DIR/audit-report.md`. Then decide:
+
+- The agent produced no output at all (empty or missing) -> `AUDIT_STATUS=no_output`, `AUDIT_FINDINGS_TOTAL=0`.
+- Otherwise, count the finding bullets: lines starting with `- **` across the whole report (`grep -c '^- \*\*'` is exactly the source convention; a report where neither section has findings has zero such lines because both say `No significant findings.`). Zero findings -> `AUDIT_STATUS=no_findings`. One or more -> `AUDIT_STATUS=ok`.
+
+### Step 5: extract the doc suggestions
+
+Always write `$PIPE_CONTEXT_DIR/audit-doc-suggestions.md`, even when it ends up empty. Its content is the bullet lines under the `## Patterns worth documenting` heading only (stop at the next `## ` heading or end of report), verbatim, or nothing when that section is `No significant findings.`. This file is what the runner checks to decide whether to attempt the `apply-docs` phase; do not fabricate a suggestion that is not literally a bullet in that section.
+
+### Step 6: emit the marker
+
+Write `$PIPE_CONTEXT_DIR/audit.env`:
+
+```
+AUDIT_STATUS=ok|no_output|no_findings
+AUDIT_FINDINGS_TOTAL=<int>
+AUDIT_REPORT_PATH=$PIPE_CONTEXT_DIR/audit-report.md
+```
+
+Do not write an `AUDIT_ISSUE_IID` line yourself: no issue exists yet at this point in the flow. The runner creates the issue after you return (only when `AUDIT_STATUS=ok`), captures its IID, and appends `AUDIT_ISSUE_IID=<iid>` to this same file so the artifact is complete when the job finishes. Always write all three lines above, including on `no_output` and `no_findings`, so the runner can branch reliably.
+
+## Mode: apply-docs
+
+The context file gives you the issue number, the documentation roots, the commit subject, and the paths of the doc-suggestions file and the full audit report the `audit`-mode invocation wrote. The repository is already checked out on the audit branch; git is local, no token needed.
+
+### Step 3: delegate to the coder
+
+Spawn the `coder` subagent. Tell it plainly:
+
+- it may edit ONLY paths under the documentation roots listed in the context file (each root is a directory or a single file) — no `src/`, no test code, no CI files, nothing else;
+- implement ONLY the suggested updates listed in the doc-suggestions file (read it itself), using the full audit report (read it itself) for context;
+- when done, commit with `git add -A && git commit` using EXACTLY the commit subject from the context file, followed by a blank line and `Closes #<issue number>` from the context file;
+- do NOT run `git push` — the runner handles pushing.
+
+Do not restate the coder's own internal workflow (documentation map lookup, verify command, etc.); those do not apply here since this is a documentation-only change.
+
+### Step 4: confirm the commit and emit the marker
+
+Run `git rev-list "origin/$PIPE_TARGET_BRANCH..HEAD" --count` to count the commits made this run. Write `$PIPE_CONTEXT_DIR/audit-apply.env`:
+
+```
+AUDIT_APPLY_COMMITS=<integer count of commits this run>
+```
+
+Zero means the coder made no changes (no suggestion turned out actionable, or it got stuck); do not draft anything else in that case, the runner handles the no-commits path.
+
+## What the CI job does after you
+
+In `audit` mode: the runner reads `audit.env`. On `no_output` it logs a failure notice (no issue exists yet to post to). On `no_findings` it stops, nothing filed. On `ok` it creates the findings issue from `audit-report.md` (truncated, with the `audited-up-to-mr-iid` marker prepended) labeled `$PIPE_LABEL_AUDIT`, appends the issue IID to `audit.env`, and emits a metric. It then skips the `apply-docs` phase entirely when there is no push-capable identity configured, or when `audit-doc-suggestions.md` is empty.
+
+Otherwise it creates and checks out the `audit-<date>` branch and runs you again in `apply-docs` mode. It reads `audit-apply.env`, recounts the commits itself as the authoritative gate: with zero commits it posts a manual-review notice to the issue (with an extra credit-exhaustion note when that applies) and deletes the branch; otherwise it pushes the branch and opens an MR/PR titled `docs: codebase audit updates (<date>)` that closes the issue, labeled `$PIPE_LABEL_AUDIT`. None of that is your job.

package/payload/skills/cve-fix/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: cve-fix
+description: Safely update one configured dependency manifest for HIGH/CRITICAL vulnerability identifiers supplied by a CI scanner, compile it, make at most one commit, and emit a CVE remediation marker. Use only when the cve-fix CI runner has prepared its context.
+---
+
+# cve-fix
+
+`cve-fix` is a code-writing skill called by the CI runner. It does not scan
+projects, choose a vulnerability scanner, or filter severities: that stays
+outside this skill. The caller supplies the already selected HIGH/CRITICAL
+identifier list through `PIPE_CVE_LIST` and the runner context.
+
+The runner owns MR/PR API access, rebase, push, and comments. Never do any of
+those things yourself.
+
+## Inputs and hard boundary
+
+Read exactly one prepared context first:
+
+- `$PIPE_CONTEXT_DIR/cve-fix-context.md` (default context directory is
+  `build/pipeline`).
+
+It names the vulnerability-list file, configured dependency manifest path,
+manifest-content file, compile command, exact commit subject, source and target
+branches, suppression path, remaining commit budget, and marker path. Read the
+named list and manifest-content files; do not independently run a scanner,
+inspect scanner output, or expand the scope from repository search results.
+
+Validate before editing:
+
+- `Mode:` must be `apply`.
+- The list must contain at least one non-blank identifier.
+- The manifest path must be present and the corresponding file must exist.
+- Source branch, target branch, commit subject, compile command, and remaining
+  commit budget must be present.
+- The remaining budget must be a positive integer. A proposed change that would
+  exceed it must not be made.
+
+If any validation fails, make no edit and no commit. Write the marker described
+below with `CVE_MANUAL_REQUIRED=1`.
+
+Only the configured dependency manifest may be changed. Do not modify the
+vulnerability list, scanner output, configured suppression path, CI files,
+source code, tests, lockfiles, generated files, or any other dependency
+manifest. Do not use a project-specific ecosystem, build tool, package name,
+or version as an assumption.
+
+## Remediation
+
+Use the shipped `coder` agent to reason from only the supplied vulnerability
+list and manifest content. It must identify updates that are explicit and safe
+in that manifest. Do not guess a package/version, edit a BOM or indirect
+configuration outside the configured file, or make a change when the affected
+dependency cannot be identified safely.
+
+When a safe update is available:
+
+1. Edit only the configured dependency manifest.
+2. Run the supplied compile command exactly as configured.
+3. If compilation succeeds, create at most one commit, using the exact supplied
+   subject and staging only that configured manifest.
+4. Never push, rebase, post a comment, use a forge API, or change branches.
+
+A failed compile, an unavailable safe update, a missing input, or uncertain
+mapping from an identifier to a manifest dependency requires no commit and
+manual follow-up.
+
+## Marker
+
+Always write `$PIPE_CONTEXT_DIR/cve-fix.env` (or the `Marker File:` path from
+the context) as exactly these four newline-separated keys, with no other keys:
+
+```dotenv
+CVE_FIX_APPLIED=0|1
+CVE_COMPILED=0|1
+CVE_COUNT=<non-negative integer>
+CVE_MANUAL_REQUIRED=0|1
+```
+
+`CVE_COUNT` is the number of non-blank vulnerability identifiers read from the
+supplied list. `CVE_FIX_APPLIED=1` only after a real new commit with the exact
+provided subject exists. `CVE_COMPILED=1` only after the supplied compile
+command completed successfully. `CVE_MANUAL_REQUIRED=1` when no safe update is
+available, required metadata is missing, validation fails, or compilation does
+not pass. Do not claim a commit or compilation solely because an agent returned
+successfully.
+
+For a successful remediation the marker is:
+
+```dotenv
+CVE_FIX_APPLIED=1
+CVE_COMPILED=1
+CVE_COUNT=<count>
+CVE_MANUAL_REQUIRED=0
+```
+
+The runner independently validates the marker, commit, compilation, rebase,
+and push before it reports success.

package/payload/skills/docs-sync/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: docs-sync
+description: Check whether the code changes of a merge request or pull request require documentation updates, in CI. Runs the docs-sync agent, which applies the updates on an autonomous MR/PR and reports the gaps on a human-authored one, then emits the comment body and a machine-readable marker for the pipeline to act on. Use this when a CI job asks to sync documentation for an MR/PR.
+---
+
+# docs-sync
+
+Generic replacement for the prompt assembly in `docs-sync.sh`. The CI job runs the harness with `/docs-sync` instead of building a long prompt in bash. This skill does the reasoning. The runner keeps only the API read that classifies the MR/PR, the diff computation, posting the comment, and committing the documentation edits.
+
+## Step 1: read the project configuration
+
+Read the config file at `$PIPE_CONFIG_PATH` (default `.claude/pipeline-config.md`). From it you need the Project stack, the Git & Platform section, and above all the Documentation Map, which says which document covers which topic. If the file is missing, say so on the first line of your output and continue with generic behavior: treat the documentation roots as the whole map.
+
+## Step 2: inputs
+
+Everything comes from CI variables and the files the job prepared. Do not call the platform API yourself, and do not run `git` to recompute the diff: the runner already scoped it.
+
+- `$PIPE_CONTEXT_DIR` (default `build/pipeline`): where the prepared context lives and where you write outputs.
+- `$PIPE_CONTEXT_DIR/docs-sync-context.md`: the mode, the MR/PR title, the documentation roots, and the paths of the two files below. Read it first.
+- `$PIPE_CONTEXT_DIR/docs-sync-files.txt`: the changed files of the whole MR/PR.
+- `$PIPE_CONTEXT_DIR/docs-sync-diff.patch`: the full `base..head` diff. It is never an incremental slice, so a gap introduced by an earlier push is still in front of you.
+- `$PIPE_DOCS_ROOTS` (default `docs,CLAUDE.md,.claude/memory`): comma-separated documentation roots. These are the only paths that may be edited.
+- `$PIPE_RESULT_DOCSSYNC` (default `$PIPE_CONTEXT_DIR/docs-sync.json`): where the result JSON goes.
+
+The `Mode:` line of the context file is one of:
+
+- `apply`: an autonomous MR/PR. The documentation updates are applied by editing files under the documentation roots.
+- `report`: a human-authored MR/PR, or an autonomous one whose tip is already an automated docs commit. Gaps are reported and nothing is edited.
+
+## Step 3: run the docs-sync agent
+
+Spawn the `docs-sync` subagent once. Pass it:
+
+- the mode and what it means (apply the updates by editing files under the documentation roots, or report the gaps without editing anything),
+- the MR/PR title,
+- the paths of the changed-files list and the diff, so it reads them itself rather than receiving them inline,
+- the documentation roots it may edit, and the instruction that production source, tests and CI files are out of bounds and that it must not run `git`,
+- the result file path, which is `$PIPE_RESULT_DOCSSYNC`.
+
+The agent reads the config, the Documentation Map and the documents it needs itself, and applies its own documentation threshold. Do not restate its internal rules in the prompt, and do not preload documents into it.
+
+## Step 4: check the boundary
+
+Before you emit anything, verify the agent stayed inside the documentation roots. Any edit outside them is out of scope: revert it, and say so in the comment body. The runner stages and commits the documentation roots before it discards any remaining out-of-scope working-tree changes, so leaving an out-of-scope edit in place only loses the agent's own work.
+
+In `report` mode nothing may be edited at all. If the agent edited a file anyway, revert every edit and report the gaps as text.
+
+## Step 5: emit the result and the marker
+
+The result JSON is the agent's own output; the body file and the dotenv are yours. If the agent wrote no result file, or wrote one that is not valid JSON with a `comment` string, rewrite it yourself from what the agent reported.
+
+`$PIPE_RESULT_DOCSSYNC` (default `$PIPE_CONTEXT_DIR/docs-sync.json`):
+
+```json
+{"has_gaps": true, "changed": true, "comment": "**Status: blocking**\n\n- **docs/X.md**: Added the section for the Y pattern introduced here"}
+```
+
+`$PIPE_CONTEXT_DIR/docs-sync-body.md`: the value of `comment` as plain markdown, and nothing else. This is what gets posted, so the runner never has to parse a model-written JSON file. Its first line is the status line, exactly one of `**Status: blocking**`, `**Status: non-blocking**`, `**Status: clean**`, followed by a flat bullet list of findings, blocking items first. Each bullet names the document and describes in one sentence what is missing, or what you added in `apply` mode. No section headers, no prose around the list. When the documentation is up to date the body is exactly the status line `**Status: clean**`.
+
+`$PIPE_CONTEXT_DIR/docs-sync.env`:
+
+```
+DOCS_HAS_GAPS=true|false
+DOCS_CHANGED=true|false
+DOCS_COMMENT_PATH=<path of the body file>
+```
+
+`DOCS_HAS_GAPS` is `true` only when at least one actionable gap was found; informational notes alone keep it `false`. `DOCS_CHANGED` is `true` only when you left an edit on disk, which can only happen in `apply` mode. `DOCS_COMMENT_PATH` is the absolute or repository-relative path of the body file you wrote.
+
+Always write all three, including on a clean verdict. A missing body file is how the runner detects that the agent did not complete, and it then posts a manual-review notice instead of your verdict.
+
+## What the CI job does after you
+
+The runner reads `docs-sync.env`, posts the body as the MR/PR comment behind its own marker line, and emits the metrics event. In `apply` mode it stages the documentation roots and commits with `$PIPE_COMMIT_DOCSSYNC` only when their staged diff is non-empty; `DOCS_CHANGED` only reports whether the skill left an edit on disk. It then discards anything you left outside those roots, rebases and pushes. It never asks you to run `git`. None of that is your job.

package/payload/skills/e2e-test-gen/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: e2e-test-gen
+description: Generate or repair one focused E2E test for a runner-selected issue, using the project's configured E2E conventions. This deliberately implements only issue-driven generation; project-specific test-gap detection is intentionally omitted.
+---
+
+# e2e-test-gen
+
+`e2e-test-gen` is the issue-driven half of generic E2E generation. It
+**deliberately omits test-gap detection**: scanner-like source/package heuristics
+are project-specific and are not a missing capability to restore.
+
+The CI runner owns the branch, git identity, commits, push, issue labels,
+comments, and MR/PR creation. Never perform any of those actions. Do not call a
+forge API.
+
+## Read inputs before editing
+
+Read `$PIPE_CONTEXT_DIR/e2e-gen-issue-<IID>.md` for the runner context. Its
+`Mode:` is either `generate` or `repair`; in repair mode it names the only file
+that may be edited. Then read the project pipeline configuration at the
+context's `Project Configuration:` path and its **E2E Tests** section.
+
+Before any edit, require all of these configuration values to be explicit:
+
+- E2E framework;
+- configured test directory, matching the runner context;
+- fixture import module;
+- test-data prefix;
+- required tags; and
+- base URL, matching the runner context.
+
+If the E2E Tests section is absent, says E2E is unused, or any required value is
+missing, make no edit. Do not infer a framework, fixtures, credentials, command,
+or base URL.
+
+## Generate mode
+
+1. Read the bounded title and description files named in the context.
+2. Read the existing fixture and one or two nearby tests to follow the project's
+   conventions, selectors, data cleanup, and tags.
+3. Use the shipped `e2e-test-writer` agent to draft one focused scenario.
+4. Write exactly one new test file beneath the configured test directory. Do not
+   modify production code, configuration, fixtures, helpers, existing tests, or
+   files outside that directory.
+5. Use the fixture module, data prefix, required tags, and cleanup convention
+   from the E2E Tests section. Do not expose credentials or invent test data
+   outside the configured prefix.
+
+## Repair mode
+
+Read the named generated test and the relevant existing test/fixture convention.
+Edit only that named generated test to address the failed verification. Do not
+create files or change any other file.
+
+## Result
+
+Return a marker-readable final line only after a file was actually written:
+
+```text
+E2E_TEST_WRITTEN=<project-relative path>
+```
+
+In repair mode `<project-relative path>` must be the named generated test. This
+line is a result for the runner to read; it does not authorize git, forge, or
+label operations.

package/payload/skills/fix-review-findings/SKILL.md

@@ -17,7 +17,7 @@ Read `$PIPE_CONFIG_PATH` (default `.claude/pipeline-config.md`). You need the Gi
 - `$PIPE_VERIFY_CMD`: verification command (compile plus unit tests) to run after a fix.
 - `$PIPE_FIX_LOOP_CAP` (default `2`): maximum consecutive review-fix commits before escalating.
 - `$PIPE_COMMIT_REVIEWFIX`: exact commit subject for a review fix. Its recurrence drives the cap count.
-- `$PIPE_TARGET_BRANCH`: the branch the MR/PR targets, used as the base for the commit-history walk.
+- `$PIPE_COMMIT_DOCSSYNC`: exact docs-sync commit subject. Ignore this subject while walking the fix streak so a documentation commit does not reset the cap.
 - `$PIPE_RESULT_REVIEWFIX` (default `$PIPE_CONTEXT_DIR/review-fix-result.json`): where the coder writes its structured result.
 - `$PIPE_CONTEXT_DIR` (default `build/pipeline`): where you write the result marker.
 
@@ -29,7 +29,7 @@ Count consecutive commits from the branch tip back toward `$PIPE_TARGET_BRANCH`
 git log "origin/$PIPE_TARGET_BRANCH"..HEAD --format="%s"
 ```
 
-Stop at the first non-matching subject. If the count is at or above `$PIPE_FIX_LOOP_CAP`, do not attempt another fix. Escalate: follow the postmortem-mr flow (spawn the `postmortem` agent with the review body as the failure text, the fix-attempt git log, and the changed files, then read `failure_category`). Write the marker with `RF_ESCALATE=true` and the `FAILURE_CATEGORY`, and stop.
+Walk the subjects in order. Increment the count only when a subject exactly equals `$PIPE_COMMIT_REVIEWFIX`. If a subject exactly equals `$PIPE_COMMIT_DOCSSYNC`, ignore it and continue walking. Stop at every other subject. If the count is at or above `$PIPE_FIX_LOOP_CAP`, do not attempt another fix. Escalate: follow the postmortem-mr flow (spawn the `postmortem` agent with the review body as the failure text, the fix-attempt git log, and the changed files, then read `failure_category`). Write the marker with `RF_ESCALATE=true` and the `FAILURE_CATEGORY`, and stop.
 
 ## Step 4: gather prior attempts
 

package/payload/skills/fix-tests/SKILL.md

@@ -20,7 +20,7 @@ Read `$PIPE_CONFIG_PATH` (default `.claude/pipeline-config.md`). You need the Bu
 - `$PIPE_FIX_LOOP_CAP` (default `2`): maximum consecutive bot fix commits before escalating.
 - `$PIPE_COMMIT_TESTFIX`: exact commit subject for a test fix. Its recurrence drives the cap count.
 - `$PIPE_COMMIT_COVERAGE`: exact commit subject for a coverage-tests commit. Separate cap counter.
-- `$PIPE_TARGET_BRANCH`: the branch the MR/PR targets, used as the base for the commit-history walk.
+- `$PIPE_COMMIT_DOCSSYNC`: exact docs-sync commit subject. Ignore this subject while walking either fix streak so a documentation commit does not reset the cap.
 - `$PIPE_CONTEXT_DIR` (default `build/pipeline`): where you write the result marker.
 
 ## Step 3: pick the case
@@ -40,7 +40,7 @@ Count consecutive commits from the branch tip back toward `$PIPE_TARGET_BRANCH`
 git log "origin/$PIPE_TARGET_BRANCH"..HEAD --format="%s"
 ```
 
-Stop counting at the first subject that does not match. If the count is at or above `$PIPE_FIX_LOOP_CAP`, do not attempt another fix. Escalate instead: follow the postmortem-mr flow (spawn the `postmortem` agent with the failure text, the fix-attempt git log, and the changed files, then read `failure_category` from its report). Write the marker with `FIX_ESCALATE=true` and the `FAILURE_CATEGORY`, and stop. The job applies the stuck label and posts the diagnostic.
+Walk the subjects in order. Increment the count only when a subject exactly equals the relevant fix subject. If a subject exactly equals `$PIPE_COMMIT_DOCSSYNC`, ignore it and continue walking. Stop at every other subject. If the count is at or above `$PIPE_FIX_LOOP_CAP`, do not attempt another fix. Escalate instead: follow the postmortem-mr flow (spawn the `postmortem` agent with the failure text, the fix-attempt git log, and the changed files, then read `failure_category` from its report). Write the marker with `FIX_ESCALATE=true` and the `FAILURE_CATEGORY`, and stop. The job applies the stuck label and posts the diagnostic.
 
 ## Step 5: delegate
 

package/payload/templates/memory-index.template.md

@@ -0,0 +1,34 @@
+# Memory index
+
+<!-- Created by the ci-agent-platform install. This is tier 3 of a three-tier
+     information architecture:
+       CLAUDE.md          hardwired instructions, an index into the tiers below
+       docs/              long-term patterns, how-tos, architecture
+       .claude/memory/    active project state and cross-agent signals
+
+     Keep this file an index. Each entry is one line: the file, and what an
+     agent learns from it. Files here are project-owned. The installer never
+     rewrites them. -->
+
+## Feedback signals
+
+<!-- One file per lesson the pipeline taught the project, named
+     feedback_<topic>.md. Written after a postmortem or a repeated review
+     finding, read by the agents whose work it constrains. -->
+(none yet)
+
+## Project state
+
+<!-- One file per moving part whose current status agents need, named
+     project_<topic>.md. -->
+(none yet)
+
+## Reference
+
+<!-- Lookup tables that would otherwise be re-derived every run, named
+     reference_<topic>.md. -->
+(none yet)
+
+## Review suppressions
+
+- `review_suppressions.md` - patterns the reviewers must not flag, with the reason and the date. Read by every reviewer agent before it reports anything.

package/payload/templates/pipeline-config.template.md

@@ -76,6 +76,15 @@ TODO
 ## Suppressions
 - Path: .claude/memory/review_suppressions.md (sections: Code / Security / Migration / Performance)
 
+## Metrics Conventions
+<!-- Optional. Only needed when the project runs the metrics-snapshot job.
+     The aggregator counts post-merge defects by matching commit subjects, so
+     the patterns have to be agreed rather than guessed. Defaults below match
+     the shipped aggregator. Mark "not used" when the job is off. -->
+- Full revert of a merged change: `Reverts !<iid>`
+- Targeted fix for a defect introduced by a merged change: `Fixes regression from !<iid>`
+- Re-landing work that was reverted: `Reintroduces work from !<iid>`
+
 ## Release
 <!-- Used by the release agent. Mark "not used" if the project has no formal release flow. -->
 - Release title format: <!-- e.g. "Update to x.y.z" --> TODO
@@ -89,7 +98,8 @@ TODO
 
 ## E2E Tests
 <!-- Only for projects with a generated e2e suite. Otherwise: not used.
-     Framework, test dir, fixture import module, test-data prefix, cleanup rules, required tags.
+     Required: framework, test dir, fixture import module, test-data prefix,
+     cleanup rules, required tags, and the base URL used by generated tests.
      Also (the e2e-test-writer relies on these):
      - frontend source dirs + selector strategy (real element IDs vs test-id attributes),
      - spec-file naming/extension convention (one scenario per file),

package/payload/templates/review_suppressions.template.md

@@ -11,15 +11,70 @@
 ## Code Review Suppressions
 
 (none yet)
+<!--
+### Generated output reports a duplicate helper
+- **Pattern:** a generated file contains a helper that resembles a hand-written helper
+- **Why:** the generator owns this output and the apparent duplicate is not maintained independently
+- **Date:** 2026-08-28
+-->
+
+<!--
+### Explicit fallback differs from the usual convention
+- **Pattern:** a narrowly scoped fallback uses a documented exception to the usual convention
+- **Why:** the deviation records a deliberate compatibility decision and is reviewed with its documented context
+- **Date:** 2026-08-28
+-->
+
 
 ## Security Review Suppressions
 
 (none yet)
+<!--
+### Generated metadata includes an unused-looking field
+- **Pattern:** generated metadata declares a field that no direct source reference uses
+- **Why:** the generator requires the field for a downstream consumer, so removing it would make the output incomplete
+- **Date:** 2026-08-28
+-->
+
+<!--
+### Escaped value triggers a broad input warning
+- **Pattern:** a value is passed through a safe escaping idiom that a generic catalog flags
+- **Why:** the idiom applies the required encoding before the value reaches its destination
+- **Date:** 2026-08-28
+-->
+
 
 ## Migration Review Suppressions
 
 (none yet)
+<!--
+### Generated history includes a repeated declaration
+- **Pattern:** generated change history repeats a declaration already represented elsewhere
+- **Why:** the generator preserves both representations so independent consumers can process the history
+- **Date:** 2026-08-28
+-->
+
+<!--
+### Intentional ordering differs from the default
+- **Pattern:** a documented ordering intentionally differs from the usual sequence
+- **Why:** the exception preserves a required transition and is limited to the documented operation
+- **Date:** 2026-08-28
+-->
+
 
 ## Performance Review Suppressions
 
 (none yet)
+<!--
+### Generated lookup repeats a calculation
+- **Pattern:** generated lookup code repeats a small calculation that resembles avoidable work
+- **Why:** the generator emits the calculation to keep each generated branch independent and correct
+- **Date:** 2026-08-28
+-->
+
+<!--
+### Guarded reuse is reported as shared-state risk
+- **Pattern:** a safe reuse idiom protected by an explicit guard is flagged by a generic catalog
+- **Why:** the guard establishes the required boundary before reuse occurs
+- **Date:** 2026-08-28
+-->

package/payload/templates/spec-issue.template.md

@@ -1,6 +1,11 @@
 <!--
-  Spec template for issues intended for autonomous implementation (the ready
-  label). Fill in every mandatory section before applying the label.
+  Spec template for issues intended for autonomous implementation. Use it only
+  when requirements are settled and every mandatory section can be completed
+  unambiguously.
+
+  For early ideation or product discussion, use a feature request. For a
+  reproducible defect, use a bug report. For a documentation-only change, use
+  a docs update. Promote those to a Spec once requirements are settled.
 
   IMPORTANT: the eight section headers below (## 1. Outcome ... ## 8. Out of
   Scope) are load-bearing. The pipeline validates decomposed sub-issues against
@@ -12,6 +17,13 @@
    GitHub default .github/ISSUE_TEMPLATE/spec.md).
 -->
 
+## Spec Readiness
+
+- [ ] All mandatory sections below are filled in and unambiguous.
+- [ ] I understand that applying this project's configured ready label hands this issue to an autonomous implementation agent.
+
+---
+
 > Fill this into the issue DESCRIPTION, not a comment. The pipeline reads only the description for the spec check.
 
 ## 1. Outcome
@@ -31,9 +43,11 @@ TODO
 ## 4. Scope Envelope
 <!-- Be honest about size. One coder session handles roughly the capacity in the
      pipeline config (default ~15 files / ~600 lines). Larger work is decomposed. -->
-- Estimated files touched: TODO
-- Layers / packages affected: TODO
-- Fits in one coder session: TODO (yes / no; if no, decompose first)
+- **Estimated files touched:** TODO
+- **Packages / layers affected:** TODO
+- **Database migration required:** TODO (yes / no)
+- **User-interface changes required:** TODO (yes / no)
+- **Fits in one coder session:** TODO (yes / no; if no, decompose first)
 
 ## 5. Existing Code Anchors
 <!-- <at least one> pointer to model the implementation after: a class, a module,
@@ -43,9 +57,10 @@ TODO
 
 ## 6. Risk Flags
 <!-- Check any that apply. Each checked box may trigger a specialist reviewer and
-     changes how the coder approaches the work. -->
+     changes how the coder approaches the work. Projects add domain-specific
+     risk flags in pipeline-config.md. -->
 - [ ] Schema migration
-- [ ] Security-sensitive (auth, permissions, tenant isolation, secrets)
+- [ ] Security-sensitive (authentication, authorization, permissions, secrets)
 - [ ] Public API contract change
 - [ ] Performance-critical (hot path, large query, batch job, N+1-prone)
 
@@ -53,11 +68,28 @@ TODO
 <!-- <what will be tested> and how we will know it works. Be specific. -->
 - New tests to add: TODO
 - Existing tests that must still pass: TODO
+- Manual verification (if applicable): TODO
 
 ## 8. Out of Scope
 <!-- What this issue deliberately does NOT include. Prevents scope creep. -->
 - TODO
 
+## Open Questions
+<!-- Optional. If this section has unresolved items, keep iterating before
+     applying the configured ready label. -->
+- TODO
+
+## Decomposition Links
+<!-- Optional. Track the parent issue and any child issues created from this
+     specification. -->
+- Decomposed from: TODO
+- Decomposes into: TODO
+
+## References
+<!-- Optional. Link related issues, change requests, design documents, and
+     external resources. -->
+- TODO
+
 <!-- Dependencies (GitHub has no native issue links): to say this issue waits on
      another, write "Blocked by #N" here. The orchestrator's release poll reads
      it back and promotes the issue once #N closes. On GitLab, native issue