PDA Platform Worked Example

[antnewman]

Summary

Proposing a LOGIC.md worked example drawn from a real UK-government AI-assurance workflow (the PDA Platform — 122 MCP tools across 18 modules, AssuranceStore, confidence-extraction, outlier-mining). Would serve as:

1. A canonical regulated-domain example — something the README can point at when the "where is this actually used?" question comes up.
2. A real-world stress-test of the spec — likely to surface scope gaps where current §2-§10 doesn't quite cover what an assurance workflow needs.
3. A reciprocal adoption signal — PDA Platform would adopt LOGIC.md for the workflow's orchestration layer if the fit is good.

Filing as an issue first (not a PR) to scope shape before I write 300 lines of YAML that may not match what you want.

Proposed example

A LOGIC.md spec for the PDA Platform risk-register assurance workflow — ~8 steps including:

• ingest_artefact — parse an uploaded project-delivery artefact (PDF, spreadsheet, or MCP feed)
• extract_risks — use an LLM to extract risk items with confidence scores
• outlier_scan — compare extracted risks against historical patterns (AssuranceStore lookup)
• triage — per-risk decision: auto-approve / flag for human review / escalate
• human_review_gate (quality gate) — if triage.flags.length > threshold, wait for human sign-off
• persist — write to AssuranceStore with provenance metadata
• emit_report — structured report for the project manager

With the features LOGIC.md is strongest at:

• Contracts between every step (typed artefacts flowing through a DAG)
• Quality gates — confidence thresholds, human-review escalation, invariants
• Fallback policies — what happens when confidence is too low or the LLM disagrees with the outlier scan
• Per-step tool permissions — ingest can read artefacts, persist can write to store, extract_risks can do neither
• Self-verification — rubric-based check that the output contains required fields before persistence

Why this is useful to LOGIC.md

1. Fills the "public regulated-domain case study" gap the README currently points at SingleSourceStudios/modular9 for — which isn't yet a public reference.
2. Tests features that conformance fixtures cover in isolation but not in combination (per-step tool permissions + quality gates + fallback + multi-agent handoff).
3. Gives implementers building a LOGIC.md runtime a non-trivial real-world spec to test against.
4. Likely surfaces small spec gaps, which is valuable signal.

Why this is useful to PDA

The PDA Platform workflows are currently orchestrated in imperative Python. Moving the orchestration layer to LOGIC.md specs would:

1. Make the assurance reasoning itself auditable (Cabinet Office / GDS compliance has an interest in this).
2. Survive framework changes — we've been considering LangGraph / DSPy / plain MCP, can't commit.
3. Allow non-Python runtimes (the procurement path sometimes requires .NET).

What I'd like from you

Not a PR yet. A short response to any of these:

1. Is this the right shape of example for you? Public-sector regulated-domain vs. a simpler commercial case. Either works, but I want to confirm before investing.
2. Would you want it under examples/ (like the existing examples/research-synthesizer.logic.md) or as a first-class "case studies" section?
3. Any features you specifically want it to exercise that the current fixtures/templates don't?
4. Scope preference — full 8-step workflow, or a reduced 3-4 step cut that still lands the point?

What I'm offering

To draft the spec + a short markdown narrative (examples/pda-risk-register-assurance.md or similar) once we've agreed the shape. ~2-3 hours of work. I'd produce it on a branch you can iterate on before merge.

Broader context

This is part of a wider set of adjacent declarative-spec projects in the same space (the UDS dashboard spec at Tortoise-AI/uds-spec, the PDA Platform itself) where LOGIC.md's shape has natural adjacency. Nothing to action here — mentioning in case it affects how you think about the worked example's framing.

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

The repo has one existing worked example at file:examples/research-synthesizer.logic.md — a 5-step ReAct workflow covering gather_sources → evaluate_credibility → synthesize → expand_search / draft_report. It exercises contracts, quality gates, self-verification (checklist), fallback escalation, per-step allowed_tools, confidence thresholds, and branching. The spec (file:docs/SPEC.md) fully supports all features the issue requests. The examples/ directory is the right home for a new worked example.

Approach

Add a single new file examples/pda-risk-register-assurance.logic.md following the exact structure and conventions of file:examples/research-synthesizer.logic.md. The 8-step workflow maps cleanly onto existing spec features. A companion narrative markdown file examples/pda-risk-register-assurance.md explains the regulated-domain context. Finally, update file:README.md to reference both files as a second canonical example.

