Secure and structure runtime-template administration

[alexeygrigorev]

Status

Groomed and ready for implementation.

• Parent: Converge DataOps onto one canonical frontend #148
• Follow-up to the incomplete runtime-template administration slice of closed Port runtime template and workflow administration to the canonical frontend #153; do not reopen Port runtime template and workflow administration to the canonical frontend #153.
• Depends on: none. This can proceed independently of Complete canonical frontend deep-link and operator parity #156, Make assistant output review safe and lifecycle-complete #158, and Restore canonical frontend behavior coverage and SAM parity gates #159.
• Blocks: safe product acceptance of runtime-template administration under Converge DataOps onto one canonical frontend #148.
• Next owner: Software Engineer.

Problem

The canonical frontend exposes runtime-template create, edit, and delete controls to every authenticated operator. The backend receives no verified actor context on template routes, so it cannot enforce privileged mutations. Editing is a raw JSON textarea, writes have no concurrency token, deletion does not protect referenced templates, and the current tests do not prove authorization or saved-definition instantiation fidelity.

In this issue, the intended maintainer/admin boundary maps to the existing User.role = admin role. Adding a new maintainer role is out of scope.

Scope

Deliver a server-enforced, admin-only runtime-template administration flow in the canonical frontend and API.

Authorization

• Route template mutations through the repository's verified server-side actor path. Do not trust role, user ID, or forwarding headers supplied by the browser.
• POST, PUT, and DELETE are allowed only for an authenticated active admin.
• Unauthenticated requests return JSON 401; authenticated non-admin requests return JSON 403; neither path mutates data or writes a success audit event.
• Operators may continue to list/read templates and instantiate workflows when otherwise authorized.
• Mutation controls are absent from the operator UI, but UI hiding is not the security boundary.
• Preserve the existing API error envelope and do not leak template contents, user details, or internal authorization data.

Structured editor

Replace the raw-JSON-first form with structured controls for the complete supported runtime-template contract:

• template metadata: name, type, emoji, tags, and default assignee;
• trigger settings: type, schedule, lead time, and enabled state;
• phases and source/reference or bundle links;
• ordered task definitions, including ref ID, description, day offset, phase, assignee, instructions/document step, systems, validation, proof requirement, required link/file, completion stage, and artifact/assistant/audit references;
• add, remove, and keyboard-accessible reorder controls with visible focus and validation tied to the relevant field.

JSON may appear only in a collapsed Advanced JSON disclosure. It is a read-only, normalized representation of the structured draft; the primary create/edit path must not require JSON authoring, and supported fields must not be silently discarded.

Save and concurrency states

• Add a monotonic integer template version. New templates start at 1; successful updates increment it.
• Existing records without a version are exposed as version 1 and can be upgraded by the first conditional write without an offline data migration.
• PUT and DELETE require the client's expectedVersion and use a datastore conditional write. Missing or stale versions return JSON 409 conflict; the response may expose the current version and updatedAt, but not a replacement definition.
• The editor visibly distinguishes clean/saved, dirty, saving, validation error, permission/network error, and conflict states.
• Prevent duplicate submissions. A failed or conflicting save preserves the local draft. Conflict recovery offers an explicit reload of the server version and never overwrites either version silently.
• Closing, navigating away from, cancelling, or switching templates with an unsaved draft requires confirmation.

Safe deletion and audit

• Hard deletion is allowed only when the template has zero references. The server, not the browser, checks all persisted reference classes, including bundles/tasks with templateId and any scheduler or recurrence reference to the template.
• A referenced template is not deleted and returns JSON 409 template_in_use with sanitized counts/categories only—no private names, descriptions, or IDs. There is no browser force-delete path.
• The UI uses a destructive confirmation naming the template and explains that referenced templates cannot be deleted.
• Record privacy-safe immutable audit events for successful create/update/delete mutations and rejected delete attempts. Include actor ID, template ID, action, outcome/reason, prior/result version where applicable, timestamp, and changed field names; do not store the full definition, credentials, document contents, or other sensitive values.
• A successful mutation and its success audit record must not diverge: use an atomic write when supported or fail closed with a tested compensating strategy.

