Status: implemented and merged; release authority remains open
Date: 2026-07-11
Document owner: Kalen Howell Sr.
Guide review state: reviewed for source and technical fidelity; business release decisions remain open
Baseline: RH Scheduler v9.346, through merge commit
01d92f0
Audience: Kalen, scheduler owners, planners, developers, and reviewers who do not already know the RH workflow or the codebase
One-Minute Explanation
The scheduler could already produce a schedule, but a planner had limited evidence for understanding one optimizer result versus another. The recent work added a safe review layer around that result and a safer way to build the next features.
The scheduler now saves each successful optimizer result as a candidate, which means a plan under review. A planner can compare the latest candidate with an earlier candidate and see changes in inputs, settings, output, row count, and warnings. Both sides remain clearly labeled candidate — not released.
Two supporting contracts clarify the path forward. The output-authority characterization explains what ten existing scheduler screens actually do today. The owner decision packet asks Mike and Justin to settle the rules that must exist before any plan can become official for the floor.
The team built these slices in three isolated Git worktrees. A new orchestration foundation checked boundaries, evidence, PR identity, review, merge order, and cleanup. This delivery tooling does not change the scheduler's business logic. It makes small changes safer to produce and easier to review.
Business Problem And Value
The problem before this work
When a planner ran the optimizer more than once, the latest schedule replaced what the planner saw. The application did not provide a durable answer to basic review questions:
- Which optimizer run produced this result?
- Did the orders or saved configuration change?
- Did the output itself change?
- Did the schedule gain or lose rows or warning types?
- Is the result only being reviewed, or is it official for production?
The same uncertainty appeared in the broader product. Existing output screens looked similar, but some only displayed schedule state, some performed their own planning, some combined plans with actual work, and some recomputed advisory results. Treating all of them as official output would create hidden conflicts.
The development process also needed a safer way to move several small slices at once. Without explicit ownership, parallel agents could edit the same file, open duplicate PRs, merge stale work, or remove a worktree that still contained important local evidence.
The value after this work
| Value | What changed | Practical benefit |
|---|---|---|
| Better planner understanding | Candidate comparison shows evidence and count deltas | A planner can identify which evidence categories changed and narrow the investigation |
| Clear authority boundary | Every candidate remains visibly nonreleased | Review cannot be mistaken for floor authorization |
| Safer architecture decisions | Ten output surfaces have source-backed classifications | The team knows which screens can become projections and which need redesign |
| Faster owner review | Four release questions are packaged with recommendations and alternatives | Mike and Justin can respond asynchronously without blocking unrelated work |
| Safer feature throughput | Three worktrees had disjoint write sets, tests, reviews, and ordered merges | The team can move several narrow slices without weakening quality gates |
| Better auditability | PR heads, tests, findings, remediation, and merge evidence are recorded | Future reviewers can reconstruct what changed and why |
What success means now
The immediate success measure is not production throughput. It is whether the team can answer the evidence and authority questions above without guessing. The pilot proved that the integrated repository still passed 102 maintained tests and that review found and corrected material issues before merge.
Business Workflow
The business feature begins when a planner runs the optimizer and ends when the planner has reviewable evidence. It does not continue into release.
How to read this view: Blue steps are delivered behavior. Amber diamonds are decisions or boundaries. The workflow saves optimizer evidence, optionally compares it, and stops at review. The future release branch is shown only to make the missing authority visible.
Example in plain language
Assume a planner runs the optimizer at 9:00 and again at 9:15.
- If the orders and settings are the same and the output is the same, the comparison reports no fingerprint change and zero row/warning deltas.
- If one order changes, the input fingerprint changes.
- If any saved field in the current configuration object changes, the configuration fingerprint changes, even if that field does not affect the optimizer result.
- If the result changes, the output fingerprint changes and the planner sees row and warning deltas.
- If the selected prior candidate was removed, the UI shows a specific error and leaves candidate history unchanged.
The comparison tells the planner which evidence categories and counts appear different. It does not identify the exact changed order, setting, or output row; explain the cause; decide whether the change is acceptable; or authorize production to follow it.
How The Four Features Fit Together
1. Orchestration foundation
The foundation is the delivery control layer. It validates a wave manifest, creates only approved worktrees, checks exact branch and path identity, requires test evidence before PR creation, prevents duplicate/stale PR reuse, and refuses ambiguous cleanup.
Business value: more feature work can happen concurrently without losing the evidence and review discipline required for a manufacturing system.
Technical location:
scripts/orchestration-wave.mjs and
scripts/lib/orchestration-wave.mjs, covered by 28 focused
tests.
4. Candidate comparison
The comparison reads two saved PlanCandidate records and reports changes in their input, configuration, and output fingerprints, plus scheduled-row and warning deltas.
Business value: the planner can compare evidence without manually reconstructing two optimizer runs.
Technical location: the comparison functions and UI
live in src/prototype/rh_adhesives_scheduler_0346.html,
with focused tests in
tests/scheduler/plan-candidate-comparison.test.mjs.
System Context And Authority Boundary
How to read this view: Blue is the current browser application. Green is delivered evidence state. Amber represents contracts and open owner decisions. Gray represents development delivery tooling. Red marks future release authority outside the current implementation.
The diagram separates two systems of work:
- Product runtime: the planner uses the browser scheduler and its local candidate history.
- Product delivery: developers use manifests, worktrees, PRs, tests, and reviews to change the repository safely.
The owner packet influences future design, but it is not executable policy. The orchestration foundation controls Git/GitHub actions, but it cannot approve or release a production plan.
Candidate Comparison Runtime
How to read this view: The solid sequence is the successful read-only path. The alternate path covers missing candidates and invalid status. Neither path writes candidate history.
Runtime steps
renderPlanCandidateDetailshows the latest candidate and the available prior IDs.- The planner chooses one prior ID.
readPlanCandidateStorereads the namespaced local candidate record.comparePlanCandidatesverifies both records have the exactcandidate-not-releasedstatus.- The function compares fingerprints and counts rows and warnings by type.
renderPlanCandidateComparisonencodes restored strings before inserting them into HTML and presents two explicit nonrelease labels.
Failure and security behavior
- A missing prior candidate, missing latest candidate, or invalid status has a distinct safe error.
- The UI states that history was not changed.
- Restored IDs, fingerprints, warning types, and option labels are treated as untrusted display values and encoded.
- Warning types such as
__proto__andconstructorare counted with a prototype-free map rather than colliding with JavaScript object properties.
These protections came from PR review. They are examples of why final-SHA review and adversarial tests matter even when initial happy-path tests pass.
What The Existing Outputs Mean
How to read this view: Each group describes current source behavior, not business approval. The red group contains screens whose current behavior mixes more than one authority type. The arrows name the state or action that makes the classification important.
| Classification | Surfaces | Plain meaning |
|---|---|---|
| Projection | Operator Schedule, Pour Schedule, Auto Line Queue | Formats existing mutable schedule state without placing order work |
| Secondary planner | Weekly Plan | Builds its own five-day allocation from open orders |
| Actuals view | Made vs Planned, Performance | Reads shipment, booking, or recorded execution information |
| Advisory view | 5-Day Summary | Recomputes simulation/summary information that is not safe floor instruction |
| Unresolved | Daily Plan, Mix Schedule, Customer Summary | Mixes display, planning, forecast, or actual behavior and needs a named gate |
No surface is currently classified as a released-plan projection. The three unresolved gates are:
- OA-01 Daily Plan: separate display from labor/tank planning rules.
- OA-02 Mix Schedule: decide which batch calculations belong in a candidate and which are later advisory or execution edits.
- OA-03 Customer Summary: separate released commitment, current forecast, completion, and shipment actuals.
How The Parallel Delivery Loop Worked
How to read this view: The fork shows work that can
happen concurrently. The review loop is intentionally repeated until
each exact PR head is ready. Integration becomes sequential because each
later branch must include and revalidate current main.
Responsibility split
| Role | Owns | Does not own |
|---|---|---|
| Root orchestrator | manifest, shared base, PR side effects, merge order, shared tracking, cleanup | feature implementation details inside a worker's declared paths |
| Feature worker | one outcome, exact write set, RED/GREEN evidence, local validation | shared trackers, another worker's files, merge authority |
| Specification reviewer | user outcome, source fidelity, business/authority boundaries | implementation changes |
| Engineering reviewer | correctness, regression, security, test strength, maintainability | implementation changes |
| Kalen | product intent and final merge authority | low-level deterministic checks delegated to the workflow |
Findings the loop caught
The reviews did more than confirm the work:
- global string checks could falsely pass when output behavior moved to the wrong function;
- the owner packet accidentally made an OM-06 acknowledgement decision inside OM-05;
- restored candidate values could inject HTML into the comparison view;
- different comparison errors were flattened into one misleading message;
- warning types matching JavaScript prototype names produced wrong counts;
- the closeout initially claimed final reviews without recording the exact reviewed heads and verdicts in durable evidence.
Each behavior finding received a failing regression before the fix. Final review occurred after integration merges, not only on the original feature commit.
Technical Implementation Map
| Business concept | Implementation | Practical meaning |
|---|---|---|
| Candidate history | readPlanCandidateStore,
persistPlanCandidate |
One browser-local append-only evidence list |
| Candidate identity | createPlanCandidate |
Unique run ID plus deterministic evidence fingerprints |
| Candidate capture | capturePlanCandidate |
Save evidence after a successful legacy optimizer result |
| Warning comparison | countPlanCandidateWarnings |
Count warning types safely, including reserved property names |
| Evidence comparison | comparePlanCandidates |
Compute changes without writing history |
| Visible comparison | renderPlanCandidateComparison |
Present escaped evidence and specific errors |
| Output contract | output-authority-characterization-v9346.md |
Source-backed meaning for ten screens |
| Output drift gate | output-authority-characterization.test.mjs |
Bind each classification to its owning functions and evidence fragments |
| Owner decision boundary | release-authority-owner-decision-packet.md |
Collect authority decisions without claiming approval |
| Worktree contract | validateWaveManifest,
buildWorktreePlan |
Reject invalid, overlapping, or unsafe task definitions |
| PR readiness | assessTaskReadiness,
openTaskPullRequest |
Require exact evidence, branch, base, clean state, and declared writes |
| Cleanup | cleanupMergedTask |
Refuse deletion unless PR/worktree/branch state agrees and is clean |
Data, Security, And Operations
Data ownership and persistence
Candidate history remains in browser-local storage under the
rha_ namespace. The comparison does not create a database,
server API, shared user identity, or cross-browser synchronization. A
changed fingerprint shows that serialized evidence changed. A matching
fingerprint is a compact practical signal, not proof of equality,
because the implementation uses a non-cryptographic 32-bit fingerprint
that can collide. The output snapshot keeps the produced schedule
inspectable, but the fingerprints do not preserve a full copy of every
input.
Security boundary
Backup/restore can introduce strings that did not originate in the
current UI. The comparison therefore treats restored candidate strings
as untrusted. The new encoding tests are narrow protection for this
view, not a claim that every innerHTML surface in v9.346
has completed security review.
Operational boundary
The current scheduler has no server-enforced authentication, authorization, release transaction, immutable current-plan pointer, or shared audit log. The NFR assessment and owner packet describe those future needs. They do not make the local prototype production-ready.
Delivery operations
The orchestration CLI uses local Git and GitHub CLI through argv-based process calls. Execute paths recheck canonical worktree identity, clean registered base state, exact branch/PR heads, declared writes, evidence, and merge state. Dry run is the default.
Decisions, Risks, And Open Questions
Decisions already made
- Optimizer results are called candidates because they are under review.
- Candidate evidence is append-only and visibly nonreleased.
- The existing
scheduledresult remains in place; traceability and comparison are additive. - Only one parallel lane may edit the prototype core in a wave.
- Shared trackers and merge side effects stay with the root orchestrator.
- Final review must use the exact head that will be merged.
Owner decisions still open
- OM-01: planning period and cutoff.
- OM-03: which warnings block release or may be reviewed.
- OM-04: routine release and exception authority.
- OM-05: current-plan identity and replacement notice.
- OM-06 remains separate: who acknowledges changed assignments and whether acknowledgement gates execution.
Known risks and limits
- Candidate history is local to one browser profile.
- Fingerprints show difference, not business reason or acceptability.
- Output classifications can drift when prototype functions change; the tests detect named changes but still require human interpretation.
- The orchestration helper exposed an operator constraint: cleanup must run from the registered controller, not from the worktree being removed.
- The current feature guide describes merged behavior on 2026-07-11. Future slices must update it when the business meaning or architecture changes.
Verification Evidence
The final pilot evidence recorded:
- 85 tests passed in each untouched pilot worktree before delegation;
- 28 focused orchestration foundation tests;
- focused RED/GREEN tests for each feature and remediation;
- 102 tests passed in the final integrated selection;
- scheduler script extraction and syntax checks;
- Markdown and command-center validation;
- isolated browser checks for comparison, reload, missing history, malicious restored values, and reserved warning names;
- CI success and two local read-only reviewer verdicts on each final PR head;
- no unresolved GitHub review threads before merge.
Primary receipt:
docs/agentic-engineering-framework/07-evidence/parallel-slice-pilot-closeout.md.
Glossary
| Term | Plain meaning |
|---|---|
| Candidate / PlanCandidate | A saved optimizer result under review; not official for production |
| Fingerprint | A deterministic hash-like identifier used to detect whether a category of evidence changed |
| Configuration | The current full saved cfg object; its fingerprint may
change for fields that do not affect optimization |
| Output fingerprint | A compact signal used to detect changed schedule content; a match is not cryptographic proof of equality |
| Warning delta | Difference in warning count, including changes by warning type |
| Projection | A screen that formats existing plan/schedule state without placing work |
| Secondary planner | A screen that independently allocates work rather than only displaying one plan |
| Actuals | Recorded work, shipment, quantity, or time that occurred |
| Advisory | Useful forecast or simulation that is not authoritative instruction |
| Release | A future controlled action that makes one reviewed plan official |
| Current-plan pointer | A future single reference that tells every user which released plan is in force |
| Worktree | A separate checked-out working directory connected to the same Git repository |
| Manifest | The root-owned declaration of task IDs, branches, paths, commands, and boundaries |
| RED/GREEN | First prove a focused test fails because behavior is absent, then implement until it passes |
| Exact-SHA review | Review of the precise commit that will be merged, including integration commits |
Source Trail
Product and architecture
docs/agentic-engineering-framework/05-decisions/2026-07-11-optimizer-result-traceability.mddocs/architecture/output-authority-characterization-v9346.mddocs/acceptance/release-authority-owner-decision-packet.mddocs/architecture/research/2026-07-11-non-functional-requirements-assessment.md
Implementation and tests
src/prototype/rh_adhesives_scheduler_0346.htmltests/scheduler/plan-candidate-traceability.test.mjstests/scheduler/plan-candidate-comparison.test.mjstests/scheduler/output-authority-characterization.test.mjstests/artifacts/release-authority-decision-packet.test.mjsscripts/lib/orchestration-wave.mjstests/orchestration/orchestration-wave.test.mjs
Delivery evidence
docs/plans/2026-07-11-parallel-slice-delivery-execplan.mddocs/agentic-engineering-framework/07-evidence/parallel-slice-pilot-closeout.md- PRs #6 through #10 and their merge commits listed in the closeout receipt
Documentation practice research
Maintenance Note
Update this guide and its diagrams when a slice changes candidate
fields, comparison behavior, output classification, owner decisions,
release/current plan authority, persistence boundaries, security
behavior, or the parallel delivery contract. Run the renderer and
--check in the same PR.
For a new material feature, use
docs/features/templates/feature-guide-template.md and
follow docs/runbooks/feature-guide-authoring.md.