@open-mercato/cli 0.6.7 → 0.6.8-canary.320.1.bf889f49e4

package/dist/agentic/shared/ai/specs/SPEC-000-template.md

@@ -3,33 +3,249 @@
 **Date**: {YYYY-MM-DD}
 **Status**: Draft
 
+> Use `om-spec-writing` for every new application, multi-module feature, or other non-trivial business slice. Keep every section below; write `N/A — {reason}` when a section does not apply. Change the status to `Ready for implementation` only after every blocking open question is resolved and the traceability table covers every requirement.
+
 ## TLDR
 
-{2-3 sentence summary}
+{What is being built, who benefits, which existing Open Mercato capabilities are reused, and the smallest coherent outcome.}
 
 ## Problem Statement
 
-{What problem this feature solves}
+{Current workflow, concrete pain, evidence, affected users, and why existing behavior is insufficient.}
+
+## Overview and Success Measures
+
+- **Primary outcome:** {Measurable business result and target.}
+- **Leading indicators:** {Signals available before the final outcome.}
+- **Baseline:** {Current measurable state or `unknown — measurement plan`.}
+- **Market / product reference:** {Comparable product or workflow studied; what is adopted, rejected, and why.}
+
+## Goals
+
+- **REQ-001** — {Observable business outcome.}
+- **REQ-002** — {Observable business outcome.}
+
+## Non-goals
+
+- {Explicitly excluded behavior, module, integration, or migration.}
 
 ## Proposed Solution
 
-{High-level approach}
+{Describe the product and technical approach, how it closes each stated problem, and why it is the smallest platform-native solution that can deliver the goals.}
+
+### Design Decisions and Alternatives
+
+| Decision | Rationale | Alternative considered | Why rejected / deferred |
+|---|---|---|---|
+| {choice} | {why it fits the requirements and platform} | {alternative} | {tradeoff} |
+
+## Domain Vocabulary and Business Rules
+
+| Term / invariant | Precise meaning or rule | Source of truth | Failure behavior |
+|---|---|---|---|
+| {term} | {one unambiguous meaning, formula, lifecycle, or constraint} | {module/entity/provider} | {reject/degrade/retry/audit} |
+
+Define fields, states, transitions, calculations, ownership, and invariants precisely enough that implementation does not need to invent domain behavior.
+
+## Users, Permissions, and Scope
+
+| Actor | Allowed outcomes | Scope rule | Required feature IDs |
+|---|---|---|---|
+| {actor} | {view/create/update/etc.} | {own/team/organization/system} | `{module}.view`, `{module}.manage` |
+
+Document how trusted `tenantId` and `organizationId` are derived. Describe any legitimate system-scope operation and the installed contract that authorizes it.
+
+## Reuse and Ownership Map
+
+| Capability | Reuse / extend / app-own | Existing module or new module | Integration seam | Why |
+|---|---|---|---|---|
+| {capability} | {reuse/UMES/app-owned} | `{module}` | {ID/snapshot/event/enricher/extension/optional DI} | {decision} |
+
+Name the installed records that remain the source of truth. Do not duplicate CRM, auth, directory, notification, workflow, or other installed capabilities in app-owned entities.
+
+## Architecture and Data Flow
+
+```text
+{actor/surface} -> {API/command} -> {owning entity}
+                                  -> {event/subscriber/integration}
+```
+
+- **Module boundaries:** {Why each new module owns a distinct invariant; merge modules that must remain transactionally consistent.}
+- **Extension points:** {Installed page/menu/widget/enricher/interceptor/event seams used instead of modifying installed code.}
+- **Alternatives considered:** {Simpler platform-native alternative and why it was not selected.}
+- **Compatibility:** {Existing API/data/UI behavior that must remain stable.}
+
+## User Journeys
+
+### Journey J-001 — {Name}
+
+1. {Actor starts from a named page or API.}
+2. {Primary action and system response.}
+3. {Success state and downstream side effects.}
+4. {Recoverable failure, permission denial, conflict, and retry behavior.}
+
+## UI and Interaction Contracts
+
+List every new or changed page before implementation. Inspect the closest existing Open Mercato page and `.ai/guides/backend-ui.md`; record that reference below. Tabular admin data uses `DataTable`, CRUD create/edit surfaces use `CrudForm`, and backend reads use the shared API helpers. Any custom page or component exception needs an explicit rationale and approval in this section.
+
+| Surface / route | Purpose and primary actions | Data source / mutations | Closest installed reference | Canonical shell / components | Required states | Requirement IDs |
+|---|---|---|---|---|---|---|
+| `/backend/{route}` | {list/create/edit/etc.} | `{API paths / command IDs}` | `{module/path or component family}` | `Page`, `PageBody`, `DataTable`, `CrudForm`, {others} | loading, empty, error, conflict, success, permission denied | REQ-001 |
+
+### UI architecture
+
+| Role | Navigation groups in order | Dashboard / injected widgets | Login-to-primary-task flow |
+|---|---|---|---|
+| {role} | {group → item} | {widget, host, click-through} | {page → action → result; target ≤3 clicks} |
+
+| Surface / widget | Empty state guidance and action | Responsive behavior | Keyboard / focus behavior |
+|---|---|---|---|
+| {surface} | {localized explanation + next action} | {narrow/mobile layout} | {focus order, submit/cancel, announcements} |
+
+### `/backend/{route}` — {Page name}
+
+```text
+┌────────────────────────────────────────────────────────────┐
+│ {Page title}                               [{Primary action}]│
+│ {Filters / summary / navigation}                           │
+├────────────────────────────────────────────────────────────┤
+│ {DataTable, CrudForm groups, calendar, or detail sections} │
+├────────────────────────────────────────────────────────────┤
+│ {Pagination / save-delete actions / status feedback}       │
+└────────────────────────────────────────────────────────────┘
+```
+
+- **Behavior:** {sorting/filtering/pagination, validation, keyboard behavior, navigation, destructive confirmation, optimistic-lock conflict recovery.}
+- **Responsive and accessibility:** {focus order, labels, screen-reader status, small-screen behavior.}
+- **Localization:** {translation namespaces and dynamic values.}
+- **Design-system and theming:** {semantic tokens and shared primitives; verify light and dark mode, contrast, reduced motion, and no hard-coded palette/status colors.}
+
+For backend UI, implementation must invoke `om-backend-ui-design` and follow `.ai/guides/backend-ui.md`. Raw `<table>`, raw admin `<form>`, raw `fetch`, copied component families, arbitrary Tailwind values, hard-coded light-only colors, and manual `dark:` patches fail readiness unless the approved contract explains why the platform primitive cannot support the interaction. A custom calendar, board, or clinical workspace may be justified, but its surrounding shell, controls, status treatment, dialogs, states, and tokens remain platform-native.
 
 ## Data Models
 