Saved-definition fidelity

Prove a real round trip through persistence:

1. An admin creates or edits a template through the structured editor, including multiple reordered tasks and non-default optional fields.
2. The UI reloads the saved definition from the API.
3. A workflow is instantiated from that saved definition.
4. The resulting bundle/tasks preserve the saved task order and supported values, including offsets, phases, descriptions, instructions, proof requirements, milestones/completion stages, assignees, references, required links/files, and bundle/source links.

The test must fail if instantiation uses a stale client draft, fixture, or hard-coded template instead of the saved record.

Acceptance criteria

• Verified server-side actor resolution protects all template mutation routes; admin succeeds, operator receives 403, unauthenticated receives 401, and spoofed client identity/role headers do not grant access.
• The canonical UI exposes mutation controls only to admins and uses the structured, accessible, reorderable editor described above.
• Advanced JSON is secondary/read-only, and a save/reload round trip loses no supported fields.
• Dirty, saving, saved, validation, permission/network error, and conflict states are observable and preserve user work as specified.
• Conditional update/delete behavior returns deterministic 409 responses for stale versions; concurrent requests cannot silently overwrite or delete newer data.
• Referenced templates cannot be deleted; an unreferenced template can be deleted only by an admin with the current version.
• Audit events are privacy-safe and mutation/audit consistency is covered by tests.
• A saved structured definition instantiates with exact task order and field fidelity.
• Architecture review records the authorization boundary, version/conditional-write contract, reference scan policy, audit consistency, and compatibility behavior for versionless rows.
• Design evidence shows admin and operator states plus clean, dirty, saving, conflict, error, and delete-blocked behavior at desktop (1440x900) and mobile (390x844) widths.
• Tests and evidence contain no real credentials, private links, contact details, raw operational documents, or sensitive fixture data.

Required tests

Backend/API tests must cover:

• admin allow and operator/unauthenticated/spoofed-header denial for each of POST, PUT, and DELETE, with denial proven non-mutating;
• create at version 1, conditional update increment, missing/stale-version 409, and two-writer concurrency with exactly one winner;
• versionless-record compatibility;
• referenced-delete 409, stale-delete 409, unreferenced delete success, and sanitized error bodies;
• audit content/redaction and mutation/audit failure behavior;
• full schema save/reload and instantiation fidelity.

Canonical browser tests against the real backend must cover:

• role-based control visibility plus direct API denial for an operator;
• structured task add/remove/reorder, validation, dirty-navigation confirmation, saving/saved/error states, and a conflict that preserves the draft;
• referenced-delete refusal and named confirmation for an eligible delete;
• create/save/reload/instantiate with API assertions for exact task order and values;
• desktop and mobile evidence for the states listed above.

Run the relevant repository checks, including backend build/unit/integration tests and canonical frontend E2E. Source-marker or static-bundle assertions alone do not satisfy behavioral acceptance.

Out of scope