---

Implementation Steps

1. Create examples/pda-risk-register-assurance.logic.md

Model the file structure exactly after file:examples/research-synthesizer.logic.md — YAML frontmatter followed by a markdown body. The YAML must include:

Top-level fields:

• spec_version: "1.0", name: "pda-risk-register-assurance", description
• reasoning.strategy: plan-execute (appropriate for a known, decomposable assurance workflow), max_iterations, temperature

Steps DAG — 8 named steps with needs wiring:

ingest_artefact
    └─► extract_risks
            └─► outlier_scan
                    └─► triage
                            └─► human_review_gate  (quality gate step)
                                    └─► persist
                                            └─► emit_report

Per-step details to specify:

Step	allowed_tools	denied_tools	Key output_schema fields	verification / branches
ingest_artefact	file_reader, mcp_feed_reader	file_write, store_write	artefact_type, raw_content, parse_confidence	retry if parse_confidence < 0.6
extract_risks	llm_extract	file_write, store_write	risks[] (each: id, description, confidence, category)	retry if risks.length == 0
outlier_scan	assurance_store_read	store_write	risks[] augmented with outlier_score, historical_match	branch: if outlier_score.avg > 0.8 → escalate_all
triage	none	all store/write tools	auto_approved[], flagged[], escalated[]	branch: if flagged.length > threshold → human_review_gate; else → persist
human_review_gate	notification_send	store_write	reviewer_decision, reviewer_notes, reviewed_at	on_fail: escalate
persist	store_write	none	record_ids[], provenance_hash, persisted_at	verify all record_ids non-empty
emit_report	report_renderer	store_write	report_url, summary, risk_count_by_category	checklist self-verification

contracts section:

• inputs: artefact_ref (string, required), project_id (string, required), triage_threshold (integer, default 3)
• outputs: assurance_record_ids (array), report_url (string), overall_confidence (number 0–1), provenance_hash (string)
• capabilities: name, version, supported_domains: [government, regulated, procurement]

quality_gates section:

• pre_output: check overall_confidence >= 0.7 (severity: error, on_fail: escalate); check assurance_record_ids.length > 0 (severity: error)
• self_verification.strategy: rubric with criteria: completeness (weight 0.4), provenance_integrity (weight 0.35), human_review_compliance (weight 0.25); minimum_score: 0.75

fallback section:

• Level 1: confidence < 0.6 → retry_with_different_strategy (switch to tot)
• Level 2: attempts >= 2 && confidence < 0.6 → request_human_review with include_reasoning_trace: true
• Level 3: attempts >= 4 → abort
• degradation: tools_unavailable → reasoning_only; timeout_exceeded → partial_output including [summary, risk_count_by_category]

metadata: tags: [government, assurance, regulated, pda-platform, risk-register]

Markdown body (after the closing ---): explain the plan-execute strategy rationale, the Cabinet Office / GDS auditability motivation, why per-step tool permissions matter for a write-segregated assurance store, and the known failure modes (low-confidence LLM extraction on dense PDFs, outlier scan cold-start on new project types).

---

2. Create examples/pda-risk-register-assurance.md

A short (~300-word) narrative companion file covering:

• What the PDA Platform is and why it's a regulated-domain reference
• How the 8-step DAG maps to the real workflow
• Which LOGIC.md features it exercises that research-synthesizer does not (rubric self-verification, write-segregated tool permissions, human-review gate as a first-class step, provenance metadata in contracts)
• How to run it: logic-md validate examples/pda-risk-register-assurance.logic.md and logic-md lint examples/pda-risk-register-assurance.logic.md

---

3. Update file:README.md

In the "Developed alongside and validated through" sentence (line 14) or in a new "Examples" subsection before the "Packages" table, add a reference to both new files:

• examples/research-synthesizer.logic.md — multi-source research synthesis
• examples/pda-risk-register-assurance.logic.md — UK government AI-assurance workflow (regulated domain, human-review gate, write-segregated tool permissions, rubric self-verification)

This directly addresses the issue's stated goal of filling the "public regulated-domain case study" gap.

---

Diagram — Step DAG with feature annotations