-{Entity definitions, relationships}
+### `{Entity}`
+
+| Field | Type / nullability | Scope / index | Sensitive / encrypted | Lifecycle and validation |
+|---|---|---|---|---|
+| `id` | UUID, required | primary key | no | immutable |
+| `tenant_id` / `organization_id` | UUID, required | composite scope indexes | no | trusted context only |
+| `updated_at` | timestamp, required | optimistic-lock version | no | updated on every edit |
+
+Document entity ownership, soft-delete or append-only rules, cross-module IDs/snapshots, uniqueness, transactions, encryption maps, retention, migrations, and compatibility impact.
+
+## API, Command, and Error Contracts
+
+| Method / command | Path / ID | Auth and feature gate | Input | Success response / event | Errors and concurrency | Requirement IDs |
+|---|---|---|---|---|---|---|
+| `GET` | `/api/{path}` | auth + `{module}.view` | {query schema} | `{ items, totalCount }` | 400/401/403 | REQ-001 |
+| `POST` | `/api/{path}` | auth + `{module}.manage` | {body schema} | 201 + `{module}.{entity}.created` | 400/403/409 | REQ-002 |
+
+State whether each route uses `makeCrudRoute` or a custom guarded command route. Include per-method `metadata`, OpenAPI schemas, scope derivation, idempotency, optimistic locking, and stable public-contract implications.
+
+## Events, Jobs, Notifications, and Cross-Module Flows
+
+| Trigger | Producer | Consumer | Side effect | Retry / idempotency / audit behavior |
+|---|---|---|---|---|
+| `{module}.{entity}.{action}` | `{module}` | `{subscriber}` | {result} | {contract} |
+
+Describe scheduled work, progress, cache invalidation, failure recovery, and optional-module behavior where applicable.
+
+## Security, Privacy, and Compliance
+
+- **Authorization:** {feature gates and record-level scope; never role-name checks.}
+- **Tenant isolation:** {read/write filters and fail-closed behavior.}
+- **Sensitive data:** {encryption map, safe reads, redaction, retention, audit policy.}
+- **Abuse and failure modes:** {enumeration, injection, replay, concurrency, destructive action, secret exposure.}
+
+## Integration Coverage
+
+Tests must be self-contained and map to real API and UI paths.
+
+| Test ID | Level | Setup / fixture | Actions | Assertions | Requirement IDs |
+|---|---|---|---|---|---|
+| TEST-001 | integration | {tenant/org/users/records} | {API or browser flow} | {success + persisted state + event} | REQ-001 |
+| TEST-002 | security | {second tenant / insufficient feature} | {forbidden read/write} | {fail closed; no data leak} | REQ-001 |
+| TEST-003 | UI | {records and permissions} | {loading/empty/error/conflict/keyboard flow} | {observable result} | REQ-002 |
+
+## Implementation Phases
+
+Phases are dependency ordered. Only the current phase may enter implementation; parallel work is limited to independent slices inside that phase. Each phase must leave a working app and close with its own evidence before the next phase starts.
 
-## API Contracts
+### Phase 1 — {Foundation or first complete vertical slice}
 
