project-delivery-operator

name	project-delivery-operator
description	Use when work is being delivered through the OpenProject ART and Codex must treat the ART as the primary work-state source, classify uncovered work correctly, and keep PI, stretch, and completion-evidence discipline intact.

Project Delivery Operator

Use this skill when a serious initiative is already running inside Workspace Delivery ART.

Read First

• platform-engineering/products/openproject/AGENTS.md
• platform-engineering/products/openproject/README.md
• platform-engineering/products/openproject/delivery-art-contract.md
• platform-engineering/products/openproject/runbooks/start-delivery-initiative.md
• platform-engineering/products/openproject/runbooks/check-delivery-art-workflow-health.md
• operator-orchestration-service/docs/operations/delivery-workflow-operator-surface.md
• platform-engineering/products/openproject/runbooks/check-delivery-art-quality.md
• workspace-governance/docs/delivery-art-operator-path.md
• workspace-governance/docs/work-home-routing-contract.md
• workspace-governance/docs/delegated-execution.md
• workspace-governance/docs/self-improvement-escalation.md

Workflow

1. Start from the ART, not from chat memory.
   • if the active Epic is already known, start with its fast active-front read and a scoped ART-quality check for that Epic
   • for known initiatives, prefer optimized packet reads: npm run art -- initiative active-session <delivery-id>, npm run art -- initiative evidence-packet <delivery-id>, and npm run art -- item evidence-packet <work-item-id>
   • for oversized ART output, CI logs, terminal output, or sensitive operational context, use context-admission-operator and CGG packet refs instead of pasting raw output into the model context
   • if the target work item is already known, use the broker work-item continuation read before scanning the full execution tree
   • use the deep execution read only when the full evidence-grade tree is actually needed
   • use the portfolio initiative summary only when the active Epic is not yet known or when PI/portfolio replanning is happening
   • identify the committed front, stretch work, PI objective state, and ART risk state before reading repo code
   • inside local dev-integration, default ART reads and writes to the broker CLI in operator-orchestration-service:
     • npm run art -- bootstrap
     • npm run art -- workflow-health
     • npm run art -- initiative planning <delivery-id>
     • npm run art -- item continuation <work-item-id>
   • use GET /v1/delivery-work-items/{work_item_id}/continuation-context as the default ART resume read for one known item
   • when the active item is not yet known, use GET /v1/delivery-initiatives/{delivery_id}/planning first to identify the active front, then fetch continuation context for the chosen item
   • when planning surfaces a ready PI Objective, Feature, or another umbrella item such as a Feature or User story classified as Enabler, do not present it as the next executable work from planning alone; fetch that item's continuation-context first
   • if that continuation packet shows open_child_count=0 and the related completed scope already satisfies the item, treat it as a stale-open closeout candidate rather than the next active front
   • treat raw k3s kubectl exec ... node -e ... broker calls as fallback-only debugging paths when the CLI or broker runtime itself is the thing under test; they are no longer the normal ART operator entrypoint
   • source x-oos-caller-id from the first allowed id in CALLER_ALLOWED_IDS, and source x-oos-caller-secret from CALLER_AUTH_SHARED_SECRET
   • before create or update sets assignee_login or responsible_login, read the live assignable-principal list first from the active devint broker pod: k3s kubectl -n <active-devint-namespace> exec deploy/operator-orchestration-service -- node scripts/show_delivery_art_assignables.mjs
   • choose the exact login from that list; do not infer assignee or responsible from repo names, board labels, or Rails-admin pages
   • when the active implementation repo is operator-orchestration-service and the route already exists, use the documented broker contract first: docs/api/openapi.json or npm run api:contract -- <METHOD> <PATH>
   • before POST /v1/delivery-work-items/{work_item_id}/complete, run the local completion-evidence preflight in operator-orchestration-service: npm run validate:completion-evidence -- <payload.json>
   • do not let the live broker completion write be the first place malformed completion evidence fails
   • completion-evidence preflight is necessary but not sufficient for done work; the broker now also fail-closes on weak done-state narrative structure
   • before complete, and before update when the work item will remain done, confirm the description still keeps the required narrative headings for that type and a flat Execution Context that matches the stored owner repo, parent item, delivery team, and iteration values when those fields apply
   • use execution-summary done_narrative_contract_* fields as the fast read model for done-state narrative drift instead of rediscovering it from raw OpenProject markdown
   • when the exact next committed step cannot proceed, stop adjacent ART mutation first and record the blocker through the bounded blocker path:
     • npm run art -- item blocker <work-item-id> <payload.json>
     • use the generic update path neither to enter nor to clear blocked
   • if the blocker is caused by a live system or workflow control bug, open or update a real Defect in ART instead of leaving the issue only in chat or a self-improvement candidate
   • if the blocker creates exposure broader than one blocked work item, open or update a Risk with ROAM fields
   • when a new defect is discovered during active ART work, contain immediate drift first if needed, then classify it before fixing: immediate_blocker, deferred_defect, absorbed_same_slice_fix, or risk
   • classify as immediate_blocker only when safe continuation is impossible: active quality remains unhealthy, the next mutation would corrupt state, evidence cannot be trusted, the runtime path is down, or an open security/trust exposure exists
   • if containment restores safe continuation, record the defect or follow-up and continue the active committed front instead of context-switching into an unplanned fix
   • absorb a discovered defect into the current Landing Unit only when cause, owner, validation, review, and rollback boundary match the active slice or the operator explicitly approves the absorption
   • if the blocked next step requires operator-side credentials, package installation, sudo, a GUI action, approval, or account permission outside Codex's safe tool boundary, stop and prompt the operator immediately; do not silently substitute CI-only proof, guesswork, or a workaround
   • when live broker truth matters for an existing documented route in operator-orchestration-service, use npm run api:probe -- <METHOD> <PATH> before falling back to handler tracing
   • before changing an OpenProject mutation surface in operator-orchestration-service, prove live form writability or read-only posture and run npm run validate:openproject-mutation-contracts in that repo before merge
   • treat src/app.js and service code as runtime-confirmation or drift sources after the contract read, not as the default first read for an existing broker route
   • do not default to Python wrappers, Rails paths, direct OpenProject admin paths, or ad hoc background localhost bridges when the broker CLI or a documented broker route can do the job
   • use local parsing only after the broker response is captured; parsing is not the access path
   • if the broker runtime is unavailable, restore the lane through the platform OpenProject or broker runtime runbooks first and return to the broker path before ART mutation resumes
   • if roadmap or PM² projection drift is suspected, use:
     1. npm run art -- workflow-health
     2. make openproject-check-delivery-art-quality ...
     3. make openproject-sync-delivery-art-views ... only when the compatible view projection itself drifted
   • after any ART mutation that returns roadmap_version_projection.status=external_reconciler_required, treat projection reconciliation as a broker-visible checkpoint, not an immediate per-mutation sync reflex:
     1. inspect npm run art -- projection status
     2. batch only related same-burst closeouts while the dirty state is known
     3. run npm run art -- projection sync --pi-names "<known-pis>" --target-epic-id <epic-id> --quality before treating roadmap projection health or scoped quality as final
   • do not defer dirty projection sync until the whole Epic is finished; run it at parent closeout, final evidence, or roadmap/quality checkpoints
   • when ART delivery work requires an owner-repo change record, start the record from that repo's docs/records/change-records/TEMPLATE.md and run the touched-record preflight before normal ART execution continues
   • before using a deployment name, pod name, route, work item ID, owner, control name, gate ID, root-cause label, branch, PR, merge state, or completion fact in an operator update or completion record, prove it from the authoritative source for that layer; if it has not been proven, mark it as unverified
