sharukhan phase-1: author the PRD - #320
Open
dcasota wants to merge 4 commits into
Open
Conversation
15 requirements and 15 acceptance criteria, each AC naming the task that will verify it, following the in-repo practice of using the AC table as the traceability matrix. Scope is drawn tightly: sharukhan orchestrates the existing Photon build scripts rather than replacing them, and every SPAGAT-Librarian concern (operator-config medium, iso-phase6, SPAGAT_*/IPHASE6_*) is explicitly out, as the maintainer scoped it. The purpose section states the three observed defects that motivate a rewrite rather than more shell: inputs that resolve implicitly (two downstream patch copies drifted 78 lines and 8-vs-27 files apart, and the build used whichever sat beside the invoked script), checks that cannot fail (40-check-staging.sh never exits non-zero), and verdicts that can be silently vacuous (toybox grep has no -a and returns zero matches on a NUL-bearing serial log). Section 8 records five defects found while inventorying the predecessor tooling, so they are requirements by implication rather than inherited bugs: mc-run.sh loses its counters to a subshell and always tallies zero; mc-verify.sh hardcodes -prebuilt when locating a cached ISO; the static address scheme is computed but never applied, so every guest takes a DHCP lease; nine config variables are declared and never read, and MC_MAC_PREFIX contradicts the OUI actually used; and the serial-growth liveness instrument was lost in translation from vm-lab, with the log truncated rather than offset-bounded. Signed-off-by: Daniel Casota <dcasota@gmail.com>
The database is the system of record; MEMORY.md is a view over it, stating which database it rendered from and when, so a stale render is visible rather than silently authoritative. Editing MEMORY.md changes nothing. Schema: run, permutation, check_result, artifact, finding, job, plus two views. v_permutation_report backs both the CLI report and MEMORY.md so the two cannot drift. v_control_integrity exists because a run whose negative controls passed proves nothing - it must read as inconclusive, not as green. check_result.pr is what turns a failure into 'PR#22 regressed' rather than 'something broke'. check_result.is_control marks the negative controls. Seeded with 18 findings from bringing the shell harness up on this host: 6 hypervisor, 5 defect, 3 portability, 2 build, 2 tooling. Seventeen are verified; one is an open blocker - the Photon ISO's grub.cfg carries no console=ttyS0, so the kernel never writes to the serial port and the boot-source-transition oracle can never fire. VMware Tools is not running during install either, so getGuestIPAddress and captureScreen are both unavailable, which leaves the install phase unobservable. Notable verified entries: vmxnet3 cannot reserve a PCI slot in this VMX layout and VMware reports only 'The operation was canceled'; an ISO on a WSL-only path is invisible to VMware; toybox grep has no -a and returns zero matches on a NUL-bearing log; a cksum-based permutation index collided on this very matrix; and editing a shell script while it runs corrupts execution mid-flight. The renderer is Python only until 'sharukhan db render' lands (Task 013); the SQL is identical either way. Signed-off-by: Daniel Casota <dcasota@gmail.com>
Measurement on this host contradicts PRD section 7. The claim that parallelism 'is not a future optimisation; it is incorrect' holds for ISO builds, which mutate a shared 65 GiB staging tree, and is false for VM installs, which share nothing - each permutation owns its VM directory, disk, MAC, UUID and results. Measured: .vmem is exactly memSize (4294967296 bytes) and exists only while the VM runs; the thin .vmdk grew 4 MiB to 914 MiB during one install. On 14 CPUs, 23 GiB RAM and 131 GiB free, the slot counts are CPU 3, RAM 4, disk 8 - so RAM binds, not CPU. A concurrency limit derived from CPU count alone would over-commit on a smaller host. Recorded as a finding with its resolution rather than silently editing the PRD, which is what the methodology prescribes when implementation disproves a spec assumption. Signed-off-by: Daniel Casota <dcasota@gmail.com>
REQ-16 and AC-16: every log and report is stamped with a UTC timestamp in its filename, with a 'latest' pointer for convenience. This is a live defect in the shell prototype, not only a future requirement. mc-verify.sh truncated a fixed checks.jsonl on every invocation and harvested guest logs to fixed filenames, so k01 was run five times and only the last run's evidence survived - lost exactly when comparing two runs is what would explain a regression. Prototype now writes checks-<UTC>.jsonl, logs-<UTC>/ and report-<UTC>.txt, each with a -latest symlink, sharing one stamp per run exported to every child. Verified: two consecutive report runs produced two distinct files with latest repointed. Memory database is at 27 findings, all verified, no open blockers. New this round: vmrun start silently does nothing from a setsid-detached process (nohup is fine, setsid is not), which made a background run look like a slow install rather than one that never started. Signed-off-by: Daniel Casota <dcasota@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Phase 1. Stacked on #319 (phase 0) so the diff shows only the PRD.
15 requirements, 15 acceptance criteria, each AC naming the task that will verify it — the AC table is the traceability matrix, following the in-repo practice in
tdnf-depgraph.Scope, drawn tightly
sharukhanorchestrates the existing Photon build scripts; it does not replace them. Every SPAGAT-Librarian concern is explicitly out of scope — theoperator-config.vmdkcredential medium,iso-phase6,SPAGAT_*/IPHASE6_*— as you scoped it. Also out: other hypervisors, remote execution, and replacingISO-PERMUTATION-MATRIX.mdas the analytical document.Why a rewrite rather than more shell
Three observed defects, not hypothesised ones:
downstream-fixes.patchcopies had drifted 78 lines and 8-vs-27 files apart, and the build used whichever sat beside the invoked script. It surfaced aspatch does not applyagainst a spec, which reads like a rebase problem; it cost two builds and two wrong diagnoses.40-check-staging.shnever exits non-zero.grephas no-aand returns zero matches on a NUL-bearing serial log; interactively the same name isugrep.§8 — defects in my own predecessor code, recorded as requirements
The feature inventory turned up five things in
mission-controlthat must not survive into the tool. I would rather write them down than quietly not port them:mc-run.shaccumulates pass/fail counters inside awhile readfed by a pipe, so the subshell discards them and the final tally is always zeromc-verify.shlocates a cached ISO as…-prebuilt, silently ignoring the canister mode it was actually built with--ipis never passed to the kickstart generator, so every guest takes a DHCP lease. The documented "static below the DHCP floor" property was never in effectMC_MAC_PREFIXcontradicts the OUI actually usedvm-lab, and the log is truncated rather than offset-bounded, discarding prior-boot evidenceConstraints that are design facts, not preferences
Sequential execution is correctness, not a missing optimisation — every ISO build shares one staging tree and the Windows volume is space-constrained. The host runs other people's VMs, so no operation may touch a VM it did not create. Sixteen permutations cannot be automated, because the STIG menu exists only in the curses configurator. UEFI ignores
bios.bootOrder— NVRAM decides, so it must be stashed between installs.Next: Phase 2 is a Dev Lead feasibility review recorded as a review on this PR (no separate file), then Phase 3 ADRs.