• Creating a new maintainer role or changing the wider user-role model.
• Restoring or extending the legacy SPA.
• Git-backed documentation authoring, sync, or review; operational documents remain a separate private knowledge-system concern.
• Assistant lifecycle work (Make assistant output review safe and lifecycle-complete #158), broader canonical parity/deep links (Complete canonical frontend deep-link and operator parity #156), and SAM/release gate work (Restore canonical frontend behavior coverage and SAM parity gates #159).
• Manual production deployment, workflow dispatch, AWS changes, or modification of source repositories.
• Archival/retirement UX or force deletion; if desired, define it separately.

[alexeygrigorev]

PM GROOMING PASS

#157 is self-contained and ready for implementation on current main 36d446c. The server-enforced admin boundary, structured and reorderable editor, advanced read-only JSON disclosure, dirty/saving/error/conflict/version states, reference-safe deletion and privacy-safe audit contract, exact saved-definition instantiation proof, and negative API/browser/concurrency coverage are now explicit.

The existing admin role is the mutation authority; this issue does not create a new maintainer role. Git-backed documentation remains a separate private knowledge-system concern, and the legacy SPA is out of scope.

No repository edit, data mutation, commit, push, deploy, workflow dispatch, or AWS action was performed.

Dependencies: none for source work; implementation can proceed independently of #156, #158, and #159. #157 blocks safe runtime-template acceptance under #148.
Next owner: Software Engineer, followed by Architect and Designer review, Tester, and PM acceptance.

[alexeygrigorev]

DESIGN PASS

Reviewed the authoritative issue #157 candidate:

• Base/HEAD: 36d446cb98b5f6b9f758b6fbe8e6723943ed965d
• Candidate: 21 status/path/blob records
• Fingerprint: 5428726d456088a580d1a5b9628cee1b895234968c8b3481c238357dd17a4bc0
• Route: #/templates
• Viewports: 1440×900 desktop and 390×844 mobile

The prior blocking mobile action-bar overlap is resolved. The action card now uses the shared 48px mobile-topbar height plus an 8px offset. In the exact-candidate focused browser run, geometry assertions confirmed that the sticky card starts 7–12px below the topbar, remains inside the viewport, and center-point hit testing resolves to Save template; the test then clicked those measured coordinates and observed Saving… followed by Saved. The screenshot .tmp/screenshots/issue-157/mobile-admin-sticky-scrolled-390x844.png shows both actions fully visible below the shared header while scrolled.

I inspected the complete 21-image evidence set under .tmp/screenshots/issue-157/:

• Desktop admin: clean/new, validation, dirty, saving, saved, conflict, network error, permission error, and blocked delete.
• Mobile admin: blocked delete, dirty, sticky/scrolled, saving, saved, conflict, clean/reloaded, validation, permission error, and network error.
• Operator: desktop and mobile read-only detail, including a clear admin-permission boundary and useful Start workflow action.

All earlier Designer findings remain closed: new-vs-persisted clean copy is accurate; task reordering preserves useful focus; mobile uses list/detail navigation instead of stacking both; operator detail is structured and actionable; permission failures preserve the draft; destructive confirmation defaults safely to Cancel and restores focus; cancelled dirty navigation preserves route/section/draft state; and reference-count copy pluralizes correctly.

No blocking 404, broken route, unreadable control, action/header overlap, clipping, missing core state, or misleading action was found in the reviewed flow. The structured editor, read-only Advanced JSON review, admin/operator permission split, blocked-delete reference counts, and persisted task-order instantiation evidence are coherent with the existing DataOps UI.

Verification evidence:

• Exact fingerprint, run from backend/: npx playwright test e2e/runtime-template-admin.spec.js --reporter=line → 2 passed
• Existing full browser evidence: .tmp/issue-157-e2e-rereview.log → 184 passed
• Existing backend evidence: .tmp/issue-157-backend-test-rereview.log → 1228 passed, 1 skipped, 0 failed

Designer review passes. This does not replace Tester verification or PM acceptance.

[alexeygrigorev]

ARCHITECTURE PASS

Architecture approval is bound to the final frozen candidate:

• Base: 36d446cb98b5f6b9f758b6fbe8e6723943ed965d
• Candidate: 21 status/path/blob records
• Fingerprint: 5428726d456088a580d1a5b9628cee1b895234968c8b3481c238357dd17a4bc0

The previously reported 7bbe4a1740ab57cb09fb2c85c0d92f667b617f6981734ec4fbbca42a7c933950 handoff is stale and superseded.

No blocking architecture findings remain:

• Verified server-side actor resolution remains the mutation security boundary. Active admins may mutate; operators, unauthenticated callers, disabled users, and spoofed client identity/role headers are denied.
• Template versions start at 1, versionless compatibility remains migration-free, and conditional PUT/DELETE operations preserve deterministic conflict behavior with one concurrent winner.
• Reference-safe deletion uses paginated, strongly consistent scans across bundles, tasks, recurrences, schedules, calendar items, and notifications. An internal retained tombstone prevents dangling references across the scan/write race, while archived templates are excluded from normal reads and fresh reference creation.
• Successful mutations and privacy-safe immutable audit events remain transactionally consistent in production with the narrowly scoped Templates plus AuditEvents dynamodb:TransactWriteItems permission.
• Portable export and validation preserve runtime-template audits, versions, emoji, archive metadata, task offsets, milestones, and source-document identifiers.
• Structured save/reload/instantiation preserves persisted task order and supported bundle/task values, including sourceDocIds.
• The canonical UI remains server-role-derived, structured and accessible, uses read-only Advanced JSON, sends expected versions, preserves drafts across conflicts/errors, and exposes operator inspection/instantiation without mutation controls.
• The final responsive delta changes only CSS and runtime-template E2E evidence. Mobile actions stick below the shared 48px header with an 8px offset; the browser test verifies geometry, viewport visibility, hit-testing, and an actual save click. Application, backend, infrastructure, export, and instantiation behavior are unchanged from the prior approval.

Reported verification is green: focused runtime-template E2E 2, full E2E 184, backend unit 1228 with one skip, typecheck, build, convergence 9, infrastructure checks, portable export checks, and git diff --check. Independent architecture checks reproduced the final base, 21-record fingerprint, syntax validity, and clean diff check.

No file edit, commit, push, deployment, workflow dispatch, AWS action, or operational-knowledge boundary change was performed by Architecture review.

[alexeygrigorev]

TEST PASS

Tested the final frozen authoritative candidate only.

Candidate identity

• Base/HEAD: 36d446cb98b5f6b9f758b6fbe8e6723943ed965d
• Candidate: exactly 21 status<TAB>path<TAB>git-hash-object records
• Fingerprint: 5428726d456088a580d1a5b9628cee1b895234968c8b3481c238357dd17a4bc0
• Fingerprint recipe: while IFS= read -r line; do status=${line:0:2}; path=${line:3}; blob=$(git hash-object -- "$path"); printf '%s\t%s\t%s\n' "$status" "$path" "$blob"; done < <(git status --porcelain=v1) | sha256sum
• Candidate identity was rechecked after all build/test activity and remained identical.

Commands and results

• git diff --check 36d446cb98b5f6b9f758b6fbe8e6723943ed965d → exit 0.
• npm --prefix backend test → exit 0: 1229 tests; 1228 passed, 1 skipped, 0 failed across 178 suites. The issue-specific runtime-template suite contributed 6 passing tests covering authorization/non-mutation, version/concurrency compatibility, deletion/tombstones/reference scans, persistence/instantiation fidelity, and audit consistency.
• npm --prefix backend run typecheck → exit 0.
• npm --prefix backend run build → exit 0; canonical frontend artifact verified.
• uv run --with pytest python -m pytest tests/infra → exit 0: 41 passed.
• make sam-validate → exit 0; infra/template.full.yaml is a valid SAM template.
• sam build --config-env full-sandbox → exit 0; Build Succeeded for the full sandbox template. The npm audit notices emitted during dependency packaging were informational and did not fail the build.
• npm --prefix backend run test:e2e → exit 0: 184 passed with one worker against the real local backend. Ports/resources were isolated to this worktree's test run (3001 admin backend, 3027 production-auth operator backend), and global teardown released both.
• find .tmp/screenshots/issue-157 ... plus native-dimension inspection → exit 0: 21 PNGs, all exactly 1440×900 or 390×844 as named below.

Logs are retained under .tmp/issue-157-tester-{backend,typecheck,build,infra-pytest,sam-validate,sam-build,e2e}.log in the issue worktree.

Acceptance criteria, in issue order

1. PASS — verified actor boundary. The router deletes client-supplied identity outside the explicit test bypass and replaces it only with a verified portal-cookie or bearer-session identity; template routes resolve the persisted user and role. POST/PUT/DELETE allow an active admin and return JSON 403 for an operator, JSON 401 for unauthenticated/disabled callers, and deny spoofed x-user-id/role headers. Denials preserve the template/version and create no success audit.
2. PASS — admin-only structured UI. Real-browser coverage proves mutation controls exist for admins and are absent for operators while read/instantiate remains available. The editor provides metadata, trigger, phase, source-doc, reference, bundle-link, complete ordered-task, add/remove, and keyboard reorder controls; reorder retains focus and visible focus styling is present.
3. PASS — secondary read-only JSON and round trip. Advanced JSON is collapsed/secondary and its textarea is readonly. Browser save/reload preserved reordered task data; backend persistence tests round-trip the full supported schema without field loss.
4. PASS — editor states and work preservation. Clean/new, dirty, saving, saved, validation, permission, network, and conflict states were asserted and inspected. Conflict/network/permission failures preserved the local draft; explicit server reload requires confirmation. Dirty tab/hash navigation cancellation preserved route, section, focus, and draft. The save control disables during saving, preventing duplicate submission.
5. PASS — deterministic optimistic concurrency. Creates start at version 1; versionless rows read as 1 and conditionally upgrade to 2. Missing/stale expected versions return JSON 409 version_conflict; a two-writer race produced exactly one 200 winner and one 409 loser. Conditional update/delete includes the versionless compatibility condition and cannot overwrite/delete a newer version silently.
6. PASS — reference-safe deletion and tombstone behavior. Server-owned, strongly consistent, paginated scans cover bundles, tasks, recurrences, schedules, calendar items, and notifications. A >1 MB scan test found all 225 references. Referenced delete returns sanitized category/count-only JSON 409 template_in_use; current-version admin deletion of an eligible template returns 204 and retains an internal versioned tombstone excluded from reads/new references. Stale and non-admin deletion are rejected.
7. PASS — privacy-safe, consistent audits and exact IAM. Create/update/delete success events and rejected delete events contain actor/template/action/outcome/reason, versions, timestamp, and sorted changed-field names, not definitions or sensitive values. Production uses a Templates + AuditEvents transaction; the tested local fallback compensates a failed audit write and restores the prior template/version. SAM grants dynamodb:TransactWriteItems in exactly one narrowly scoped statement whose only resources are the Templates and AuditEvents tables.
8. PASS — saved-definition fidelity. The real browser creates, reorders, saves, reloads, then instantiates from the saved API record; assertions prove persisted order, offsets, descriptions, instruction document, proof values, and source-document context rather than a client fixture. The schema-complete backend round trip additionally proves phases, assignees, URL/document instructions, systems, validation, proof, required link/file, milestone/completion stage, artifact/assistant/audit/intake references, bundle references/links, and sourceDocIds; instantiated bundle and tasks inherit sourceDocIds exactly.
9. PASS — architecture gate. Architecture PASS is bound to this exact 21-record fingerprint: Secure and structure runtime-template administration #157 (comment) . It explicitly records authorization, conditional/versionless compatibility, paginated reference policy, retained tombstone race behavior, transactional audit consistency, export, and source-document propagation.
10. PASS — design/evidence gate. Designer PASS is bound to this exact fingerprint: Secure and structure runtime-template administration #157 (comment) . I independently inspected every image below at its native viewport. No image shows a 404/error page, broken route, unreadable state, overlap, clipping, or missing core state. The mobile sticky action geometry test asserted the action top 7–12 px below the shared 48px topbar, its bottom inside the viewport, and center-point hit testing on Save template; it then performed the coordinate click and observed Saving… followed by Saved.
11. PASS — safe evidence. Candidate-added test/evidence values are synthetic (example.test, synthetic IDs/content). No changed test or screenshot adds a real credential, private link, contact detail, raw operational document, or secret; no secret value was emitted by the verification commands.

Screenshot inspection

All files are under .tmp/screenshots/issue-157/.

• Desktop 1440×900 (10): desktop-admin-clean-1440x900.png, desktop-admin-dirty-1440x900.png, desktop-admin-saving-1440x900.png, desktop-admin-saved-1440x900.png, desktop-admin-validation-1440x900.png, desktop-admin-conflict-1440x900.png, desktop-admin-error-1440x900.png, desktop-admin-permission-1440x900.png, desktop-admin-delete-blocked-1440x900.png, desktop-operator-readonly-1440x900.png.
• Mobile 390×844 (11): mobile-admin-clean-390x844.png, mobile-admin-dirty-390x844.png, mobile-admin-sticky-scrolled-390x844.png, mobile-admin-saving-390x844.png, mobile-admin-saved-390x844.png, mobile-admin-validation-390x844.png, mobile-admin-conflict-390x844.png, mobile-admin-error-390x844.png, mobile-admin-permission-390x844.png, mobile-admin-delete-blocked-390x844.png, mobile-operator-readonly-390x844.png.

No source file was edited, committed, pushed, deployed, or dispatched, and no AWS API was called.

[alexeygrigorev]

PM ACCEPTED

Final user-perspective acceptance is bound to the frozen candidate below:

• Base/HEAD: 36d446cb98b5f6b9f758b6fbe8e6723943ed965d
• Candidate: exactly 21 status<TAB>path<TAB>git-hash-object records
• Fingerprint: 5428726d456088a580d1a5b9628cee1b895234968c8b3481c238357dd17a4bc0

I reviewed the complete groomed issue, the final implementation paths, the Architecture PASS, Designer PASS, Tester PASS, and every one of the 21 desktop/mobile screenshots at native size. The product behavior matches all 11 acceptance criteria.

From the admin perspective, the canonical Templates surface provides the complete structured create/edit flow, accessible add/remove/reorder controls with focus retention, secondary read-only Advanced JSON, clear new/clean/dirty/saving/saved/validation/permission/network/conflict states, explicit conflict reload that preserves the local draft until confirmed, and dirty-navigation protection. The destructive confirmation names the template, defaults safely to Cancel, restores focus, explains that referenced templates cannot be deleted, and the blocked state reports only correctly pluralized sanitized reference categories/counts. Mobile list/detail navigation and sticky Save/Cancel controls remain visible and operable below the shared header while scrolled.

From the operator perspective, mutation controls are absent, the permission boundary is stated plainly, template details and ordered tasks remain readable, and Start workflow remains available. This is correctly backed by verified server-side actor resolution: unauthenticated, inactive, operator, and spoofed-header mutation attempts are denied without successful mutation/audit effects.

Version 1 compatibility, conditional update/delete conflicts, one-winner concurrency, retained deletion tombstones, paginated reference scans, privacy-safe audit fields, mutation/audit consistency, narrow transactional IAM, portable export, and synthetic-only evidence are complete. Saved-definition fidelity is proven through the real persistence path: structured create/reorder/save, API reload, then instantiation by persisted template ID preserves task order and supported template, bundle, source-document, assignment, instruction, validation, proof, milestone/stage, link/file, and reference fields.

Gate evidence:

• Architecture PASS: Secure and structure runtime-template administration #157 (comment)
• Designer PASS: Secure and structure runtime-template administration #157 (comment)
• Tester PASS: Secure and structure runtime-template administration #157 (comment) — backend 1229 total / 1228 passed / 1 skipped, infrastructure 41 passed, Playwright 184 passed, and typecheck/build/SAM validation/SAM build passed.

No PM follow-up or human-only acceptance gate remains.

Next owner: Software Engineer — commit this exact frozen candidate with Closes #157. If the candidate changes before commit, rerun the affected review gates.