Logics flow

Conventions

• Keep workflow docs in logics/request/, logics/backlog/, logics/tasks/.
• Use companion docs in logics/product/ for structuring product framing and logics/architecture/ for structuring technical decisions.
• Use numeric IDs and slugs in filenames: req001mytitle.md, item002somescope.md, task003dothework.md.
• When mentioning files in generated docs, use repo-relative paths such as logics/... or src/..., never absolute filesystem paths such as /Users/....
• Keep indicators at the top:

- From version: X.X.X - Status: Draft | Ready | In progress | Blocked | Done | Obsolete | Archived - Understanding: ??% - Confidence: ??% - Progress: ??% (mainly tasks; optionally backlog) - Complexity: Low | Medium | High - Theme: Combat | Items | Economy | UI | ...

• When writing a request, the # Context section must include a Mermaid diagram that visualizes the need.
• Prefer a compact business-readable flowchart TD or flowchart LR showing inputs, decision points, outputs, and feedback loops.
• Backlog items should include a Mermaid diagram that makes the delivery slice explicit: request/source -> problem -> scope -> acceptance criteria -> task(s).
• Tasks should include a Mermaid diagram that shows the execution path: backlog/source -> implementation steps -> validation -> done/report.
• Generated workflow Mermaid blocks now include %% logics-signature: ... metadata comments; keep them aligned with the current doc context so stale diagrams can be detected automatically.
• Mermaid safety rules are mandatory:

- use plain ASCII text labels only - do not use Markdown formatting inside node labels: no backticks, bold, italics, or inline code - do not put raw route syntax or braces in labels such as /users/{id}; rewrite them as plain text like users-id route - do not use + to concatenate task names inside labels; rewrite as plain text such as task 1 and task 2 - keep labels short and business-readable so strict Mermaid renderers can display them consistently

If unsure, open logics/instructions.md and follow the workflow described there.

Command examples below use python ... as the canonical cross-platform launcher. The preferred stable entrypoint is now python logics/skills/logics.py ..., which routes toward the flow manager and adjacent kit commands behind one operator-facing contract. If your environment only exposes python3 or py -3, substitute that launcher.

Create a new doc (recommended)

Use the generator script (picks the next available ID, creates a file from templates):

python logics/skills/logics.py flow new request --title "Offline recap UI"
python logics/skills/logics.py flow new request --title "Offline recap UI" --fixture
python logics/skills/logics.py flow new backlog --title "Offline recap UI"
python logics/skills/logics.py flow new task --title "Implement offline recap UI"

After creation, run logics-confidence-booster to raise Understanding/Confidence above 90%:

python logics/skills/logics-confidence-booster/scripts/boost_confidence.py logics/request/req_001_example.md
python logics/skills/logics-confidence-booster/scripts/boost_confidence.py logics/backlog/item_002_example.md
python logics/skills/logics-confidence-booster/scripts/boost_confidence.py logics/tasks/task_003_example.md

When a request or backlog item surfaces a structuring product choice, create a product brief before or alongside promotion:

python logics/skills/logics-product-brief-writer/scripts/new_product_brief.py --title "Guest checkout framing" --out-dir logics/product

When a backlog item surfaces a structuring technical choice, create an ADR/DAT:

python logics/skills/logics-architecture-decision-writer/scripts/new_adr.py --title "Choose cache strategy" --out-dir logics/architecture

For backlog/task creation or promotion, the script now auto-detects product and architecture signals and writes a # Decision framing section in generated docs. It stays advisory by default and can auto-create the companion docs when you opt in:

python logics/skills/logics.py flow new backlog --title "Checkout auth migration" --auto-create-product-brief --auto-create-adr

Optional flags:

