Document the committed program and its fixed operands in the README

[dmccoystephenson]

Summary

This cycle was devoted to a documentation-accuracy sweep, since every open issue is blocked on either an owner design decision or an LC-3 toolchain that is not installed in this environment.

• README.md gains a What is committed section describing the two blocks that are actually in src/multiplyTwoNumbers.asm: TESTCODE: (clears R1 and R2, then loads 5 and 6) and MULTIPLY: (clears R0, then adds R1 into R0 and decrements R2 each pass, branching back to AGAIN).
• The drift between the README's opening sentence and the committed source is disclosed rather than resolved. That the operands are fixed at 5 and 6 by TESTCODE: is now stated plainly, alongside the header comment's caller-supplied contract, and the note records that which of the two is intended has not been decided. Deciding it is reserved for the repository owner and is tracked in TESTCODE: overwrites the caller-supplied operands the header comment and README document #2 — nothing in this diff picks a side.
• A short Building and running section records that no LC-3 assembler or simulator is named by this repository yet. Naming one that was never run was deliberately avoided.
• src/multiplyTwoNumbers.asm is not touched. No toolchain is named, no command is claimed to have been run, and no register value is asserted anywhere in the diff.

No Closes #N reference is included. Issue #5 is partially advanced — the hardcoded operands it asks to have disclosed are now disclosed — but the build and run commands it asks for cannot be written honestly here, so it is left open.

Test plan

UNVERIFIED — not applicable. No LC-3 assembler or simulator exists in this environment (which lc3as lc3sim lc3convert complx lc3tools lc3 exits 1 with no output), so the syntax and behavior gates could not be run. Per this loop's scope gate that is acceptable for this PR specifically, because the diff touches only README.md, contains no commands, and asserts no register values.

• git diff --stat reports README.md | 13 +++++++++++++, 1 file changed, 13 insertions(+) — the two pre-existing README lines are untouched and src/multiplyTwoNumbers.asm is not in the diff, so no CRLF renormalization was possible.
• git diff --check reports nothing.
• git status --porcelain shows no assembler artifact, no simulator script, and no .claude/ entry staged.
• Every statement added to the README was checked against the source by line number: .ORIG x3000 (line 5), TESTCODE: (line 7), MULTIPLY: (line 13), AGAIN (line 15), BRp AGAIN (line 17), HALT (line 19).
• Assemble and simulate — not run, no toolchain.

Issues deferred this cycle, with reasons

• TESTCODE: overwrites the caller-supplied operands the header comment and README document #2 (TESTCODE: overwrites the caller-supplied operands) — the choice between a caller-supplied contract and a self-contained 5 x 6 demonstration is a design decision reserved for the owner. This PR documents the disagreement without resolving it.
• README documents nothing operational: no toolchain, no build or run command, no mention of the hardcoded operands #5 (README documents nothing operational) — partially advanced as described above; the remainder is blocked on the owner's choice of LC-3 toolchain, because every command and register value it asks for must come from a real run.
• Multiply loop tests after its body, so a zero or negative R2 is expected to yield a wrong product #6 (do-while loop and a zero or negative R2) — downstream of TESTCODE: overwrites the caller-supplied operands the header comment and README document #2, and unfixable without simulator runs at R2 = 0, R2 = 1, and a negative R2, none of which can be produced here.
• R2 is clobbered by the multiply loop and no documentation says so #7 (R2 is clobbered without documentation) — also downstream of TESTCODE: overwrites the caller-supplied operands the header comment and README document #2; the post-HALT value that would be documented cannot be observed without a simulator.

Issue #1 was closed during triage, having been resolved by the merged PR #9 but left open.

---

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

drafted by Claude on behalf of Daniel Stephenson

[dmccoystephenson]

Self-review

Posted as a plain comment rather than as a review object; independent review is not implied.

Rubric

• Scope: PASS — git diff --name-only origin/master...HEAD lists README.md alone. No formatting churn, no rename, no .asm change.
• Tests-new: PASS (vacuous) — no behavioral change is made, so no assemble-and-run command is owed. Every added statement is a positional fact about the source, each checked against a line number: .ORIG x3000 (5), TESTCODE: (7), MULTIPLY: (13), AGAIN (15), BRp AGAIN (17), HALT (19).
• Tests-fix: not applicable — no bug is fixed by this diff.
• Assembled, not read: PASS after two corrections. The first draft was scored FAIL on this item and amended in 5be87f4: while R2 remains positive was replaced, because it described a loop-trip property that only a simulator run could establish and it framed a body-before-test loop as a while-loop, which is exactly the behavior open issue Multiply loop tests after its body, so a zero or negative R2 is expected to yield a wrong product #6 disputes and this cycle cannot verify. The wording now records the source order only. the result is read out of R0 once the program halts was likewise attributed to the header comment rather than asserted as an observed outcome.
• Register values are observed, not asserted: PASS — no register value appears anywhere in the diff. The numerals 5 and 6 are quoted from the ADD immediates on lines 10 and 11, not from a run.
• CRLF preserved: PASS — src/multiplyTwoNumbers.asm is not in the diff at all, so no renormalization was possible. git diff --check reports nothing.
• Contract coherence: PARTIAL, stated deliberately. The header comment, the README sentence, the GitHub repository description, and the code do not agree, and this PR does not make them agree — it discloses the disagreement and names it as undecided. Resolving it is reserved for the owner under TESTCODE: overwrites the caller-supplied operands the header comment and README document #2. The repository description is not a tracked file and was not edited.
• Entry and exit intact: PASS — no source file is modified.
• Operand legality / timeout on every run / toolchain probe present / no new toolchain: PASS (vacuous) — no immediate, no simulator invocation, no script, and no workflow is added by this diff.
• No artifacts committed: PASS — git status --porcelain is clean; no .obj, .sym, .bin, .hex, simulator script, or .claude/ entry is present.
• Issue resolution: PASS — no Closes #N is claimed. README documents nothing operational: no toolchain, no build or run command, no mention of the hardcoded operands #5 is advanced only in part and is deliberately left open.
• Manual validation: UNVERIFIED, scope-gated. which lc3as lc3sim lc3convert complx lc3tools lc3 exits 1 with no output, so no assembler or simulator exists here. The gate is waived for this PR only because the diff is documentation containing no commands and no claimed register values. Any future PR touching src/multiplyTwoNumbers.asm must not take this waiver.

Findings folded in from the file, since both fall outside the current diff hunks

• README.md:2 — the original one-line description ("multiplies the R1 and R2 registers") remains unchanged and is still contradicted by TESTCODE:. It is left as-is on purpose: rewriting it would pick a side in TESTCODE: overwrites the caller-supplied operands the header comment and README document #2. The new section below it supplies the qualification a reader needs in the meantime.
• src/multiplyTwoNumbers.asm:2 — the header comment pre execution we have num1 in R1 and num2 in R2 is now quoted verbatim by the README, so the two documents will drift together rather than apart if the contract is later settled. Should TESTCODE: overwrites the caller-supplied operands the header comment and README document #2 be resolved in favor of the code, both lines and the repository description need changing in the same pass.

Summary: a documentation-only cycle that records what the committed file contains and discloses the fixed 5-and-6 operands, without resolving the contract question or naming a toolchain nobody ran. Merging is a human decision; behavior remains unverified in this environment, as it was for PR #9.

---

This comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

drafted by Claude on behalf of Daniel Stephenson