-{Endpoints, request/response schemas}
+- **Depends on:** none
+- **Outcome:** {user-visible or independently verifiable result}
+- **Why this order / value delivered:** {dependency and measurable business value available at phase completion}
+- **Deliverables:** {specific entities, commands, routes, pages, subscribers, migrations}
+- **Independent slices / estimated commits:** {bounded work that may run in parallel inside this phase only}
+- **Requirements closed:** REQ-001
+- **Tests:** TEST-001, TEST-002
+- **Validation:** `yarn generate`, {focused typecheck/tests/integration paths}
+- **Exit gate:** {observable criteria proving this phase works end to end, including affected UI in light/dark and narrow-width states}
+
+### Phase 2 — {Next complete vertical slice}
+
+- **Depends on:** Phase 1 exit gate
+- **Outcome:** {result}
+- **Why this order / value delivered:** {dependency and measurable business value}
+- **Deliverables:** {specific files/seams}
+- **Independent slices / estimated commits:** {bounded work inside this phase}
+- **Requirements closed:** REQ-002
+- **Tests:** TEST-003
+- **Validation:** {focused commands}
+- **Exit gate:** {observable criteria}
+
+## Requirement Traceability
+
+| Requirement | Journey / surface | Data/API/event contracts | Phase | Tests | Acceptance criterion |
+|---|---|---|---|---|---|
+| REQ-001 | J-001, `/backend/{route}` | `{entity}`, `GET /api/{path}` | Phase 1 | TEST-001, TEST-002 | AC-001 |
+
+Every requirement must map to a phase, at least one test oracle, and a measurable acceptance criterion. No phase may be a catch-all “integration and polish” bucket for behavior required by earlier slices.
+
+## Rollout, Migration, and Rollback
+
+{Migration generation/application boundary, seed/setup work, feature flags, compatibility bridge, observability, rollout order, and reversible rollback steps.}
+
+## Risks and Tradeoffs
+
+| Risk / tradeoff | Impact | Mitigation / detection | Residual risk |
+|---|---|---|---|
+| {risk} | {impact} | {test/metric/guard} | {accepted remainder} |
+
+Cover data integrity and concurrency, cascading/event failures, tenant isolation and privacy, migration/rollback, external-service degradation, scale/storage, and operational detection. Do not use “standard risks” as a substitute for concrete failure scenarios.
 
 ## Acceptance Criteria
 
-- [ ] {Criterion 1}
-- [ ] {Criterion 2}
+- [ ] **AC-001** — {Measurable end-to-end result, including actor and scope.}
+- [ ] **AC-002** — {Measurable failure/safety result.}
+- [ ] Every listed backend surface matches its recorded Open Mercato reference and uses the canonical shell/components, shared API helpers, semantic tokens, and complete loading, empty, error, conflict, keyboard, accessibility, responsive, light-mode, and dark-mode states.
+- [ ] Every affected API and UI path has self-contained integration coverage and the configured validation gate passes.
+
+## Final Compliance Report
+
+| Check | Status | Evidence / resolution |
+|---|---|---|
+| Applicable `AGENTS.md` files and routed guides/skills reviewed | pass/fail | {paths} |
+| Data models, APIs, events, UI, and tests are internally consistent | pass/fail | {traceability rows} |
+| Every workflow completes end to end without a catch-all integration phase | pass/fail | {journeys/phases} |
+| Platform-native reuse and extension points were chosen before custom code | pass/fail | {reuse decisions} |
+| UI contracts identify references, canonical components, and theme/state coverage | pass/fail | {surfaces} |
+| Every phase has dependencies, bounded slices, tests, value, and an observable exit gate | pass/fail | {phases} |
+
+Verdict must be exactly `Ready for implementation` or `Blocked — {unresolved items}`. The document status may change to ready only when every row passes.
+
+## Open Questions
+
+Blocking questions must be resolved before setting `Status: Ready for implementation`.
+
+| ID | Question | Owner | Blocking? | Resolution / decision date |
+|---|---|---|---|---|
+| Q-001 | {question} | {owner} | yes/no | {pending or decision} |
 
 ## Changelog
 
 | Date | Change |
-|------|--------|
-| {date} | Initial spec |
+|---|---|
+| {date} | Initial draft |

package/dist/agentic/shared/ai/trackers/github.md

@@ -1,8 +1,8 @@
 # Tracker provider: GitHub
 
-This file is the GitHub implementation of the tracker operations contract (see `TEMPLATE.md` for the contract itself). Every skill in the collection performs issue/PR state management through **named tracker operations** — `**get-issue**`, `**comment-pr**`, and so on — and this file defines what each operation means for GitHub, using the `gh` CLI.
+This file is the GitHub implementation of the tracker operations contract (see `TEMPLATE.md` for the contract itself). Skills perform issue/PR state management through **named tracker operations** — `**get-issue**`, `**comment-pr**`, and so on — and this file defines what each operation means for GitHub, using the `gh` CLI.
 