2. Keep the truth split explicit:
   • ART = work-state truth
   • owner repos = implementation and design truth
   • workspace-governance = workspace-control truth
3. If the request is not already covered by the active ART, classify it before doing the work:
   • use workspace-governance/docs/work-home-routing-contract.md as the primary classification surface
   • apply the contract's classification order before execution: active_incident_or_blocker, active_art_slice, meaningful_same_initiative_expansion, owner_repo_maintenance, new_business_or_architecture_idea, late_discovered_unclassified_work
   • tiny same-slice patch: absorb it into the active work item
   • meaningful work in the same initiative: add a new item under the active Epic
   • if the operator asks for a broad stage/prod rehearsal, temporary prod activation, or restore-to-baseline exercise, classify the scope as a governed drill before assuming product scope:
     • product-runtime-drill for one governed product lane
     • active-stack-runtime-drill for multi-product or shared-component mixed-lane bring-up plus restore
     • environment-complete-runtime-drill only when every admitted lane and product environment in scope is actually exercised
     • lifecycle-control-drill for lifecycle-state exercises without full runtime bring-up
   • route broad runtime drills through the shared platform workflow in platform-engineering/docs/runbooks/active-stack-runtime-drill.md instead of defaulting to the most mature product-only path
   • do not treat a broad platform rehearsal as OpenClaw-only just because OpenClaw already has the most mature governed promotion path
   • before creating a new item, choose the smallest ART structure that still preserves real owner, review, and validation boundaries
   • one task is only acceptable when the work is genuinely one execution slice with one primary owner path and one materially shared done boundary
   • if the work changes a shared control plane, introduces a new operator workflow, or spans multiple repos with distinct deliverables, do not compress it into one task
   • represent that class of work as a parent Feature plus child tasks for the concrete owner slices such as:
     • workflow model or design decision
     • platform or source implementation
     • security review
     • governance closure or skill/routing updates
   • when the slice is enabling or runway-focused, express that through the real machine metadata:
     • structural delivery types are: Epic, PI Objective, Feature, User story, Defect, Task, Milestone, and Risk
     • use structural Feature or User story
     • set Execution Classification = Enabler
     • use structural Defect for true defect work instead of title-only tagging it as a Task
     • let visible subject prefixes be derived from machine metadata: Risk: from type Risk, Defect: from type Defect, Enabler: or Improvement: from Execution Classification
     • do not invent a structural Enabler type or rely on title-only prefixes
   • if a stopgap placeholder item was created just to avoid leaving the work untracked, replace or retire it before normal implementation continues
   • different business outcome: route it through Workspace Proposals
   • repeated process or control miss: record or update an improvement candidate
   • security or trust-boundary judgment: route it through security-architecture and reflect any blocking impact back in the ART
   • pure owner-repo maintenance outside the initiative: track it in the owner repo only
   • if important work already happened without this classification, reconcile it through the same work-home contract instead of discarding the work or leaving the skipped classification invisible
   • before creating a branch, opening a PR, or implementing source-backed ART work, run the Landing Unit Decision Gate and name one decision: feature_single_landing_unit, child_isolated_landing_unit, non_source_child, or defer_decision_blocked
   • choose feature_single_landing_unit when same-Feature children share the same owner repo, review path, validation surface, deployment timing, security posture, and rollback boundary; use one branch, one PR, and one Review Packet that maps all covered children
   • choose child_isolated_landing_unit only when a child has a real split reason such as different owner repo, independent rollback or deployment, distinct security/trust boundary, materially different validation, urgent blocker, unreviewable diff size, or explicit operator-approved split
   • choose non_source_child for planning, risk disposition, live verification, metadata repair, or other non-source evidence work; do not create fake merge evidence for it
   • choose defer_decision_blocked when sibling scope, owner boundaries, validation surface, or rollback boundary is not understood well enough; stop source work and read the needed ART/repo context before continuing
   • branch by Landing Unit, not by ART child and not automatically by Epic
   • treat a Landing Unit as the smallest source change that should be reviewed, merged, deployed, and rolled back together
   • use a Review Packet to bind landed or explicitly accepted evidence back to one or more ART items
   • for source-backed ART work, create or refresh the draft Review Packet while the PR is still open and set landing_unit.evidence_kind to open_pr
   • before merge, the draft Review Packet must include the PR URL, changed surfaces with explanations, test results, validation results, rollback boundary, and one completion_mapping entry per covered work item
   • before merge, fetch the PR base and run the local command or command set that is CI-equivalent for the changed surface; when required CI uses a base-aware validator, use the same base-ref shape after fetching the base, such as --against-ref origin/main
   • record the CI-equivalent command, base ref, and result in Review Packet validation evidence; if the proof needs operator-side action outside Codex's safe tool boundary, prompt immediately and record the blocker or operator-approved exception instead of relying on GitHub CI as the first proof
   • after the PR is open and before it is merged, run: npm run art -- review-packet readiness <packet.json>
   • do not merge while readiness fails; fix the same PR or explicitly split the Landing Unit instead of planning a corrective PR after merge
   • when editing generated ART payloads, Review Packets, or completion evidence files, use apply_patch or an equivalent reviewed file patch and rerun the relevant local preflight before broker submission; do not make final evidence edits with heredocs, raw redirection, or one-off overwrites unless the generator itself is the reviewed control
   • after merge, update the Review Packet to merged_pr, add the merge commit, finalize it, and use the finalized digest in ART completion evidence
   • do not mark source-backed ART children done until a finalized Review Packet covers them with merged PR evidence, approved direct-land evidence, or equivalent durable source evidence
   • allow one Review Packet to close several ART children when they share the same Landing Unit and rollback boundary
   • close non-source ART items with non-source evidence, such as live verification, planning decision, risk disposition, or metadata repair proof
   • require Feature and Epic closeout to prove every child is covered by a finalized Review Packet or explicitly marked as non-source evidence only
   • backfill is selective and evidence-driven; do not recreate all historical work as ART items just because the rule now exists
   • urgent human/operator bypass can be treated as containment only; reconcile it before adjacent planned ART mutation continues when it affects scope, blocker state, risk state, security posture, or completion evidence
   • reconciliation must record the discovered change, authoritative evidence, selected resolution path, owner repo, any ART/proposal/candidate refs, and operator acceptance when required