graph TD
    A[ingest_artefact\nallowed: file_reader, mcp_feed_reader\ndenied: store_write] --> B[extract_risks\nallowed: llm_extract\ndenied: store_write]
    B --> C[outlier_scan\nallowed: assurance_store_read\ndenied: store_write]
    C --> D[triage\ndenied: all write tools]
    D -->|flagged.length > threshold| E[human_review_gate\nQuality Gate Step\nallowed: notification_send]
    D -->|flagged.length <= threshold| F[persist\nallowed: store_write]
    E --> F
    F --> G[emit_report\nallowed: report_renderer]

    style E fill:#f5f5f5,stroke:#333,stroke-dasharray: 5 5

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The repo has one existing worked example at `file:examples/research-synthesizer.logic.md` — a 5-step ReAct workflow covering `gather_sources → evaluate_credibility → synthesize → expand_search / draft_report`. It exercises contracts, quality gates, self-verification (checklist), fallback escalation, per-step `allowed_tools`, confidence thresholds, and branching. The spec (`file:docs/SPEC.md`) fully supports all features the issue requests. The `examples/` directory is the right home for a new worked example.

## Approach

Add a single new file `examples/pda-risk-register-assurance.logic.md` following the exact structure and conventions of `file:examples/research-synthesizer.logic.md`. The 8-step workflow maps cleanly onto existing spec features. A companion narrative markdown file `examples/pda-risk-register-assurance.md` explains the regulated-domain context. Finally, update `file:README.md` to reference both files as a second canonical example.

---

## Implementation Steps

### 1. Create `examples/pda-risk-register-assurance.logic.md`

Model the file structure exactly after `file:examples/research-synthesizer.logic.md` — YAML frontmatter followed by a markdown body. The YAML must include:

**Top-level fields:**
- `spec_version: "1.0"`, `name: "pda-risk-register-assurance"`, `description`
- `reasoning.strategy: plan-execute` (appropriate for a known, decomposable assurance workflow), `max_iterations`, `temperature`

**Steps DAG** — 8 named steps with `needs` wiring:

```
ingest_artefact
    └─► extract_risks
            └─► outlier_scan
                    └─► triage
                            └─► human_review_gate  (quality gate step)
                                    └─► persist
                                            └─► emit_report
```

Per-step details to specify:

| Step | `allowed_tools` | `denied_tools` | Key `output_schema` fields | `verification` / `branches` |
|---|---|---|---|---|
| `ingest_artefact` | `file_reader`, `mcp_feed_reader` | `file_write`, `store_write` | `artefact_type`, `raw_content`, `parse_confidence` | retry if `parse_confidence < 0.6` |
| `extract_risks` | `llm_extract` | `file_write`, `store_write` | `risks[]` (each: `id`, `description`, `confidence`, `category`) | retry if `risks.length == 0` |
| `outlier_scan` | `assurance_store_read` | `store_write` | `risks[]` augmented with `outlier_score`, `historical_match` | branch: if `outlier_score.avg > 0.8` → `escalate_all` |
| `triage` | none | all store/write tools | `auto_approved[]`, `flagged[]`, `escalated[]` | branch: if `flagged.length > threshold` → `human_review_gate`; else → `persist` |
| `human_review_gate` | `notification_send` | `store_write` | `reviewer_decision`, `reviewer_notes`, `reviewed_at` | `on_fail: escalate` |
| `persist` | `store_write` | none | `record_ids[]`, `provenance_hash`, `persisted_at` | verify all `record_ids` non-empty |
| `emit_report` | `report_renderer` | `store_write` | `report_url`, `summary`, `risk_count_by_category` | checklist self-verification |

**`contracts` section:**
- `inputs`: `artefact_ref` (string, required), `project_id` (string, required), `triage_threshold` (integer, default 3)
- `outputs`: `assurance_record_ids` (array), `report_url` (string), `overall_confidence` (number 0–1), `provenance_hash` (string)
- `capabilities`: name, version, `supported_domains: [government, regulated, procurement]`

**`quality_gates` section:**
- `pre_output`: check `overall_confidence >= 0.7` (severity: error, on_fail: escalate); check `assurance_record_ids.length > 0` (severity: error)
- `self_verification.strategy: rubric` with criteria: `completeness` (weight 0.4), `provenance_integrity` (weight 0.35), `human_review_compliance` (weight 0.25); `minimum_score: 0.75`

**`fallback` section:**
- Level 1: `confidence < 0.6` → `retry_with_different_strategy` (switch to `tot`)
- Level 2: `attempts >= 2 && confidence < 0.6` → `request_human_review` with `include_reasoning_trace: true`
- Level 3: `attempts >= 4` → `abort`
- `degradation`: `tools_unavailable` → `reasoning_only`; `timeout_exceeded` → `partial_output` including `[summary, risk_count_by_category]`