-How it is used at runtime: `om-setup-agent-pipeline` copies this file into the repository at `.ai/trackers/github.md`, and the config's `tracker` field selects it. When a skill says "tracker operation **get-pr**", execute the command documented under that operation heading in the repo's copy. The repo's copy is authoritative: teams extend or override any operation by editing it — add flags, swap a command, append repo-specific conventions — and every skill picks the change up on its next run. An operation not covered by an edit keeps its behavior from this file's text as copied.
+At runtime: `om-setup-agent-pipeline` copies this file into the repository at `.ai/trackers/github.md`, and the config's `tracker` field selects it. When a skill says "tracker operation **get-pr**", execute the command documented under that operation heading in the repo's copy. The repo's copy is authoritative: teams extend or override any operation by editing it, and every skill picks the change up on its next run. An operation not covered by an edit keeps its behavior from this file's text as copied.
 
 ## Prerequisites
 
@@ -14,7 +14,7 @@ How it is used at runtime: `om-setup-agent-pipeline` copies this file into the r
 - Issue and PR identifiers are numbers; in text they are written `#123`.
 - A PR is linked to the issue it resolves with `Fixes #{issueId}` (or `Closes #{issueId}`) in the PR body; GitHub then closes the issue on merge. To reference without auto-closing, use a plain issue link.
 - PRs open as **drafts** when a skill says so; a human (or **mark-pr-ready**) promotes them.
-- Claim/lock signals on an issue or PR are: assignee set to the automation user, the `in-progress` label, and a `🤖`-prefixed claim comment. All three are set on claim; the label is guarded (below).
+- Claim/lock signals on an issue or PR are: assignee set to the automation user, the `in-progress` label, and a `🤖`-prefixed claim comment. All three are set on claim; the label is guarded (below). The `ci-monitoring` label is **not** a claim/lock signal: it marks a PR whose work is finished and already reported while an agent watches CI, so a PR carrying `ci-monitoring` without any of the three signals above MUST be treated as unclaimed and is free to claim.
 - Long, multi-line comment bodies are posted with `--body-file` (or a heredoc via process substitution) so formatting is preserved.
 - CI status truth comes from **get-pr-checks**; the set of *required* checks comes from **get-required-checks** (branch protection). When branch protection is not readable (404), treat every reported check as required.
 