4. Keep PI honesty explicit.
   • do not leave work marked committed when it is really stretch or deferred
   • replan the PI when the active front changes materially
   • when new accepted work enters ART, do not skip straight to deep execution structure
   • for the first accepted-idea shaping decision, start with platform-engineering/products/openproject/runbooks/start-delivery-initiative.md
   • the default planning path is:
     1. consume into one Epic shell
     2. frame the initiative while it stays backlog-shaped
     3. create PI objectives and committed features during PI planning
     4. elaborate user stories only for committed features
     5. create tasks only under active user stories or defects
     6. review carryover and decommit work deliberately at PI boundaries
   • use platform-engineering/products/openproject/runbooks/plan-delivery-art.md as the detailed checklist surface for those six phases after the initial entry-shape decision is made
   • treat platform-engineering/products/openproject/delivery-art-planning-workflow.json as the canonical machine-readable gate inventory
   • when planning drift appears, name the exact gate id that failed instead of describing it only as a generic planning problem
   • treat backlog as mostly Epic + Feature
   • do not create User story or Task forests before PI commitment
   • a top-level Epic may stay unclassified only while it remains the new Initiating shell with blank Target PI
   • once a top-level Epic leaves that shell posture, it must carry Initiative Family and Lineage Role
   • follow-on top-level epics must also carry Architecture Anchor Ref and Required Upstream Ref when their lineage role requires them
   • a PI-committed initiative must include at least one PI Objective
   • a backlog Feature may stay umbrella-only, but a PI-committed or active Feature must keep an open User story or Defect child as its leaf front
   • PI Objective, User story, Task, and Milestone work must carry Target PI
   • Milestone is an Epic-level checkpoint only; it does not replace a PI Objective or a Feature leaf front
   • PI-committed non-Epic work must also carry non-backlog Iteration
   • backlog Feature work may exist without Target PI, but it must stay umbrella-shaped until commitment
