Architecture and design

<!-- sflow-copilot-pause -->

First run singularity-flow phase enter --compose --for-agent --json once in every turn, also after an interrupted one: an earlier turn's entry is context, not this turn's binding. It composes context only when admitted. Lookup from current cwd (non-Git allowed). Never search /Users, $HOME or parents for a repo. Require returned ready/workId/repositoryPath; unavailable: /sf-session or /sf-workspaces, stop. It checks pause before Git. If paused, native Copilot; only offer /sf-pause off, never resume implicitly. Otherwise follow agentGuide.readOrder once, reuse binding/recovery/clarification/references and delivered inputs from this entry; no duplicate lookups. Read clarification.checkpoint: missing answers permit questions, not drafting. Missing record is not unanswered: reuse same-binding replies; repair recording. Never ask users to supply questions or slice control instructions. Use personalization.replyName literally in replies, never artifacts or approval identity.

<!-- sflow-output-contract: clarification-and-artifact -->

Output contract: Author configured artifacts from governed inputs and pinned clarification; publish only after readiness. Approved phase inputs are the earlier steps' outputs and settle what they state: never ask what they answer or search elsewhere for them. Summarize artifacts with verified Markdown-preview links; never paste document bodies, code or diffs into Copilot. For code, list touched paths and observed added/deleted/created line counts; unavailable stays unavailable. Use existing evidence, not extra calls solely for display. Summaries, links and opened previews are not human review or approval. For every next action, honor returned commandGuidance in order: Copilot, Shell, VS Code (model-free) using modelFreeCommand; if absent, say "not available for this action". Missing Copilot: "no verified equivalent". Never invent routes. On a refusal read remediationPlan: run its first read-only step once and follow context.strategy; never retry an unchanged condition or edit an earlier phase to clear it. One returned automatic plan-hash action (such as sync) may run once, then re-enter once. When a result's act.state is author, or it routes back to this skill with nothing for a person to answer, edit, review or confirm, that is this turn's own work: do it, never relay it. A file edit that does not match is not a refusal: read the file again and redo the edit. Run a check only when a returned field or command asks for it; never decide from a step's name, kind or route that it applies. A refusal saying a check does not apply to this step is not a blocker: skip it and continue. Act on a result's act first: its state, do routes and any ask. A bounded result names agentOutput.read ranges and omittedFields text files; read all in one response with your file tool. If your host saved a result to a file you cannot open, run that command again with --for-agent --json; never read the host's copy with shell tools.

<!-- sflow-execution-boundary -->

Boundary: reuse entry ready/workId, valid phaseAgent; cwd=repositoryPath. Honor mutationContract. Returned workItemRoot/artifact paths only; never $HOME. Use exact CLI-returned paths. repositoryPath is command cwd, not a prefix for absolute file paths. Never rebase paths or strip .git/worktrees. Issued private/external files are exact exceptions to repository confinement, not wider read/write permission; writes still need authorization. Resolve relative paths only against their declared base. On failure, preserve the path and error; never search or recreate it. Blocked: relay resolution.issues[].choices too. Eligible risk needs reason/expiry and authorized human confirmation. Never auto-accept risk.

1. Use entry authoring. If policyVerified is false, show policyReason, offer /sf-validate then /sf-recover; stop. Continue only if effectiveAuthoringSkill is /sf-design, or /sf-phase with authoringSkill null and <phase> = design; else relay its verified route; null drafts nothing. retained-generation: relay next, stop.
2. Review entry recovery and exact diffs; stop for protected/unowned edits or required human decisions. successor-preparation-required: run successor.preparation.command, preserve private drafts/publications and refresh entry once. Use entry context.text; if not-requested or stale, rerun it once with <phase> --work-id <WORK-ID> --compose. Not admitted: relay blockers/next, stop. Never infer --task.
3. Reuse delivered inputs; expand only needed missing/truncated material. Inspect selected source/uploads; use references.repositories[].localPath, no repeated verification.
4. Follow entry clarification.checkpoint; off skips. Reuse actual same-binding replies; ask only unanswered/materially changed questions with ask_user, then record before preparation. Unavailable: show questions and stop; stage chat replies. Confirm boundaries/contracts/failures/tradeoffs. File-edit only the issued staging path; run checkpoint.recordAction alone. On refusal preserve replies and repair recording, not questions.
5. Preparation is not authoring. Run singularity-flow prepare <phase> unless prepared in step 2; use the native file-edit tool to complete the existing document from context.text and approved evidence, including Agent brief. Resolve template TODOs, preserve managed blocks; never invent or pad.
6. Cover components, interfaces, data flow, alternatives, compatibility, security, privacy, observability, migration, rollout/rollback, risks, and implementation order.
7. State assumptions and tradeoffs. Do not implement production code.
8. Run singularity-flow phase prepublish <phase> --for-agent --json --publish-if-ready (includes draft-check). Unready: reuse findings/resolution; fresh diagnostics only when requested by its next action. Stay in this phase. Correct agent findings from governed evidence only when correction.sameTurn; else route to owner/regenerator via correction.guidance/correction.skill. Never blindly delete markers, invent facts/padding, nest models or overwrite producers. Follow returned repairLoop.protocol; stop unchanged.
9. Use returned commands.publish when ready unless publishIfReady.published; absent: relay commands.next, stop. Race-time ARTIFACT_AUTHORING_INCOMPLETE: recheck once, retry once if ready, never loop. Never submit or approve.
10. From publishIfReady.review, summarize the published documents with verified Markdown-preview links, generation/hashes, warnings and current reviewBinding. Never reproduce bodies or count a summary/link as human review; document reuse never carries approval consent.
11. Report commit/tokens. Relay each handoff: Next in Copilot: /sf-… from copilotCommand, then Terminal equivalent: singularity-flow … from command.