**`metadata`:** `tags: [government, assurance, regulated, pda-platform, risk-register]`

**Markdown body** (after the closing `---`): explain the `plan-execute` strategy rationale, the Cabinet Office / GDS auditability motivation, why per-step tool permissions matter for a write-segregated assurance store, and the known failure modes (low-confidence LLM extraction on dense PDFs, outlier scan cold-start on new project types).

---

### 2. Create `examples/pda-risk-register-assurance.md`

A short (~300-word) narrative companion file covering:
- What the PDA Platform is and why it's a regulated-domain reference
- How the 8-step DAG maps to the real workflow
- Which LOGIC.md features it exercises that `research-synthesizer` does not (rubric self-verification, write-segregated tool permissions, human-review gate as a first-class step, provenance metadata in contracts)
- How to run it: `logic-md validate examples/pda-risk-register-assurance.logic.md` and `logic-md lint examples/pda-risk-register-assurance.logic.md`

---

### 3. Update `file:README.md`

In the **"Developed alongside and validated through"** sentence (line 14) or in a new **"Examples"** subsection before the "Packages" table, add a reference to both new files:

- `examples/research-synthesizer.logic.md` — multi-source research synthesis
- `examples/pda-risk-register-assurance.logic.md` — UK government AI-assurance workflow (regulated domain, human-review gate, write-segregated tool permissions, rubric self-verification)

This directly addresses the issue's stated goal of filling the "public regulated-domain case study" gap.

---

### Diagram — Step DAG with feature annotations

```mermaid
graph TD
    A[ingest_artefact\nallowed: file_reader, mcp_feed_reader\ndenied: store_write] --> B[extract_risks\nallowed: llm_extract\ndenied: store_write]
    B --> C[outlier_scan\nallowed: assurance_store_read\ndenied: store_write]
    C --> D[triage\ndenied: all write tools]
    D -->|flagged.length > threshold| E[human_review_gate\nQuality Gate Step\nallowed: notification_send]
    D -->|flagged.length <= threshold| F[persist\nallowed: store_write]
    E --> F
    F --> G[emit_report\nallowed: report_renderer]

    style E fill:#f5f5f5,stroke:#333,stroke-dasharray: 5 5
```

---

Execution Information

Branch: main
Commit: 70629c2

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[SingleSourceStudios]

Thanks for filing this as an issue first — exactly the right call. Quick answers so you can get a branch started:

1. Shape. Yes — regulated-domain (public-sector) is the right shape. It directly fills the gap the README currently handwaves toward modular9 (not public), and the compliance angle gives the example teeth that a synthetic commercial case wouldn't.

2. Location. examples/ is correct — sits next to research-synthesizer.logic.md. No new "case studies" section yet; we'll promote the directory structurally if a second one lands.

3. Features to exercise. Beyond what you already listed, please specifically drive:

• Rubric-based self-verification on at least one step (research-synthesizer.logic.md uses a checklist; a rubric/scored variant isn't covered in fixtures yet)
• Write-segregated per-step allowed_tools — the persist / ingest / extract_risks asymmetry is the cleanest demonstration we'd have of this
• human_review_gate as a first-class step, not a flag on an LLM step — treat it as the canonical pattern
• Provenance metadata in contracts — show what a production audit trail field looks like flowing through the DAG

4. Scope. Full 8 steps. The value is the feature combinations stressing each other; a 3–4 step cut loses that signal and we'd end up asking for the other 4 anyway.

Workflow. Branch-first on your fork → PR against main. I'll do a first-pass review within 48h of the PR opening. If the draft surfaces real spec gaps, open them as separate issues rather than expanding #18 — keeps scope clean.

The UDS-spec / Tortoise-AI adjacency is interesting and I appreciate the heads-up — off-topic for this issue, but worth a separate thread once the example is in.

Leaving #18 open until the PR lands.

[SingleSourceStudios]

Thanks for the thorough scoping @antnewman — the 8-step workflow (ingest_artefact → extract_risks → outlier_scan → triage → human_review_gate → persist → emit_report) is exactly the right shape for a canonical regulated-domain example.

Labelled help wanted — if you'd like to drive the implementation since you've already thought through the design, happy to review PRs as they land. No pressure, just flagging the door is open on our side. Otherwise this sits in the backlog and we'll pick it up after the current toolchain/docs cleanup (#24, #25).