5. Update the ART when work-state changes:
   • status
   • blocker or risk state
   • PI commitment
   • PM² phase and initiative-review evidence
   • completion evidence
   • initiative closeout now has a governed review sequence:
     1. record System Demo Evidence
     2. move the initiative Epic into PM² Closing only after the execution tree is clean
     3. record Inspect & Adapt Actions
     4. mark the initiative done only from PM² Closing
   • initiative retired is a separate terminal path, not a PM² phase
     • use initiative governance to set status = retired
     • only do that after all descendants are already done or retired
   • use platform-engineering/products/openproject/runbooks/review-delivery-initiative.md as the primary checklist surface for that closeout path
   • treat platform-engineering/products/openproject/delivery-art-initiative-review-workflow.json as the canonical machine-readable initiative-review gate inventory
   • when PM² closing drift appears, name the exact gate id instead of calling it only a generic closeout problem
   • use platform-engineering/products/openproject/runbooks/manage-delivery-blockers.md as the primary checklist surface for blocker trigger, recording, and clear doctrine
6. Close work only through the supported evidence-backed completion path.
7. Raise active-slice narrative weakness explicitly.
   • if the ART-quality check reports rewrite-required or discussion-required findings on active or next-up work, bring that to the operator before continuing that item
   • propose the rewrite shape clearly instead of silently working around weak content