• --from-version 0.14.3
• --understanding 60% --confidence 40%
• --status Draft|Ready|In progress|Blocked|Done|Obsolete|Archived
• --complexity Low|Medium|High --theme UI
• --progress 0% (task/backlog)
• --fixture or --smoke-test (request only; generate a compact synthetic request shape)
• --auto-create-product-brief (backlog/task only; create logics/product/prod###*.md when product framing is required)
• --auto-create-adr (backlog/task only; create logics/architecture/adr###*.md when architecture framing is required)
• --dry-run (show path + content preview, no writes)

Promote between stages

Create the next-stage doc and link back to the source:

python logics/skills/logics.py flow promote request-to-backlog logics/request/req_001_offline_recap_ui.md
python logics/skills/logics.py flow promote backlog-to-task logics/backlog/item_002_offline_recap_ui.md

For request -> backlog promotion, default to a split-first mindset:

• use python logics/skills/logics.py flow assist suggest-split <request-ref> --format json when the request spans multiple user flows, delivery surfaces, risks, or acceptance criteria;
• then use python logics/skills/logics.py flow split request ... to cover the request with several bounded backlog items;
• do not compress broad request coverage into only one or two oversized backlog items just to keep the split count low;
• use direct promote request-to-backlog only when the request is already atomic enough to map to one clear backlog slice.

The promotion flow seeds more of the next-stage document automatically:

• source indicators such as From version, Understanding, Confidence, Complexity, and Theme;
• request acceptance criteria into backlog acceptance criteria + AC traceability;
• backlog acceptance criteria into task AC traceability;
• source context/problem statements into the generated problem/context sections;
• actionable Decision framing follow-up text inside the generated doc itself.
• generated docs are prevalidated during generation/promotion so stale Mermaid signatures and incomplete AC traceability are caught before audit time.

Split a broad request/backlog item into several executable children:

python logics/skills/logics.py flow split request logics/request/req_001_example.md --title "Slice A" --title "Slice B"
python logics/skills/logics.py flow split backlog logics/backlog/item_002_example.md --title "Task A" --title "Task B"

logics.yaml now drives the default split policy. The shipped default is minimal-coherent, so keep splits to the smallest coherent slice count unless you explicitly pass --allow-extra-slices. In practice, request coverage still comes first: if a broad request needs several bounded backlog items, keep the slices explicit instead of collapsing them into one or two large items.

Close docs with automatic transition propagation:

python logics/skills/logics.py flow close task logics/tasks/task_003_example.md
python logics/skills/logics.py flow close backlog logics/backlog/item_002_example.md
python logics/skills/logics.py flow close request logics/request/req_001_example.md

When a task is actually finished, prefer the kit-native guarded flow instead of editing indicators manually:

python logics/skills/logics.py flow finish task logics/tasks/task_003_example.md

finish task closes the task, propagates closure to linked backlog/request docs when eligible, verifies that the linked chain stayed synchronized, appends finish/report evidence to the task, and leaves a completion note in linked backlog items. Use close only when you explicitly want the lower-level primitive.

Generated tasks now include explicit wave checkpoints:

• each completed wave should leave the repository in a coherent, commit-ready state;
• linked Logics docs should be updated during the wave that changes the behavior;
• prefer one reviewed commit checkpoint per meaningful wave rather than several undocumented partial states.
• if the shared AI runtime is active and healthy, use python logics/skills/logics.py flow assist commit-all for the commit checkpoint of each meaningful step, item, or wave.
• do not mark a wave or step complete until the relevant automated tests and quality checks have been run successfully.

When one orchestration task covers multiple backlog items:

• put one - Derived from \...\` line per linked backlog item in the task # Links` section;
• keep the lines explicit even when the task is a parent wave that spans several backlog slices;
• prefer the repo-relative backlog path so the generated task stays traceable without extra lookup.

Run workflow coherence audit:

python logics/skills/logics.py audit
python logics/skills/logics.py audit --stale-days 30
python logics/skills/logics.py audit --group-by-doc
python logics/skills/logics.py audit --format json
python logics/skills/logics.py audit --autofix-ac-traceability
python logics/skills/logics.py audit --refs req_001_example
python logics/skills/logics.py audit --paths logics/request logics/backlog
python logics/skills/logics.py audit --since-version 1.9.0
python logics/skills/logics.py flow sync refresh-mermaid-signatures

Use the guarded local dispatcher when you want a local model to propose a workflow action without giving it direct file-write authority:

python logics/skills/logics.py flow sync dispatch-context req_088_add_a_local_llm_dispatcher_for_deterministic_logics_flow_orchestration --include-graph --include-registry
python logics/skills/logics.py flow sync dispatch req_088_add_a_local_llm_dispatcher_for_deterministic_logics_flow_orchestration --model deepseek-coder-v2:16b --include-graph --include-registry
python logics/skills/logics.py flow sync dispatch req_088_add_a_local_llm_dispatcher_for_deterministic_logics_flow_orchestration --decision-file /tmp/dispatcher-decision.json --execution-mode execute

Dispatcher rules:

• sync dispatch-context builds a compact machine-readable bundle around context-pack, with optional graph, registry, and doctor summaries.
• sync dispatch validates a strict decision contract with only new, promote, split, finish, and safe non-destructive sync actions.
• suggestion-only is the default mode; use --execution-mode execute only when you explicitly want the runner to invoke the mapped Logics command.
• Dispatcher runs append JSONL audit records to logics/dispatcher_audit.jsonl unless you override --audit-log.
• The Ollama path is transport-specific only; the deterministic runner and decision schema stay runtime-agnostic.
• sync build-index refreshes the runtime cache used by repeated context, graph, doctor, validation, and registry operations.
• sync show-config exposes the effective logics.yaml merge so automation can inspect the active split policy, mutation mode, and cache path.
• sync refresh-ai-context and sync migrate-schema now support repo-configurable transactional apply-or-rollback semantics and emit JSONL audit records to logics/mutation_audit.jsonl by default.

Use the shared hybrid assist runtime when the user asks for repetitive delivery help that should opportunistically use Ollama but still degrade safely:

python logics/skills/logics.py flow assist runtime-status --format json
python logics/skills/logics.py flow assist roi-report --format json
python logics/skills/logics.py flow assist commit-all
python logics/skills/logics.py flow assist summarize-pr --format json
python logics/skills/logics.py flow assist summarize-validation --format json
python logics/skills/logics.py flow assist next-step req_089_add_a_hybrid_ollama_or_codex_local_orchestration_backend_for_repetitive_logics_delivery_tasks --format json
python logics/skills/logics.py flow assist triage req_090_add_high_roi_hybrid_ollama_or_codex_assist_flows_for_repetitive_logics_delivery_operations --format json
python logics/skills/logics.py flow assist handoff req_090_add_high_roi_hybrid_ollama_or_codex_assist_flows_for_repetitive_logics_delivery_operations --format json

Hybrid assist rules:

• prefer the named aliases over ad hoc shell commands;
• keep python ... as the canonical cross-platform launcher;
• runtime-status is the shared probe surface for plugin, Codex, and Claude integrations;
• roi-report is the shared observability surface for CLI automation and plugin insights, including explicit measured, derived, and estimated sections;
• use --model-profile qwen-coder when the operator explicitly wants the curated Qwen path instead of the default DeepSeek profile;
• the shared runtime keeps backend provenance, degraded reasons, audit JSONL, and measurement JSONL visible to downstream surfaces;
• risky execution stays bounded: suggestion-only remains the default unless the operator intent is explicit.

Manage legacy per-repository Codex overlays when several repos still need workspace-specific CODEX_HOME projections during migration or troubleshooting:

python logics/skills/logics-flow-manager/scripts/logics_codex_workspace.py register
python logics/skills/logics-flow-manager/scripts/logics_codex_workspace.py sync
python logics/skills/logics-flow-manager/scripts/logics_codex_workspace.py status
python logics/skills/logics-flow-manager/scripts/logics_codex_workspace.py doctor --fix
python logics/skills/logics-flow-manager/scripts/logics_codex_workspace.py run -- codex
python logics/skills/logics-flow-manager/scripts/logics_codex_workspace.py clean

This overlay manager is no longer the primary runtime path. The default model is a globally published kit under ~/.codex, while this legacy flow keeps logics/skills/ canonical in the repo, projects repo-local skills into ~/.codex-workspaces/<repo-id>/, lets repo-local skills shadow same-named global skills, and keeps shared user assets such as auth.json, config.toml, and skills/.system referenced from the primary ~/.codex/ home when available.

After promotion:

• Ensure the backlog item has clear acceptance criteria + priority.
• Ensure the task has a step-by-step plan and at least 1–2 validation commands relevant to the work.
• Ensure broad requests are represented by several bounded backlog items rather than one or two oversized slices.
• Ensure each task explicitly treats successful test execution as a gate before closing any step or wave.
• Ensure each task uses the shared flow assist commit-all checkpoint when the AI runtime is active and healthy.
• Ensure the source request lists any generated backlog items in its Backlog section.
• Carry forward any linked prod### and adr### refs so downstream docs keep the product and architecture framing visible.

Before promotion:

• If Understanding or Confidence is below 90% in the source doc, run the logics-confidence-booster skill first to clarify and update indicators.
• If the need requires a non-trivial product framing document, write a product brief in logics/product/ and reference it from the source doc before promotion.
• If the need requires a non-trivial technical decision, write an ADR in logics/architecture/ and reference it from the source doc before promotion.
• For request docs, replace the default Mermaid scaffold with a diagram specific to the need before considering the request ready.
• For backlog/task docs, replace the default Mermaid scaffold with a doc-specific diagram whenever the default no longer reflects the real flow.
• Refresh the Mermaid block whenever the title, problem/need, acceptance criteria, plan, validation path, or source links change in a way that changes the delivery story.
• Before finalizing any Mermaid diagram, sanity-check that the labels still obey the Mermaid safety rules above so previewers do not fall back to raw source rendering.