@adamchanadam/cer-workflow 0.3.17

package/skills/cer-workflow-en/references/parallel-producers.md

@@ -0,0 +1,174 @@
+# Parallel Candidate Producers
+
+<!-- cer-parallel-producers-owner -->
+
+This file is the sole complete rule owner for CER parallel candidate producers. It defines how C
+may use an inline, informal capability on demand while preserving formal roles, the single writer,
+fresh Reviewers, source-based adjudication, and stop boundaries.
+
+## Contents
+
+- [Position And Role Boundary](#position-and-role-boundary)
+- [Keep User Operation Simple](#keep-user-operation-simple)
+- [Activation Eligibility](#activation-eligibility)
+- [Frozen Lane Contract](#frozen-lane-contract)
+- [Modes And Write Boundary](#modes-and-write-boundary)
+- [Mechanical Scratch-Root Boundary](#mechanical-scratch-root-boundary)
+- [Candidate Return](#candidate-return)
+- [C Readback, Adjudication, And Convergence](#c-readback-adjudication-and-convergence)
+- [Failure, Drift, And Lifecycle](#failure-drift-and-lifecycle)
+- [Prohibitions](#prohibitions)
+
+## Position And Role Boundary
+
+- CER has only the formal roles C, E1, R, and E2. A parallel candidate producer is not a fifth
+  role and receives no formal title, cycle, ready, result, batch lifecycle, or Reviewer identity.
+- A producer is C's inline, informal, on-demand candidate capability. It adds no slash command,
+  lock, registry, run id, resident mode, or background service.
+- A producer does not replace E1 for writes to the formal project, replace R for independent
+  challenge, or communicate directly with E1, E2, or R.
+- The formal project still has only one writer, E1. E2 may take over only after the existing
+  takeover conditions hold. No producer, C, or R becomes a parallel project writer.
+
+## Keep User Operation Simple
+
+Normal CER use keeps the existing explicit trigger and five commands. The user does not configure
+producers, lanes, scratch roots, hashes, roles, or extra review procedures and does not need to
+learn the term "parallel candidate producer." C decides internally whether parallel work is
+worthwhile, assigns lanes, and verifies isolation. When value or safety cannot be proven, C uses
+zero producers and returns to serial analysis. Report only results, unknowns, blockers, or risks
+that materially affect the user, without exposing internal lane ceremony.
+
+## Activation Eligibility
+
+C may start two or more parallel lanes only when every condition below holds:
+
+1. At least two work lanes are independent and need no result from each other, shared mutable
+   state, or fixed execution order.
+2. Each lane's input and source identity is frozen.
+3. C has non-duplicative critical analysis, gating, or adjudication work to do concurrently and
+   does not degrade into a candidate organizer.
+4. C can independently verify each candidate against authoritative sources.
+5. Expected net time savings materially exceed startup, readback, hashing, deduplication, and
+   adjudication costs.
+6. Required parallel execution slots are available without reducing capacity needed by formal E1
+   or a fresh R.
+
+If any condition fails, is uncertain, or one bounded read is sufficient, `producer_count=0` and C
+completes the analysis serially. This is normal auto-idle, not degradation, an error, or a mode the
+user must configure.
+
+## Frozen Lane Contract
+
+Before a lane starts, C freezes all of the following:
+
+- `lane_label`, used only to identify this candidate and not as a formal role or run id.
+- `mode`, which must be either `read_only` or `isolated_artifact`.
+- One objective.
+- Input identity and version, source identity, and verifiable source coordinates.
+- Allowed and forbidden scope.
+- Expected candidate output.
+- Acceptance method.
+- Stop condition.
+- For `isolated_artifact`, a lane-specific `scratch_root` explicitly supplied by C and already
+  accepted by the mechanical boundary check.
+
+A lane does not start, or becomes invalid immediately, when its contract is unfrozen,
+contradictory, or rewritten by the producer. A producer cannot expand its objective, sources,
+permissions, output, or acceptance.
+
+## Modes And Write Boundary
+
+### `read_only`
+
+- The lane must perform zero writes everywhere, including the project, scratch space, temporary
+  storage, external systems, and the producer's visible workspace.
+- It may read only inputs and sources assigned by C and return a text candidate.
+
+### `isolated_artifact`
+
+- The lane may write only to its task-owned, lane-specific `scratch_root` explicitly supplied by C.
+- It must not write the target project, formal sources of truth, another lane, a user root, system
+  location, external service, or any unlisted target.
+- An artifact is a candidate, not a formal project result. Only C may read it back, recompute its
+  hash, and converge it. A producer cannot send it directly to E1 or R for use.
+
+## Mechanical Scratch-Root Boundary
+
+Before an artifact lane starts, C resolves the actual absolute path and proves every condition:
+
+1. `scratch_root` and the target project do not contain each other; neither is an ancestor of the
+   other.
+2. `scratch_root` is not a drive root, user root, system root, or equivalent high-risk root.
+3. The existing path chain contains no symlink, junction, Windows reparse point, mount, or other
+   link that redirects writes to an unverified location.
+4. Lane roots are distinct, are not ancestors of one another, and do not overlap formal sources
+   of truth, another lane, or an external system.
+5. Actual tool permissions allow only that lane's explicit root. Relative paths, wildcards,
+   environment fallback, or a producer-selected location cannot expand the boundary.
+
+If any condition cannot be proven, the lane does not start. Do not fall back to staging inside the
+project, shared scratch space, a user root, or another more dangerous location.
+
+## Candidate Return
+
+Every naturally arriving candidate includes at least:
+
+- `lane_label`.
+- Frozen input identity.
+- Actual source coordinates.
+- `claims`, with each candidate claim verifiable from its source.
+- `unknowns`, covering missing, conflicting, unverified, or restricted material.
+
+An `isolated_artifact` candidate also lists the actual absolute path and SHA-256 for each artifact.
+A return is not a formal CER ready/result, uses no formal batch identity, and is not acceptance,
+progress, or Reviewer evidence.
+
+## C Readback, Adjudication, And Convergence
+
+- C personally reads back sources and artifacts supporting critical claims; a producer summary is
+  not a substitute.
+- C recomputes SHA-256 for every artifact and verifies that its path remains under the accepted
+  scratch root, input identity has not drifted, and source coordinates are replayable.
+- When sources or candidates conflict, C adjudicates from user decisions, project sources of
+  truth, and authoritative sources required by the task. C must not accept by vote, quantity,
+  completion order, or matching answers.
+- C converges only material still inside the intake boundary with unchanged sources and hashes
+  that can be independently verified.
+- Only after C completes readback, deduplication, conflict adjudication, and convergence may it
+  form a formal self-contained batch for E1. E1 receives only that C-converged batch and must not
+  use raw producer communication, lane summaries, or unconverged scratch artifacts directly.
+- R still challenges the frozen original evidence independently. A producer candidate cannot
+  impersonate fresh R evidence.
+
+## Failure, Drift, And Lifecycle
+
+- C does not wait, poll, or background-monitor producers. It uses only candidates that arrive
+  naturally while the intake boundary remains open.
+- A late candidate is invalid after intake closes, the formal batch is frozen, or `/CER-stop` or
+  `/CER-close` begins. It cannot reopen an adjudicated batch.
+- Input or source drift discards only lanes that depend on that identity. Unaffected lanes do not
+  rerun.
+- An out-of-bounds artifact path, hash drift, tamper, unreplayable source, or lane-contract drift
+  fails closed and cannot be converged.
+- If producer creation fails, subagent capability is unavailable, a producer times out, no result
+  arrives naturally, or a candidate cannot be verified, C returns to ordinary serial analysis and
+  does not repeat the same failure. CER blocks only when the missing evidence is itself a task
+  blocker.
+- `/CER-stop` and `/CER-close` do not wait for producers. C stops accepting new candidates, lets
+  late material expire, and follows the formal E1/R lifecycle for stop or close.
+
+## Prohibitions
+
+- A producer impersonates C, E1, R, E2, or a fresh Reviewer.
+- A producer uses a formal title, cycle, ready, result, slash, lock, registry, or run id.
+- C, R, or a producer writes the target project, or any shared-workspace writer exists besides E1.
+- A `read_only` lane writes anything.
+- An `isolated_artifact` lane writes outside its accepted lane root or uses a project-contained or
+  ancestral path, drive root, user root, system root, link, junction, reparse point, mount, or
+  overlapping lane.
+- A producer sends a candidate directly to E1, E2, or R, or E1 uses unconverged scratch.
+- Producer count, votes, speed, or matching answers replace C's source-based adjudication.
+- The user must configure lanes, scratch roots, hashes, roles, review procedures, or a new command.
+- C polls or background-monitors producers, delays stop/close to wait for them, or accepts a late,
+  drifted, tampered, or out-of-bounds candidate.

package/skills/cer-workflow-en/references/roadmap.md

@@ -0,0 +1,198 @@
+# User Checkpoints And Roadmap
+
+## Contents
+
+- [Two Different Surfaces](#two-different-surfaces)
+- [Standard Inline Visualizer Timing](#standard-inline-visualizer-timing)
+- [Fixed Lifecycle Cards](#fixed-lifecycle-cards)
+- [Other Fixed Checkpoint Cards](#other-fixed-checkpoint-cards)
+- [Bear Card Timing](#bear-card-timing)
+- [Display Priority](#display-priority)
+- [Role Display Boundary](#role-display-boundary)
+- [Roadmap Source](#roadmap-source)
+
+## Two Different Surfaces
+
+- The **inline visualizer roadmap** is the standard progress surface for long-running,
+  multi-stage, multi-batch, or first-public-alignment CER work without requiring user action. Layout, stage count, and
+  extra fields adapt to the project. Do not use a fixed four-box or fixed-table template as a
+  substitute for real task information. Minimum content is defined under "Display Priority".
+  Work that needs convergence also shows the living task brief, current batch freeze, and next
+  observable checkpoint.
+- The **four-color ASCII bear card** is a checkpoint signal. It answers whether the user must preview,
+  decide, handle a blocker, or accept a result. It is not the roadmap or a continuous tracker.
+
+Both may appear in one message, but they do not repeat content: the roadmap shows global
+position, while the card names the current checkpoint.
+
+## Standard Inline Visualizer Timing
+
+1. When C classifies work as multi-stage, multi-batch, or a new product, flow, design, content,
+   or experience deliverable that needs first public alignment, show the initial roadmap before
+   the first real batch. It includes the living task brief, current batch freeze, and next preview
+   or decision point.
+2. Update it after C reads back and accepts a result that creates an outcome difference for a user
+   completion condition, or after a necessary diagnostic changes the next handoff path.
+3. When a user decision, an actual new constraint, or R evidence materially changes direction,
+   scope, deliverable shape, risk, or acceptance state, show the difference from the prior version
+   before updating it.
+4. Show the matching terminal state at staged delivery, technical acceptance, fit check, or closeout.
+
+Do not update it for ordinary internal reads, E1 substeps, polling, unadjudicated candidates,
+review completion, format pass, file consistency, logged issues, completed designs, or details
+that do not change a user completion condition. Progress comes only from bounded readback after
+direct-push, C adjudication, and an accepted outcome difference against `outcome_anchor`.
+
+## Fixed Lifecycle Cards
+
+Before showing any lifecycle or checkpoint bear card, read `VERSION` again from this Skill root.
+Stable semver `X.Y.Z` renders as `vX.Y.Z`; a missing, unreadable, or malformed value renders as
+`version unverified`. `{package_version}` in the cards below is a template placeholder. Replace
+it completely with the current `VERSION` before output and never display the placeholder itself.
+Every card must be output as a standalone fenced `text` code block. Do not put it in a bullet,
+block quote, ordinary paragraph, or the same Markdown block as other text.
+
+```text
+   ()_()   CER Workflow v{package_version}
+  ( o.o )  🔵 CER started
+   ( ^ )
+```
+
+Every successfully accepted `CER-start`, including simple single-batch work, uses this fixed
+open-eye start card. Keep the complete three-line ASCII bear: version on the first line, status on
+the second line, and only the bear base line on the third line.
+
+A successful `/CER-stop` uses this fixed closed-eye stop card:
+
+```text
+   ()_()   CER Workflow v{package_version}
+  ( -.- )  ⚪ CER stopped · CER inactive
+   ( ^ )
+```
+
+A successful `/CER-close` uses this fixed closed-eye close card:
+
+```text
+   ()_()   CER Workflow v{package_version}
+  ( -.- )  🟢 CER closed · writer closed
+   ( ^ )
+```
+
+A closed-eye card is proof of a verified terminal state, not an intent receipt. Show the stop
+card only after proving no active writer or a stopped writer and completing required readback.
+Show the close card only after proving `writer closed`, completing required readback, and reading
+back either a `✓` appended to this cycle's cycle number in every verifiable C/E/R title or a
+`title sync warning`. The closed-eye close card proves writer close and required readback, not
+all-green title sync. When any evidence is missing, use the open-eye red blocker card:
+
+```text
+   ()_()   CER Workflow v{package_version}
+  ( o.o )  🔴 Major blocker · checkpoint blocked
+   ( ^ )
+```
+
+## Other Fixed Checkpoint Cards
+
+Non-lifecycle checkpoints keep the open-eye ASCII bear and also use a standalone fenced `text`
+code block. Version stays on the first line, and the status is replaced on the second line. If the
+version is invalid, they also show `version unverified`.
+
+- `🟡 Direction decision`
+- `🔴 Major blocker`
+- `🟢 Staged delivery / final acceptance`
+
+## Bear Card Timing
+
+CER is a continuous loop, but it does not show a card for every small step:
+
+1. Every successfully accepted `CER-start` first uses one fixed `🔵 CER started` card as the
+   startup receipt, including single-batch work. Long-running, multi-batch, or first-public-
+   alignment work adds the full inline roadmap in the same message.
+2. Use `🟡 Direction decision` when the user must choose a material direction, scope,
+   deliverable shape, cost, knowledge source, or acceptance standard.
+3. Use `🔴 Major blocker` when a communication path, threadId or platform-equivalent coordinate, permission,
+   source of truth, knowledge foundation, platform capability, or safety condition is
+   insufficient for reliable continuation.
+4. Use `🟢 Staged delivery` when an observable stage is ready for user acceptance after C
+   adjudication or risk-based R review.
+5. A successful `/CER-stop` shows the fixed closed-eye `⚪ CER stopped` card. A successful
+   `/CER-close` shows the fixed closed-eye `🟢 CER closed` card. Ordinary final acceptance may
+   still use the open-eye `🟢 Final acceptance` checkpoint and must not impersonate a lifecycle
+   terminal state.
+
+Do not show a card for ordinary internal reads, low-risk small edits, E1 substeps, ordinary batch
+acceptance, R completion that creates no user checkpoint, or a clear next action. Update only the
+inline roadmap when progress changed.
+
+## Display Priority
+
+The inline roadmap shows at minimum: a testable destination; ordered stages with
+complete/current/pending state; overall progress; the current action and verified evidence or
+blocker; C/E1/R state; the next checkpoint; and knowledge-foundation state only for
+knowledge-heavy work. First public alignment also shows scope/exclusions, key assumptions, the
+smallest observable result, whether technical acceptance and fit check apply, and whether a user
+decision is needed. Work that needs convergence also shows the living task brief: confirmed
+requirements/exclusions, safe inferences, critical gaps, latest feedback, current batch freeze,
+the next preview or decision point, and what changed from the previous version. A bear card reduces the current situation to a preview, decision,
+blocker, or acceptance checkpoint. Both derive from existing project plan/progress or verified
+execution state and do not create a second progress source.
+Any user-visible living-brief rendering must carry `CER` identity and C/E1/R or
+Controller/Executor/Reviewer context. Do not present it as a Codex task brief, Goal plan,
+assistant plan, or unbranded internal feature.
+The living task brief also derives only from the highest available authority and C-adjudicated facts.
+Long multi-batch work also shows the unfinished `outcome_anchor` conditions, accepted outcome
+differences, whether diagnostic/mechanism work is non-mainline only, and how the next batch
+continues a completion condition. Do not substitute batch, task, or review counts for outcome
+progress.
+
+1. When Codex exposes a callable in-conversation visualization capability, create an inline HTML visualization by default and use the capability's official rendering instruction, such as `::codex-inline-vis{file="..."}`.
+2. Mermaid does not satisfy the first layer. Use Mermaid only when inline visualization is unavailable, not callable, cannot write to its required visual directory, or fails to render.
+3. Use fixed Markdown or plain text only when Mermaid is also unavailable.
+4. State the fallback reason in one sentence. Do not silently downgrade, and do not block the project because visualization is unavailable.
+
+Plain-text fallback:
+
+```text
+CER roadmap | live brief
+CER goal: <destination>
+CER scope/exclusions: <in scope / not doing now>
+CER assumptions: <confirmed / safe inference / decision needed>
+CER live brief: confirmed=<...> | safe inference=<...> | decisions needed=<...>
+CER outcome anchor: unfinished=<completion condition> | accepted delta=<outcome difference / none>
+CER current batch freeze: <only what this batch will do>
+CER work lane: <mainline_outcome / diagnostic / mechanism_improvement / governance_self_improvement>
+CER last feedback / change: <... / none>
+[Public alignment: <confirmed / safe inference / decision needed>]
+[✓] Complete -> [● Now] Current stage -> [○] Later stage -> [○] Final delivery / closeout
+Current: <one sentence>
+Smallest observable outcome: <next thing the user will see>
+Acceptance: technical acceptance=<condition / not applicable>; fit check=<condition / not applicable>
+Next checkpoint: <one sentence>
+Knowledge foundation: <confirmed / source missing / not applicable>
+CER roles: C=<state> | E1=<state> | R=<not created / reviewing / complete>
+```
+
+## Role Display Boundary
+
+Roadmaps and lifecycle cards show only formal C, E1, R, and E2 when takeover occurs. Parallel
+candidate producers are C's internal on-demand capability. They do not enter role columns,
+lifecycle cards, user settings, or separate progress displays. Only report missing evidence in
+ordinary risk language when it becomes a material blocker.
+
+## Roadmap Source
+
+Use the highest available authority and do not create a second progress record. The living task
+brief and `outcome_anchor` also derive only from the highest available authority and C-adjudicated facts in this
+cycle; it is not a second plan, fixed document set, or new workflow:
+
+1. If the target project has an authoritative progress source or roadmap, derive from it.
+2. If it has only an accepted plan, derive temporary state from that plan plus verified execution evidence.
+3. If it has no plan, derive temporary state from the current user request and verified role/blocker facts, and label it `initial / pending convergence`.
+
+When `$project-context-workflow` is also in use, read only its accepted plan and progress. Do not repeat its five-step process or create a duplicate consensus gate.
+
+Do not show cards for ordinary implementation detail. Use yellow for material direction or
+deliverable-shape choices, open-eye red for reliability blockers, and open-eye green for
+observable staged results and ordinary final acceptance. Only a proven stop/close terminal state
+uses a closed-eye card. Ordinary batch state does not show a card; update the inline roadmap only
+when the outcome-anchor progress gate is satisfied.