8. If active work becomes half-finished or the operator explicitly calls out a repeated mistake, half-baked state, or missed catch:
   • run python3 /home/mfshaf7/projects/workspace-governance/scripts/check_self_improvement_escalation.py ...
   • record the candidate before continuing normal execution when the signal is in the fail-closed set
9. When using delegated execution for ART-backed work:
   • keep ART mutation, live proof, security closure, and final completion with the main agent
   • create a bounded packet before spawn
   • keep delegated write scopes disjoint
   • record the delegated run in the delegation journal when delegated write is used
   • classify any newly discovered scope through the ART before treating it as accepted work

Guardrails

• Do not let meaningful uncovered work live only in chat.
• Do not reconstruct the work queue from handoff prose when the ART already exists.
• Do not hide a cross-repo control-plane or workflow change inside one coarse ART task when the real work has distinct owner, review, or validation slices.
• Do not leave a temporary placeholder item as the lasting execution model once the proper parent-plus-children structure is clear.
• Do not reconstruct prior-done sibling context by manually scanning a giant execution-summary payload when the continuation-context read is available.
• Do not present a ready umbrella item as the next ART front from planning alone; confirm it still has open execution scope through its own continuation-context first.
• Do not treat repo code or contracts as the work queue; they are the implementation truth, not the planning truth.
• Do not turn raw broker access into the normal workflow. Use the documented npm run art -- ... broker CLI, optimized active-session/evidence packets, Review Packet commands, and landing-unit closeout commands first. Raw k3s kubectl exec ... node -e ... broker calls are fallback-only debugging paths when the CLI or broker runtime itself is under test.
• Do not guess broker caller auth headers during delivery work; reuse the broker pod's own allowed caller id and shared secret from environment.
• Do not guess ART assignee or responsible values; read the live assignable principal list first and use the exact login it returns.
• Do not leave stretch work looking committed just because it still exists in the same PI.
• Do not silently continue on active work whose narrative contract is too weak to operate safely.
• Do not continue active delivery work normally after a fail-closed self-improvement signal.
• Do not let delegated workers mutate the ART, live environments, security closure, or final proof surfaces.
• Do not assume valid completion-evidence bullets mean the done record is acceptable; the done-state narrative contract is a separate hard gate now.