@@ -98,6 +98,84 @@ BASE_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
 [ -z "$BASE_BRANCH" ] && BASE_BRANCH="main"
 ```
 
+### Public session-share artifacts
+
+#### publish-session-share
+`{owner}/{repo}`, `{branch}`, `{shareName}`, and a local `{bundleDir}` → atomically publish the four reviewed session-share artifacts on a new public branch and return repository, branch, commit, branch URL, and raw artifact URLs as JSON.
+
+This operation is intentionally strict: the repository must already be public; the branch must be a new slash-free `session-share-…` ref; and the bundle directory must contain regular, non-symlinked `session.json`, `generated-files.zip`, `manifest.json`, and `privacy-report.json` files within the documented size cap. Git blobs, a tree, and a commit are created first; the public ref is created last, so a preparation failure does not expose a partial branch.
+
+```bash
+TARGET_REPO="{owner}/{repo}"
+SHARE_BRANCH="{branch}"
+SHARE_NAME="{shareName}"
+BUNDLE_DIR="{bundleDir}"
+printf '%s' "$TARGET_REPO" | grep -Eq '^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$' || exit 1
+printf '%s' "$SHARE_NAME" | grep -Eq '^[a-z0-9][a-z0-9-]{1,46}[a-z0-9]$' || exit 1
+[ "$SHARE_BRANCH" = "session-share-$SHARE_NAME" ] || exit 1
+[ "$(gh repo view "$TARGET_REPO" --json visibility --jq .visibility)" = "PUBLIC" ] || exit 1
+gh api "repos/${TARGET_REPO}/git/ref/heads/${SHARE_BRANCH}" >/dev/null 2>&1 && exit 1
+
+SESSION_SHARE_TMP=$(mktemp -d)
+trap 'rm -rf "$SESSION_SHARE_TMP"' EXIT HUP INT TERM
+printf '[]\n' > "$SESSION_SHARE_TMP/tree.json"
+TOTAL_BYTES=0
+for ARTIFACT in session.json generated-files.zip manifest.json privacy-report.json; do
+  ARTIFACT_PATH="$BUNDLE_DIR/$ARTIFACT"
+  [ -f "$ARTIFACT_PATH" ] && [ ! -L "$ARTIFACT_PATH" ] || exit 1
+  ARTIFACT_BYTES=$(wc -c < "$ARTIFACT_PATH" | tr -d ' ')
+  TOTAL_BYTES=$((TOTAL_BYTES + ARTIFACT_BYTES))
+  [ "$ARTIFACT_BYTES" -le 26214400 ] && [ "$TOTAL_BYTES" -le 31457280 ] || exit 1
+done
+
+for ARTIFACT in session.json generated-files.zip manifest.json privacy-report.json; do
+  ARTIFACT_PATH="$BUNDLE_DIR/$ARTIFACT"
+  base64 < "$ARTIFACT_PATH" | tr -d '\n' > "$SESSION_SHARE_TMP/content.b64"
+  BLOB_SHA=$(jq -n --rawfile content "$SESSION_SHARE_TMP/content.b64" '{content:$content,encoding:"base64"}' \
+    | gh api -X POST "repos/${TARGET_REPO}/git/blobs" --input - --jq .sha) || exit 1
+  jq --arg path "$ARTIFACT" --arg sha "$BLOB_SHA" \
+    '. + [{path:$path,mode:"100644",type:"blob",sha:$sha}]' \
+    "$SESSION_SHARE_TMP/tree.json" > "$SESSION_SHARE_TMP/tree.next.json" || exit 1
+  mv "$SESSION_SHARE_TMP/tree.next.json" "$SESSION_SHARE_TMP/tree.json"
+done
+
+DEFAULT_BRANCH=$(gh repo view "$TARGET_REPO" --json defaultBranchRef --jq .defaultBranchRef.name) || exit 1
+BASE_COMMIT=$(gh api "repos/${TARGET_REPO}/git/ref/heads/${DEFAULT_BRANCH}" --jq .object.sha) || exit 1
+BASE_TREE=$(gh api "repos/${TARGET_REPO}/git/commits/${BASE_COMMIT}" --jq .tree.sha) || exit 1
+TREE_SHA=$(jq -n --arg base "$BASE_TREE" --slurpfile entries "$SESSION_SHARE_TMP/tree.json" \
+  '{base_tree:$base,tree:$entries[0]}' \
+  | gh api -X POST "repos/${TARGET_REPO}/git/trees" --input - --jq .sha) || exit 1
+COMMIT_SHA=$(jq -n --arg message "session share ${SHARE_NAME}" --arg tree "$TREE_SHA" --arg parent "$BASE_COMMIT" \
+  '{message:$message,tree:$tree,parents:[$parent]}' \
+  | gh api -X POST "repos/${TARGET_REPO}/git/commits" --input - --jq .sha) || exit 1
+jq -n --arg ref "refs/heads/${SHARE_BRANCH}" --arg sha "$COMMIT_SHA" '{ref:$ref,sha:$sha}' \
+  | gh api -X POST "repos/${TARGET_REPO}/git/refs" --input - >/dev/null || exit 1
+
+jq -n \
+  --arg repository "$TARGET_REPO" \
+  --arg branch "$SHARE_BRANCH" \
+  --arg commit "$COMMIT_SHA" \
+  --arg branchUrl "https://github.com/${TARGET_REPO}/tree/${SHARE_BRANCH}" \
+  --arg sessionUrl "https://raw.githubusercontent.com/${TARGET_REPO}/${SHARE_BRANCH}/session.json" \
+  --arg archiveUrl "https://raw.githubusercontent.com/${TARGET_REPO}/${SHARE_BRANCH}/generated-files.zip" \
+  --arg manifestUrl "https://raw.githubusercontent.com/${TARGET_REPO}/${SHARE_BRANCH}/manifest.json" \
+  --arg privacyUrl "https://raw.githubusercontent.com/${TARGET_REPO}/${SHARE_BRANCH}/privacy-report.json" \
+  '{repository:$repository,branch:$branch,commit:$commit,branchUrl:$branchUrl,artifacts:{session:$sessionUrl,archive:$archiveUrl,manifest:$manifestUrl,privacy:$privacyUrl}}'
+```
+
+#### delete-session-share
+`{owner}/{repo}`, `{branch}`, and `{shareName}` → remove only the exact derived session-share ref after a failed issue creation or an explicit retention cleanup request. Deleting a public ref cannot guarantee erasure from clones, forks, caches, logs, or archives.
+
+```bash
+TARGET_REPO="{owner}/{repo}"
+SHARE_BRANCH="{branch}"
+SHARE_NAME="{shareName}"
+printf '%s' "$TARGET_REPO" | grep -Eq '^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$' || exit 1
+printf '%s' "$SHARE_NAME" | grep -Eq '^[a-z0-9][a-z0-9-]{1,46}[a-z0-9]$' || exit 1
+[ "$SHARE_BRANCH" = "session-share-$SHARE_NAME" ] || exit 1
+gh api -X DELETE "repos/${TARGET_REPO}/git/refs/heads/${SHARE_BRANCH}"
+```
+
 ### Issues
 
 #### get-issue
@@ -109,7 +187,9 @@ gh issue view {issueId} --repo {owner}/{repo} --json number,title,body,state,aut
 #### search-issues
 Query (text, `in:title,body`, state) → matching issues.
 ```bash
-gh issue list --repo {owner}/{repo} --state open --search "<query> in:title,body" --json number,title,url
+ISSUE_STATE="{state}"
+case "$ISSUE_STATE" in open|closed|all) ;; *) exit 1 ;; esac
+gh issue list --repo {owner}/{repo} --state "$ISSUE_STATE" --search "<query> in:title,body" --json number,title,url
 ```
 
 #### create-issue
@@ -130,6 +210,12 @@ gh issue close {issueId} --repo {owner}/{repo} --reason completed --comment "<co
 gh issue comment {issueId} --repo {owner}/{repo} --body "<body>"
 ```
 
