traverse-framework · enricopiovesan · Jul 6, 2026 · Jul 6, 2026
diff --git a/.agents/skills/app-refs-ops/SKILL.md b/.agents/skills/app-refs-ops/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: "app-refs-ops"
-description: "Start or resume the App-References operating model when the user says APP REFS OPS, asks to start app-refs ops/dev work, asks for the ready-ticket worker, PR finisher, or backlog gardener, or wants Codex to pick ready Project 2 work and run the App-References coordination process."
+description: "Start or resume the App-References operating model when the user says APP REFS OPS. Runs continuously until no Ready work remains or a hard blocker stops progress — merge green PRs, claim Ready tickets, implement, release, repeat."
 ---
 
 # App-References Ops
@@ -23,23 +23,76 @@ The target repo is `traverse-framework/reference-apps` (GitHub slug; product nam
 
 Read `docs/traverse-starter-plan.md` and `.specify/memory/constitution.md` before any implementation work.
 
+## Continuous run mode (default)
+
+`/app-refs-ops` is **not** a single-ticket session. When triggered, run the full ops loop **until idle** — do not stop after one PR, one merge, or one status summary, and do not ask the user "want me to continue?" between tickets.
+
+### Ops loop
+
+Repeat until a stop condition (below):
+
+1. **PR finisher** — inspect open PRs owned by this agent or blocking Ready work; fix CI/review issues; merge when green; rebase if behind `main`.
+2. **Release** — after merge: remove `agent:*` label, set Agent → Unassigned, Status → Done, close issue (see Release sequence below).
+3. **Ready-ticket worker** — query Ready items; run pre-flight on the next unclaimed ticket; claim; implement; open PR.
+4. **Validate** — run applicable local gates; wait for CI; merge when green; go to step 2.
+
+One issue at a time per agent thread, but **many issues per ops invocation** — keep cycling.
+
+### Stop conditions (only these)
+
+Stop reporting only when **all** are true:
+
+- No open PRs from this ops run need attention (merged or explicitly handed off).
+- No Project 2 items remain in `Ready` that pass pre-flight for this agent.
+- No fixable CI failures on open PRs you opened this session.
+
+**Do not stop** merely because one ticket shipped. **Do not pause** for merge approval if CI is green and the user invoked `/app-refs-ops` for autonomous end-to-end execution — merge and continue.
+
+### When to ask the user
+
+Ask only for:
+
+- Product or architecture decisions (`needs-enrico`)
+- Merge approval if the user explicitly said not to merge autonomously in this session
+- Hard blockers outside this repo (Traverse runtime feature missing, credentials, environment)
+
+Everything else — claim, implement, PR, CI fix, merge, release — proceed autonomously.
+
+### Release sequence (after merge)
+
+```bash
+gh issue edit <NUMBER> --repo traverse-framework/reference-apps --remove-label "<AGENT_LABEL>"
+
+ITEM_ID=$(gh project item-list 2 --owner traverse-framework --format json --limit 300 \
+  --jq '.items[] | select(.content.number == <NUMBER>) | .id')
+
+gh project item-edit --project-id PVT_kwDOEbiBt84BbzAz --id "$ITEM_ID" \
+  --field-id PVTSSF_lADOEbiBt84BbzAzzhWjEik --single-select-option-id 8ebf043b
+
+gh project item-edit --project-id PVT_kwDOEbiBt84BbzAz --id "$ITEM_ID" \
+  --field-id PVTSSF_lADOEbiBt84BbzAzzhWg5OQ --single-select-option-id 98236657
+
+gh issue close <NUMBER> --repo traverse-framework/reference-apps
+```
+
 ## Workflow
 
 1. Read `.specify/memory/constitution.md` before any implementation work.
 2. Read `AGENTS.md` and follow the agent coordination rules.
 3. Inspect current GitHub and Project 2 state.
-4. Prefer finishing existing open PRs before claiming new Ready work.
-5. If no active PR needs attention, pick one Ready Project 2 issue.
-6. Before work on an issue, run the pre-flight checks from `AGENTS.md`:
+4. Enter the **ops loop** above — do not exit after step 10 once; loop until idle.
+5. Before work on an issue, run the pre-flight checks from `AGENTS.md`:
    - issue must not have any `agent:*` label
    - no remote `*/issue-NNN-*` branch may exist
-7. If pre-flight passes, claim the issue:
+   - Project 2 status must be `Ready`
+6. If pre-flight passes, claim the issue:
    - add your agent label (see Agent Registry in `AGENTS.md`)
    - set Project 2 `Agent` to your tool
    - set Project 2 `Status` to `In Progress`
-8. Use a dedicated `<agent>/issue-NNN-*` branch (see Agent Registry in `AGENTS.md`).
-9. Keep work scoped to the claimed issue and the UI-only architecture boundary.
-10. Open a dedicated PR with the required sections (Summary, Definition of Done, Validation).
+7. Use a dedicated `<agent>/issue-NNN-*` branch (see Agent Registry in `AGENTS.md`).
+8. Keep work scoped to the claimed issue and the UI-only architecture boundary.
+9. Open a dedicated PR with the required sections (Summary, Definition of Done, Validation).
+10. Validate, merge when green, release, then **return to step 4** for the next Ready ticket.
 
 ## Project 2 IDs
 
@@ -133,9 +186,11 @@ Minimality must never push business logic into the UI, import private Traverse i
 
 ## Operating Lanes
 
-- **Ready-ticket worker**: claim one Ready Project 2 issue and implement it end to end.
-- **PR finisher**: inspect open PRs, fix CI/review issues, and merge when green.
-- **Backlog gardener**: audit Project 2 statuses, labels, blockers, and notes.
+All lanes run inside the **continuous ops loop** — none of them end the session after one pass.
+
+- **PR finisher**: inspect open PRs, fix CI/review issues, merge when green, release linked issues — then pick the next Ready ticket.
+- **Ready-ticket worker**: claim one Ready issue, implement end to end, merge, release — then claim the next Ready issue.
+- **Backlog gardener**: audit Project 2 statuses, labels, blockers, and notes — only when no Ready work is available or as hygiene between tickets.
 
 ## Guardrails
 
@@ -144,5 +199,7 @@ Minimality must never push business logic into the UI, import private Traverse i
 - Do not claim work already owned by another agent.
 - Do not broaden scope beyond the issue and the UI-only architecture boundary.
 - Create follow-up tickets for non-blocking improvements instead of expanding an active slice.
+- **Do not stop the ops loop after one ticket** — run until Ready queue is empty or a stop condition applies.
+- **Do not ask the user to continue** between tickets during `/app-refs-ops`; that breaks autonomous end-to-end execution.
 
 For the full operating model, see `docs/multi-thread-workflow.md`.
diff --git a/.claude/commands/app-refs-ops.md b/.claude/commands/app-refs-ops.md
@@ -1,6 +1,6 @@
 ---
 name: "app-refs-ops"
-description: "Start or resume the App-References operating model when the user says APP REFS OPS, asks to start app-refs ops/dev work, asks for the ready-ticket worker, PR finisher, or backlog gardener, or wants Codex to pick ready Project 2 work and run the App-References coordination process."
+description: "Start or resume the App-References operating model when the user says APP REFS OPS. Runs continuously until no Ready work remains or a hard blocker stops progress — merge green PRs, claim Ready tickets, implement, release, repeat."
 ---
 
 # App-References Ops
@@ -23,23 +23,76 @@ The target repo is `traverse-framework/reference-apps` (GitHub slug; product nam
 
 Read `docs/traverse-starter-plan.md` and `.specify/memory/constitution.md` before any implementation work.
 
+## Continuous run mode (default)
+
+`/app-refs-ops` is **not** a single-ticket session. When triggered, run the full ops loop **until idle** — do not stop after one PR, one merge, or one status summary, and do not ask the user "want me to continue?" between tickets.
+
+### Ops loop
+
+Repeat until a stop condition (below):
+
+1. **PR finisher** — inspect open PRs owned by this agent or blocking Ready work; fix CI/review issues; merge when green; rebase if behind `main`.
+2. **Release** — after merge: remove `agent:*` label, set Agent → Unassigned, Status → Done, close issue (see Release sequence below).
+3. **Ready-ticket worker** — query Ready items; run pre-flight on the next unclaimed ticket; claim; implement; open PR.
+4. **Validate** — run applicable local gates; wait for CI; merge when green; go to step 2.
+
+One issue at a time per agent thread, but **many issues per ops invocation** — keep cycling.
+
+### Stop conditions (only these)
+
+Stop reporting only when **all** are true:
+
+- No open PRs from this ops run need attention (merged or explicitly handed off).
+- No Project 2 items remain in `Ready` that pass pre-flight for this agent.
+- No fixable CI failures on open PRs you opened this session.
+
+**Do not stop** merely because one ticket shipped. **Do not pause** for merge approval if CI is green and the user invoked `/app-refs-ops` for autonomous end-to-end execution — merge and continue.
+
+### When to ask the user
+
+Ask only for:
+
+- Product or architecture decisions (`needs-enrico`)
+- Merge approval if the user explicitly said not to merge autonomously in this session
+- Hard blockers outside this repo (Traverse runtime feature missing, credentials, environment)
+
+Everything else — claim, implement, PR, CI fix, merge, release — proceed autonomously.
+
+### Release sequence (after merge)
+
+```bash
+gh issue edit <NUMBER> --repo traverse-framework/reference-apps --remove-label "<AGENT_LABEL>"
+
+ITEM_ID=$(gh project item-list 2 --owner traverse-framework --format json --limit 300 \
+  --jq '.items[] | select(.content.number == <NUMBER>) | .id')
+
+gh project item-edit --project-id PVT_kwDOEbiBt84BbzAz --id "$ITEM_ID" \
+  --field-id PVTSSF_lADOEbiBt84BbzAzzhWjEik --single-select-option-id 8ebf043b
+
+gh project item-edit --project-id PVT_kwDOEbiBt84BbzAz --id "$ITEM_ID" \
+  --field-id PVTSSF_lADOEbiBt84BbzAzzhWg5OQ --single-select-option-id 98236657
+
+gh issue close <NUMBER> --repo traverse-framework/reference-apps
+```
+
 ## Workflow
 
 1. Read `.specify/memory/constitution.md` before any implementation work.
 2. Read `AGENTS.md` and follow the agent coordination rules.
 3. Inspect current GitHub and Project 2 state.
-4. Prefer finishing existing open PRs before claiming new Ready work.
-5. If no active PR needs attention, pick one Ready Project 2 issue.
-6. Before work on an issue, run the pre-flight checks from `AGENTS.md`:
+4. Enter the **ops loop** above — do not exit after step 10 once; loop until idle.
+5. Before work on an issue, run the pre-flight checks from `AGENTS.md`:
    - issue must not have any `agent:*` label
    - no remote `*/issue-NNN-*` branch may exist
-7. If pre-flight passes, claim the issue:
+   - Project 2 status must be `Ready`
+6. If pre-flight passes, claim the issue:
    - add your agent label (see Agent Registry in `AGENTS.md`)
    - set Project 2 `Agent` to your tool
    - set Project 2 `Status` to `In Progress`
-8. Use a dedicated `<agent>/issue-NNN-*` branch (see Agent Registry in `AGENTS.md`).
-9. Keep work scoped to the claimed issue and the UI-only architecture boundary.
-10. Open a dedicated PR with the required sections (Summary, Definition of Done, Validation).
+7. Use a dedicated `<agent>/issue-NNN-*` branch (see Agent Registry in `AGENTS.md`).
+8. Keep work scoped to the claimed issue and the UI-only architecture boundary.
+9. Open a dedicated PR with the required sections (Summary, Definition of Done, Validation).
+10. Validate, merge when green, release, then **return to step 4** for the next Ready ticket.
 
 ## Project 2 IDs
 
@@ -133,9 +186,11 @@ Minimality must never push business logic into the UI, import private Traverse i
 
 ## Operating Lanes
 
-- **Ready-ticket worker**: claim one Ready Project 2 issue and implement it end to end.
-- **PR finisher**: inspect open PRs, fix CI/review issues, and merge when green.
-- **Backlog gardener**: audit Project 2 statuses, labels, blockers, and notes.
+All lanes run inside the **continuous ops loop** — none of them end the session after one pass.
+
+- **PR finisher**: inspect open PRs, fix CI/review issues, merge when green, release linked issues — then pick the next Ready ticket.
+- **Ready-ticket worker**: claim one Ready issue, implement end to end, merge, release — then claim the next Ready issue.
+- **Backlog gardener**: audit Project 2 statuses, labels, blockers, and notes — only when no Ready work is available or as hygiene between tickets.
 
 ## Guardrails
 
@@ -144,5 +199,7 @@ Minimality must never push business logic into the UI, import private Traverse i
 - Do not claim work already owned by another agent.
 - Do not broaden scope beyond the issue and the UI-only architecture boundary.
 - Create follow-up tickets for non-blocking improvements instead of expanding an active slice.
+- **Do not stop the ops loop after one ticket** — run until Ready queue is empty or a stop condition applies.
+- **Do not ask the user to continue** between tickets during `/app-refs-ops`; that breaks autonomous end-to-end execution.
 
 For the full operating model, see `docs/multi-thread-workflow.md`.
diff --git a/AGENTS.md b/AGENTS.md
@@ -19,6 +19,18 @@ This repo is **UI-only**. Traverse runtime and business logic live outside this
 | Linux (GTK4 + Rust) | Shipped | `apps/traverse-starter/linux-gtk/` |
 | CLI (Rust) | Shipped | `apps/traverse-starter/cli-rust/` |
 
+### doc-approval clients (Phase 1 submitter — shipped)
+
+| Platform | Status | Path |
+|---|---|---|
+| Web (React + TypeScript) | Shipped | `apps/doc-approval/web-react/` |
+| iOS (SwiftUI) | Shipped | `apps/doc-approval/ios-swift/` |
+| macOS (SwiftUI + AppKit) | Shipped | `apps/doc-approval/macos-swift/` |
+| Android (Jetpack Compose) | Shipped | `apps/doc-approval/android-compose/` |
+| Windows (WinUI 3) | Shipped | `apps/doc-approval/windows-winui/` |
+| Linux (GTK4 + Rust) | Shipped | `apps/doc-approval/linux-gtk/` |
+| CLI (Rust) | Shipped | `apps/doc-approval/cli-rust/` |
+
 ### Ready to claim (query live board)
 
 ```bash
@@ -30,6 +42,7 @@ gh project item-list 2 --owner traverse-framework --format json --limit 300 \
 
 - **Web SSE refactor** ([#43](https://github.com/traverse-framework/reference-apps/issues/43)) — replace polling with runtime SSE; blocked on Traverse #525, #526, #527
 - **Platform SSE upgrade (Phase 2)** — iOS/macOS/Android/Windows/Linux/CLI Phase 1 scaffolds use HTTP polling; SSE blocked on same Traverse issues
+- **doc-approval shared core** ([#72](https://github.com/traverse-framework/reference-apps/issues/72), [#73](https://github.com/traverse-framework/reference-apps/issues/73)) — extract shared Swift/Rust client packages; blocked on Phase 2 SSE / shared crate design
 
 Update this section when a PR changes platform status (see PR template checklist).
 
@@ -45,6 +58,14 @@ apps/
     windows-winui/       # WinUI 3 Windows client
     linux-gtk/           # GTK4 + Rust Linux client
     cli-rust/            # Rust CLI client
+  doc-approval/
+    web-react/           # React submitter UI
+    ios-swift/           # SwiftUI iOS client
+    macos-swift/         # SwiftUI macOS client
+    android-compose/     # Jetpack Compose Android client
+    windows-winui/       # WinUI 3 Windows client
+    linux-gtk/           # GTK4 + Rust Linux client
+    cli-rust/            # Rust CLI client
 .agents/skills/
   app-refs-ops/          # Ops skill for Project 2 work
 .specify/memory/         # Constitution and governing principles

diff --git a/README.md b/README.md
@@ -70,6 +70,18 @@ All clients are UI-only shells — they invoke the runtime and render structured
 | Linux (GTK4 + Rust) | Shipped | [`apps/traverse-starter/linux-gtk/`](apps/traverse-starter/linux-gtk/) |
 | CLI (Rust) | Shipped | [`apps/traverse-starter/cli-rust/`](apps/traverse-starter/cli-rust/) |
 
+### doc-approval (Phase 1 submitter)
+
+| Platform | Status | Path |
+|---|---|---|
+| Web (React + TypeScript) | Shipped | [`apps/doc-approval/web-react/`](apps/doc-approval/web-react/) |
+| iOS (SwiftUI) | Shipped | [`apps/doc-approval/ios-swift/`](apps/doc-approval/ios-swift/) |
+| macOS (SwiftUI + AppKit) | Shipped | [`apps/doc-approval/macos-swift/`](apps/doc-approval/macos-swift/) |
+| Android (Jetpack Compose) | Shipped | [`apps/doc-approval/android-compose/`](apps/doc-approval/android-compose/) |
+| Windows (WinUI 3) | Shipped | [`apps/doc-approval/windows-winui/`](apps/doc-approval/windows-winui/) |
+| Linux (GTK4 + Rust) | Shipped | [`apps/doc-approval/linux-gtk/`](apps/doc-approval/linux-gtk/) |
+| CLI (Rust) | Shipped | [`apps/doc-approval/cli-rust/`](apps/doc-approval/cli-rust/) |
+
 ## Development
 
 ```bash
@@ -100,4 +112,4 @@ Active blockers on [Project 2](https://github.com/orgs/traverse-framework/projec
 
 - **SSE state subscription** ([#43](https://github.com/traverse-framework/reference-apps/issues/43)) — replace polling with runtime SSE; blocked on [Traverse #525](https://github.com/traverse-framework/Traverse/issues/525), [#526](https://github.com/traverse-framework/Traverse/issues/526), [#527](https://github.com/traverse-framework/Traverse/issues/527). All platform clients inherit this blocker for Phase 2 SSE upgrade.
 - **meeting-notes web-react** ([#57](https://github.com/traverse-framework/reference-apps/issues/57)) — second domain app (list-type output); blocked pending runtime capability work.
-- **doc-approval scaffolds** ([#65](https://github.com/traverse-framework/reference-apps/issues/65)–[#73](https://github.com/traverse-framework/reference-apps/issues/73)) — submitter + approver surfaces across Web, iOS, macOS, Android, Windows, Linux, CLI, and shared core packages; blocked pending domain capability registration in Traverse.
+- **doc-approval shared core** ([#72](https://github.com/traverse-framework/reference-apps/issues/72), [#73](https://github.com/traverse-framework/reference-apps/issues/73)) — extract shared Swift/Rust client packages for iOS/macOS and linux-gtk/cli-rust; Phase 2 work blocked on SSE and crate design.
diff --git a/docs/design-language.md b/docs/design-language.md
@@ -69,6 +69,18 @@ The UI renders these fields exactly as the runtime provides them — never compu
 | Linux (GTK4 + Rust) | `apps/traverse-starter/linux-gtk/` | Shipped |
 | CLI (Rust) | `apps/traverse-starter/cli-rust/` | Shipped |
 
+### doc-approval (Phase 1 submitter)
+
+| Platform | Path | Status |
+|---|---|---|
+| Web (React) | `apps/doc-approval/web-react/` | Shipped |
+| iOS (SwiftUI) | `apps/doc-approval/ios-swift/` | Shipped |
+| macOS (SwiftUI + AppKit) | `apps/doc-approval/macos-swift/` | Shipped |
+| Android (Jetpack Compose) | `apps/doc-approval/android-compose/` | Shipped |
+| Windows (WinUI 3) | `apps/doc-approval/windows-winui/` | Shipped |
+| Linux (GTK4 + Rust) | `apps/doc-approval/linux-gtk/` | Shipped |
+| CLI (Rust) | `apps/doc-approval/cli-rust/` | Shipped |
+
 New platform clients must link to this doc in their issue Definition of Done.
 
 ## Governance

diff --git a/docs/multi-thread-workflow.md b/docs/multi-thread-workflow.md
@@ -76,13 +76,15 @@ Use this short trigger when you want Codex to start or resume the App-References
 APP REFS OPS
 ```
 
-When Enrico says `APP REFS OPS`, Codex should:
+When Enrico says `APP REFS OPS`, the agent should run the **continuous ops loop** (see `.agents/skills/app-refs-ops/SKILL.md`) until idle:
 
-- Start or resume the **ready-ticket worker**: pick one Ready Project 2 ticket, follow `AGENTS.md`, claim it, set `In Progress`, implement on one branch, open one PR.
-- Start or resume the **PR finisher**: inspect open PRs, fix CI/review issues, merge green PRs, update linked issues and Project 2 state.
-- Start or resume the **backlog gardener**: audit Project 2 statuses, labels, blockers, and notes; ensure items have the right status; create missing tickets with full Definition of Done.
-- Do all feasible work autonomously. Ask only when a product or architecture decision requires Enrico.
-- Run lean: filtered Project 2 queries, bounded command output, focused diffs, summarized CI results.
+- **PR finisher** → merge green PRs, release linked issues
+- **Ready-ticket worker** → claim, implement, PR, merge, release — then pick the next Ready ticket
+- **Backlog gardener** → only when no Ready work is available
+
+Do **not** stop after one ticket or ask to continue between tickets. Ask only for product/architecture decisions or hard external blockers.
+
+Run lean: filtered Project 2 queries, bounded command output, focused diffs, summarized CI results.
 
 ## Starter Prompts