+#### update-issue
+`{issueId}`, new title and/or body (use a body-file for multi-line bodies). Edits the issue's own fields; does not touch labels or assignees (those have their own operations).
+```bash
+gh issue edit {issueId} --repo {owner}/{repo} --title "<title>" --body-file <file>
+```
+
 #### assign-issue / unassign-issue
 ```bash
 gh issue edit {issueId} --repo {owner}/{repo} --add-assignee "<login>"
@@ -151,6 +237,12 @@ gh api repos/{owner}/{repo}/issues/comments/{commentId} --jq '{body,user:.user.l
 gh api repos/{owner}/{repo}/issues/{number}/comments --jq '.[] | {id,user:.user.login,body}'
 ```
 
+#### update-comment
+`{commentId}`, new body → rewrite an existing conversation comment in place (works for issue and PR conversation comments alike). This is how marker-idempotent comments (label rationale, verification, claim take-overs) are updated on re-runs: find your `🤖 …` marker via **list-issue-comments**, then update that comment instead of posting a new one. Use a body file so multi-line bodies survive.
+```bash
+gh api -X PATCH repos/{owner}/{repo}/issues/comments/{commentId} -F body=@<path>
+```
+
 ### Pull requests
 
 #### get-pr
@@ -181,6 +273,17 @@ PR_URL=$(gh pr view --json url --jq .url)
 PR_NUMBER=$(gh pr view --json number --jq .number)
 ```
 
+#### update-pr
+`{prNumber}`, new title and/or new body → the PR's own title/body rewritten in place (not a comment), e.g. reframing a doc-originated spec PR that grew a feature implementation. Pass whichever of `--title` / `--body-file` changed; omit the other. Use a body file so multi-line bodies survive.
+```bash
+gh pr edit {prNumber} --title "<title>"
+gh pr edit {prNumber} --body-file <path-or-process-substitution>
+```
+If `gh pr edit` silently no-ops in this repo (some GitHub setups do), fall back to the REST API:
+```bash
+gh api -X PATCH repos/{owner}/{repo}/pulls/{prNumber} -f title="<title>" -f body="$(cat <path>)"
+```
+
 #### comment-pr
 `{prNumber}`, body. For long structured comments:
 ```bash
@@ -365,6 +468,7 @@ gh label create skip-qa           --color 0e8a16 --description "Low risk, QA not
 gh label create qa-approved       --color 0e8a16 --description "Manual QA passed"
 gh label create qa-self-verified  --color c5def5 --description "Self-QA exception used"
 gh label create in-progress       --color c5def5 --description "An automated skill is working on this"
+gh label create ci-monitoring     --color 00b8d9 --description "Work complete and reported; agent is watching CI results"
 gh label create do-not-close      --color c5def5 --description "Humans only: never auto-close this issue"
 gh label create priority-low      --color e4e669 --description "Cosmetic or follow-up work"
 gh label create priority-medium   --color fbca04 --description "Ordinary bug or feature"

package/dist/agentic/shared/scripts/agent-harness-tool-server.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+
+const MAX_READ_BYTES = 256 * 1024
+const MAX_WRITE_BYTES = 256 * 1024
+const SAFE_TEXT_EXTENSIONS = new Set([
+  '.cjs', '.css', '.graphql', '.html', '.js', '.json', '.jsx', '.md', '.mdx',
+  '.mjs', '.prisma', '.sql', '.ts', '.tsx', '.txt', '.xml', '.yaml', '.yml',
+])
+const FORBIDDEN_SEGMENTS = new Set(['.git', '.docker', '.kube', '.aws', '.ssh', '.codex', '.claude', '.next', 'dist'])
+const FORBIDDEN_BASENAMES = new Set([
+  '.npmrc', '.netrc', '.pypirc', '.git-credentials', 'secrets.json', 'credentials.json',
+  'service-account-credentials.json',
+])
+const FORBIDDEN_SECRET_EXTENSIONS = new Set(['.key', '.pem', '.p12', '.pfx'])
+// Declarative provenance for a read outside the canonical example root. The server does
+// NOT authorize on it — the read allowlist still governs what may be read — but it refuses
+// an unrecognized value so the runner trace cannot carry an arbitrary string into the
+// evaluator's reason-gated fallback accounting. Mirrors `cases.schema.json`.
+const INSTALLED_FALLBACK_REASON_CODES = new Set([
+  'SPECIALIST_ROUTE_NOT_DECLARED',
+  'INSTALLED_VERSION_CONTRACT_MISMATCH',
+])
+
+function fail(message) {
+  process.stderr.write(`agent-harness-tool-server: ${message}\n`)
+  process.exit(2)
+}
+
+function isInside(root, candidate) {
+  const relative = path.relative(root, candidate)
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative))
+}
+
+function isInstalledSourcePath(value, allowPatterns) {
+  const normalized = value.replaceAll('\\', '/')
+  const segments = normalized.split('/')
+  if (segments.length < 5 || segments[0] !== 'node_modules' || segments[1] !== '@open-mercato' || segments[3] !== 'src') return false
+  if (!segments[2] || segments.slice(4).some((entry) => !entry)) return false
+  return allowPatterns || !normalized.includes('*') && !normalized.includes('?')
+}
+
+function safeRelative(value, { allowInstalledSourcePatterns = false } = {}) {
+  if (typeof value !== 'string' || !value || value.includes('\0') || path.isAbsolute(value)) return false
+  const normalized = value.replaceAll('\\', '/')
+  if (normalized === '.' || normalized.startsWith('../') || normalized.includes('/../')) return false
+  const segments = normalized.split('/')
+  const basename = segments.at(-1) ?? ''
+  const installedSource = segments.includes('node_modules')
+  if (installedSource && !isInstalledSourcePath(normalized, allowInstalledSourcePatterns)) return false
+  if ((installedSource ? segments.slice(4) : segments).some((entry) => FORBIDDEN_SEGMENTS.has(entry))) return false
+  if (normalized === '.ai/harness' || normalized.startsWith('.ai/harness/')) return false
+  if (basename === '.env' || basename.startsWith('.env.') || FORBIDDEN_BASENAMES.has(basename)) return false
+  return !FORBIDDEN_SECRET_EXTENSIONS.has(path.extname(basename).toLowerCase())
+}
+
+function globToRegExp(pattern) {
+  let source = '^'
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index]
+    if (char === '*' && pattern[index + 1] === '*') { source += '.*'; index += 1 }
+    else if (char === '*') source += '[^/]*'
+    else if (char === '?') source += '[^/]'
+    else source += char.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  }
+  return new RegExp(`${source}$`)
+}
+
+const rootArg = process.argv[2]
+const mode = process.argv[3]
+let allowedReads
+let allowedWrites
+let immutableRoots
+try { allowedReads = JSON.parse(process.argv[4] ?? '[]') } catch { fail('allowed read set is invalid JSON') }
+try { allowedWrites = JSON.parse(process.argv[5] ?? '[]') } catch { fail('allowed write set is invalid JSON') }
+try { immutableRoots = JSON.parse(process.env.OM_HARNESS_IMMUTABLE_ROOTS ?? '[]') } catch { fail('immutable root set is invalid JSON') }
+if (!path.isAbsolute(rootArg ?? '')) fail('root must be absolute')
+if (!['read-only', 'writable'].includes(mode)) fail('mode must be read-only or writable')
+if (!Array.isArray(allowedReads) || allowedReads.some((entry) => !safeRelative(entry, { allowInstalledSourcePatterns: true }) || ['*', '**'].includes(entry))) fail('allowed read set is invalid')
+if (!Array.isArray(allowedWrites) || allowedWrites.some((entry) => !safeRelative(entry))) fail('allowed write set is invalid')
+if (!Array.isArray(immutableRoots) || immutableRoots.some((entry) => !safeRelative(entry) || entry.includes('*') || entry.includes('?'))) fail('immutable root set is invalid')
+const root = fs.realpathSync(rootArg)
+const readMatchers = allowedReads.map(globToRegExp)
+const writeMatchers = allowedWrites.map(globToRegExp)
+const immutablePrefixes = immutableRoots.map((entry) => entry.replaceAll('\\', '/'))
+
+// Root immutability precedence: declared read-only roots are resolved BEFORE the write
+// allowlist, so a broader writable grant such as `src/modules/**` can never reach inside one.
+function isImmutablePath(normalized) {
+  return immutablePrefixes.some((prefix) => normalized === prefix || normalized.startsWith(`${prefix}/`))
+}
+
+function resolveRead(relative) {
+  if (!safeRelative(relative)) throw new Error('path is outside the allowed app context')
+  const normalized = relative.replaceAll('\\', '/')
+  if (!readMatchers.some((matcher) => matcher.test(normalized))) throw new Error('path is outside the case read allowlist')
+  const lexical = path.resolve(root, relative)
+  if (!isInside(root, lexical)) throw new Error('path escapes the app root')
+  const real = fs.realpathSync(lexical)
+  if (isInstalledSourcePath(normalized, false)) {
+    const dependencyRoot = fs.realpathSync(path.join(root, 'node_modules'))
+    if (!isInside(dependencyRoot, real)) throw new Error('installed source resolves outside the protected dependency root')
+  } else if (!isInside(root, real)) throw new Error('path resolves outside the app root')
+  const stat = fs.statSync(real)
+  if (!stat.isFile() || stat.size > MAX_READ_BYTES) throw new Error('path must be a bounded regular file')
+  if (!SAFE_TEXT_EXTENSIONS.has(path.extname(real).toLowerCase()) && path.basename(real) !== 'AGENTS.md') throw new Error('path is not an allowed text file')
+  return { real, stat }
+}
+
+function resolveWrite(relative) {
+  if (mode !== 'writable') throw new Error('writes are disabled for this evaluation')
+  if (!safeRelative(relative)) throw new Error('path is outside the case write allowlist')
+  const normalized = relative.replaceAll('\\', '/')
+  if (isImmutablePath(normalized)) throw new Error('path is inside a read-only declared root and can never be written')
+  if (!writeMatchers.some((matcher) => matcher.test(normalized))) throw new Error('path is outside the case write allowlist')
+  const lexical = path.resolve(root, relative)
+  if (!isInside(root, lexical)) throw new Error('path escapes the app root')
+  let cursor = path.dirname(lexical)
+  const missing = []
+  while (cursor !== root && !fs.existsSync(cursor)) { missing.push(cursor); cursor = path.dirname(cursor) }
+  if (!isInside(root, cursor)) throw new Error('write ancestor escapes the app root')
+  for (let current = cursor; current !== root; current = path.dirname(current)) {
+    const stat = fs.lstatSync(current)
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('write ancestor must be a regular directory')
+  }
+  if (fs.existsSync(lexical)) {
+    const stat = fs.lstatSync(lexical)
+    if (!stat.isFile() || stat.isSymbolicLink() || !isInside(root, fs.realpathSync(lexical))) throw new Error('write target must be a contained regular file')
+  }
+  for (const directory of missing.reverse()) fs.mkdirSync(directory, { mode: 0o700 })
+  return lexical
+}
+
+const tools = [
+  {
+    name: 'read',
+    description: 'Read one exact app-relative instruction, fact, source, or allowed target file. Fact-linked @open-mercato package source reads are allowed; absolute paths, discovery, credentials, dependency writes, Git, and harness internals are rejected.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['path'],
+      properties: {
+        path: { type: 'string' },
+        reason: { type: 'string', enum: [...INSTALLED_FALLBACK_REASON_CODES] },
+        capabilityId: { type: 'string' },
+      },
+    },
+  },
+  ...(mode === 'writable' ? [{
+    name: 'write',
+    description: 'Replace one exact app-relative file declared in the current case write allowlist. The content must be the complete file.',
+    inputSchema: { type: 'object', additionalProperties: false, required: ['path', 'content'], properties: { path: { type: 'string' }, content: { type: 'string' } } },
+  }] : []),
+]
+
+function result(id, value) {
+  process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, result: value })}\n`)
+}
+
+function toolResult(id, text, isError = false) {
+  result(id, { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) })
+}
+
+function handle(message) {
+  if (!message || message.jsonrpc !== '2.0') return
+  if (message.method === 'initialize') {
+    result(message.id, {
+      protocolVersion: message.params?.protocolVersion ?? '2025-06-18',
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: { name: 'open-mercato-agent-harness', version: '1.0.0' },
+    })
+    return
+  }
+  if (message.method === 'ping') { result(message.id, {}); return }
+  if (message.method === 'tools/list') { result(message.id, { tools }); return }
+  if (message.method !== 'tools/call') return
+  try {
+    const name = message.params?.name
+    const input = message.params?.arguments ?? {}
+    if (name === 'read') {
+      if (input.reason !== undefined && !INSTALLED_FALLBACK_REASON_CODES.has(input.reason)) {
+        throw new Error('read reason must be a declared installed-source fallback reason code')
+      }
+      if (input.capabilityId !== undefined
+        && (typeof input.capabilityId !== 'string' || !/^[a-z0-9][a-z0-9.-]{0,63}$/.test(input.capabilityId))) {
+        throw new Error('read capabilityId must be a bounded surface-inventory capability id')
+      }
+      const { real } = resolveRead(input.path)
+      toolResult(message.id, fs.readFileSync(real, 'utf8'))
+      return
+    }
+    if (name === 'write') {
+      if (typeof input.content !== 'string' || Buffer.byteLength(input.content) > MAX_WRITE_BYTES) throw new Error('content must be a bounded string')
+      const target = resolveWrite(input.path)
+      const temporary = `${target}.om-harness-${process.pid}.tmp`
+      fs.writeFileSync(temporary, input.content, { encoding: 'utf8', mode: 0o600, flag: 'wx' })
+      fs.renameSync(temporary, target)
+      toolResult(message.id, `wrote ${input.path}`)
+      return
+    }
+    throw new Error('unknown tool')
+  } catch (error) {
+    toolResult(message.id, error instanceof Error ? error.message : String(error), true)
+  }
+}
+
+let buffer = ''
+process.stdin.setEncoding('utf8')
+process.stdin.on('data', (chunk) => {
+  buffer += chunk
+  while (true) {
+    const newline = buffer.indexOf('\n')
+    if (newline < 0) break
+    const line = buffer.slice(0, newline).replace(/\r$/, '')
+    buffer = buffer.slice(newline + 1)
+    if (!line.trim()) continue
+    try { handle(JSON.parse(line)) } catch (error) {
+      process.stderr.write(`agent-harness-tool-server: invalid request: ${error instanceof Error ? error.message : String(error)}\n`)
+    }
+  }
+})