docs(initializer): verify the generated-project figure/reference authoring workflow

Completed verification

Verified that an agent can use generated/package documentation and documented public APIs to author a calculation with a figure, complete independent numerical references and local HTML/PDF reports from a fresh external project.

Category: enhancement
Triage: ready-for-agent
Status: completed

Documentation already present

At main f28c96d:

Generated authoring guidance includes figure imports, a complete figure call, directory containment, caption and alt text.
Generated reference guidance includes a complete independently derived rectangle case, binding metadata, executable verification commands, report registration, unmatched outcomes and reviewed rebinding.
Windows installed checks execute the rectangle binding recipe.

Do not repeat the completed documentation expansion. Repair concrete documentation gaps only when the remaining verification exposes them.

Verification coverage

The installed initializer acceptance now follows the packaged composed-report/figure recipe with complete independently established intermediate and output expectations. Its separate reference qualification proves matching, wrong and unmatched cases, formula/text invalidation, explicit reviewed rebinding, browser edits, output-only curl and same-run HTML/PDF/evidence. The maintained two-panel case remains a separate runtime-integration check.

The 1 November audit gap is resolved. The isolated triangle trial was completed on 6 November using the version-matched artifacts from #73, with no implementation inspection or monorepo access. The full trial record retains the brief, independent basis, package/host versions, commands, results and exact artifact hashes.

Acceptance criteria

Extend the existing external installed-consumer acceptance with a small synthetic calculation containing a valid figure and independently established expected values for calculated intermediates and outputs. Follow the shipped recipe through documented public APIs. Do not infer contracts from implementation files or copy canonical engineering examples.
Prove correct matching references pass, a deliberately wrong matching value fails, and unmatched inputs remain pending/not applicable.
Prove a source edit, including a text-only edit, invalidates matching and requires an explicit reviewed rebind. Preserve expected values unless their independent derivation changes.
Check editable browser inputs, output-only curl and same-run HTML/PDF with that reference setup. Inspect all delivered PDF pages and record automated results, visual review and engineering approval separately.
Repeat an agent authoring trial using the triangle brief and independently established symmetric/asymmetric expectations. Allow generated/package documentation, documented public APIs and engineering references. Exclude implementation-source inspection, prior solutions and the local monorepo.
Record package versions, brief, independent basis, commands, results and unresolved documentation questions for the trial. Keep automated consumer evidence separate from the agent-trial evidence.

Completion evidence

PR #125, merged as 2943192a5bab0c802e46c7288837ede07f03b1a8, delivers the maintained acceptance. Its final combined-head CI run covers quality, isolation, installed packages and both native PowerShell shells. Dependency review, PR title and CodeQL also pass.
The automated consumer passes 16 CLI reference scenarios and both matching/unmatched browser cases. The separate documentation-only trial passes 18 CLI scenarios and complete three-symbol references for both asymmetric and symmetric triangle cases.
Browser/curl values and retained source/input/reference bindings agree. HTML and PDF hashes match the same captured run. Every page of both triangle PDFs and both new acceptance PDFs was visually inspected, with no missing content, unreadable notation or clipping found.
The intentionally wrong matching value fails as required. Unmatched inputs and stale bindings remain pending/not applicable. Reviewed formula/text rebinding preserves the independently derived expectations.
Automatic evidence keeps its visualInspection field pending. Separate exact-hash visual review records contain the completed agent inspections. Human engineering approval is NOT SUPPLIED. Registry publication is outside this verification.
No blocking documentation questions remain. The trial comment retains original artifact provenance separately from the maintained current-main acceptance.

Ownership and dependencies

#73 owns shared authoring-guide ownership, version-matched distribution, installed link integrity and release synchronization. Those changes are outside this issue. The completed documentation-only trial used the version-matched artifacts delivered by #73.

This issue owns verification of the figure/reference recipe and the authoring trial. No new CLI commands, agent runtime, broader input validation, deployment or registry publication is implied.

Historical context

The original 27 September 2026 public-package triangle trial succeeded, but the agent inspected installed implementation files to resolve authoring questions. That established documentation friction, not that every inspection was necessary. The remaining trial must establish the workflow using its permitted documented interfaces.

The isolated documentation-only triangle trial is now complete, including full reference coverage, negative/stale-binding cases, live browser/curl, same-run HTML/PDF and every-page visual review. No implementation sources or monorepo solutions were inspected by the trial agent. The maintained installed-consumer acceptance also passes locally; its PR and required checks are the remaining delivery step before closure.

The full trial record follows so its provenance, commands, results and exact artifact hashes remain available in this issue. Automated checks, agent visual review and human engineering approval are recorded separately. Engineering approval is NOT SUPPLIED.

Complete isolated triangle trial evidence, 6 November 2026

Installed authoring trial: issues #73 and #70

Updated 2026-11-06. Exact scaffold root: /private/var/folders/7h/rrzd96pd01dcj8tf0crkzzn00000gn/T/cso-73-doc-trial-c5wgt_nn/triangle-report.

The retained documentation-only calculation trial now completes its reference, live browser and PDF qualifications. The original HTML-only #73 record is preserved in output/qualification/trial-evidence-73-original.md. This continuation supplies isolated consumer evidence for #70; the parent owns maintained acceptance, PR review and issue closure.

No implementation files in node_modules, the Python venv or the monorepo were inspected. No other agents' solutions were read. All authored work stayed in this scaffold. No packages were installed, replaced or upgraded. Public CLI, generated documentation, package metadata and public Playwright/browser APIs were used. The PDF skill was read as an explicit workflow exception; no implementation source was read through it.

Original installed artifact provenance

The parent supplied its retained original provisioning record: these 1.0.0 artifacts were built from #73 revision 6847978, with no registry publication. They are distinct from current-main synthetic acceptance artifacts. The project was created with node <extracted create-cs-object archive>/dist/cli.js triangle-report --skip-install, followed by explicit npm archive installs and node scripts/setup.ts using wheel find-links. The original archive directory was /private/var/folders/7h/rrzd96pd01dcj8tf0crkzzn00000gn/T/cso installed packages initializer VALvAs/archives. This agent did not inspect that external directory.

Original artifact	Parent-retained SHA-256
wheel	`02437ce6219ce2a4999b41e4171d2cec906583b02260547788b83a6d7308fd8b`
initializer	`196f349296dbdb11a018da4366d71df875731e812adf960d2069aebeb99d80f2`
cli	`a914b1d7b1f27c517a8636ab9d461f8d925fc7006a8d0fe838efe6b2fe5145ce`
core	`e5e63ca0127232a67540409e89068a5171c75f34f7077d397757aa5de207be85`
react	`95c1e36a1b0e177223ba64db2ab3eb40b2407f252027b13d2ec5fe85c483e7e4`

output/qualification/original-artifact-provenance.json preserves that record plus this scaffold's generated lock metadata for the three npm packages. Public npm ls and Python package metadata report @cs-object/cli, @cs-object/core, @cs-object/react and cs-object version 1.0.0. Host: macOS 15.6.1 (24G90), Darwin arm64; Node v24.19.0, npm 11.17.0, Python 3.14.3; browser Chromium 156.0.8078.4. No package source inspection is implied by metadata collection.

Read files and independently established brief

Read the generated AGENTS.md, README.md, authoring.md, authoring-contract.md, original brief.md, shipped references/README.md including its complete reference recipe, reports.json and package.json. Read relevant contract sections for shared aliases, child handles, forwarded outputs, notation, figures and verification. The original session's reference recipe was used for this continuation. Subsequent reads were this agent's own authored sources, retained evidence, generated package-lock metadata and public CLI help. Read the applicable pdf:pdf skill and used runtime dependency discovery to find its marker and available Poppler tools.

The child calculates one planar right triangle's area and hypotenuse from base and perpendicular height in metres. The parent invokes the child once, returns its two results and calculates the total area for two identical, non-overlapping triangles. Positive finite legs and an exact right angle are assumptions. Positive ranges are not automatically enforced; no structural/design-code acceptance is claimed.

The independently stated expectations predate execution:

Base (m)	Perpendicular height (m)	Child area (m^2)	Child hypotenuse (m)	Parent total (m^2)
3	4	6	5	12
6	6	18	sqrt(72)	36

These follow elementary area and Pythagorean relations. The expected hypotenuse for the symmetric case was evaluated independently with 50-digit Decimal square root, not copied from execution. Its binary64 reference value is 8.48528137423857; comparison with the 50-digit independent value differs by about 2.93e-16 m.

Authored calculation: calculations/quantities.py, calculations/triangle.cso.py, calculations/report.cso.py, calculations/assets/triangle.svg. Qualified symbols are b_tri, h_tri, c_tri, A_tri and A_pair, with meanings explained in the report. The figure is schematic, includes perpendicular-leg and hypotenuse labels and a right-angle marker, and has a caption and descriptive alt text. The generated report includes every input, unit, assumption, child formula, substitution and result, followed by the parent total.

Complete bound references and negative checks

references/triangle-reference.json contains two revision-3 cases with independently established expectations for every calculated symbol: child area, child hypotenuse and parent total, with exact units. Bindings use the reference recipe's entry module ID, entry source hash, source closure hash, function, resolved inputs and numeric kinds. reports.json registers triangle-pair, its calculate entry and the reference file.

The qualification script saved original sources, every CLI report, each reference revision and all commands/exit codes. It changed the parent's multiplication from 2.0 * single_triangle["area"] to single_triangle["area"] * 2.0, reviewed this equivalent formula, and explicitly rebound both cases as revision 2. It then added the clarification "Legs are measured along their edges.", reviewed that text-only change and explicitly rebound both cases as revision 3. Assertions prove all independent expected entries were preserved across revisions 1, 2 and 3.

CLI run	Exit	Independent reference status
baseline-3-4	0	not_applicable
baseline-6-6	0	not_applicable
matching-original-3-4	0	passed
matching-original-6-6	0	passed
wrong-matching-value	1	failed
unmatched-inputs	0	not_applicable
formula-stale-3-4	0	not_applicable
formula-stale-6-6	0	not_applicable
formula-reviewed-3-4	0	not_applicable
formula-reviewed-6-6	0	not_applicable
formula-rebound-3-4	0	passed
formula-rebound-6-6	0	passed
text-stale-3-4	0	not_applicable
text-stale-6-6	0	not_applicable
text-reviewed-3-4	0	not_applicable
text-reviewed-6-6	0	not_applicable
final-matching-3-4	0	passed
final-matching-6-6	0	passed

The wrong matching child-area expectation was deliberately changed from 6 to 7 in a separate negative fixture. Its failure produced REFERENCE_FORMULA_MISMATCH and REFERENCE_RUNTIME_MISMATCH with child source location and call chain. That intentional failure is a successful negative test, not an unresolved defect. Unmatched inputs and stale source bindings correctly remain not_applicable, rather than passing. Both final matching cases pass exactly 3/3 distinct calculated symbols. Source consistency also passes with 2/2 input checks, 3/3 formulas and 5/5 public-output observations.

Final entry source SHA-256: 5b7f268f8973ce7ff2cf709ee90bc281368c255a227a2dba0c1e8e2f09b2b19a. Final reference SHA-256: c3d629e91ee8c1ce6dd63a450b6603747f0b5b3aa4bb47d43dcc28f28b30ae72. Final source closure SHA-256: 6af671a73e54e2b65badb81b5d8cf00eb7e8788e1010593fd7445d239591f3da.

Live app, output-only API and same-run artifacts

Started the actual generated app with npm run dev -- --port 0; it selected http://127.0.0.1:60640. Playwright waited for the initial report, opened Inputs, edited both generated fields to 6 and 6, calculated, then edited to 3 and 4 and calculated. Both cases showed source-to-document Passed and independent reference Passed. Actual PDF button downloads succeeded for both cases; afterwards the UI showed PDF layout Passed and human inspection WIP. The script captured each run's HTML and evidence links, downloaded both, and saved the app response and screenshots. No browser page errors were observed.

The symmetric captured run is 5efe0d36-bd89-4687-a6bd-f6668e7419fa; the asymmetric captured run is f8f00f60-0d81-48c4-af12-5393a8ec7ae2. Each downloaded evidence JSON contains that exact run ID, the final reference bytes/hash, matching source/input bindings and hashes of its HTML and PDF. Assertions independently recomputed all hashes, checked every binding and compared all outputs against the pre-established values. Changing subsequent browser inputs did not change the earlier captured HTML hashes.

The unmatched browser case (2,5) returned independent reference not_applicable; the app displayed Independent reference WIP. This remains pending, not passed. Source consistency passed independently. The app does not turn an unmatched reference into engineering approval.

Output-only curl results have exactly three public keys and no verification envelope: (3,4) returns {"triangle_area":6,"hypotenuse":5,"total_area":12}; (6,6) returns {"triangle_area":18,"hypotenuse":8.48528137423857,"total_area":36}. Both responses were compared with the captured execution and independent expectations.

PDF and HTML visual review

Applied pdf:pdf. Its marker ran successfully exactly once before the first attempted PDF creation, with --operation-kind create --expected-output-count 2 --output-format pdf. The initial browser harness incorrectly expected HTTP 200 for run creation; the API correctly returned 201. The harness was corrected to accept successful 2xx responses before any PDF was created, then passed. This was a harness correction, not a product failure.

Both same-run PDFs are one A4 page (595.92 by 842.88 pt). pdfinfo results and pdftotext -layout output are retained. Poppler rendered every page at 110 dpi. Each complete page image was opened and visually reviewed: header, inputs and units, all assumptions, the figure and caption, child area and hypotenuse derivations/substitutions, parent total and footer are intact and readable. No missing glyphs, clipping, overlaps or pagination defect was observed. The 6x6 hypotenuse is displayed as 8.49 m with the symbolic radical and numerical substitution intact.

Clean screenshots of the exact captured HTML links were also opened and inspected at 1280px width. Both have no horizontal overflow, all figure assets loaded at 440x260, and the alt text is retained. These clean same-run screenshots are same-run-html-3-4.png and same-run-html-6-6.png; earlier iframe screenshots include the open input drawer and are not the clean visual-review evidence.

Automated evidence deliberately retains visualInspection: pending. The separate agent visual-review record is passed; no stored automatic status was modified to claim human inspection or engineering approval.

Commands and reproduction

All commands ran from the exact root above. The reference qualification script records every invoked CLI argument, exit code and diagnostic in reference-check-summary.json. It is a sequential trial starting from the original source; to repeat that full mutation sequence, first restore the retained report-original.cso.py.txt to calculations/report.cso.py. The checked final reference and artifacts correspond to the final reviewed source, not that starting snapshot.

.venv/bin/python output/qualification/reference-qualification.py
.venv/bin/python -m cso_python bindings calculations --check
npm run build
npm run dev -- --port 0
node output/qualification/browser-qualification.mjs
curl --fail-with-body http://127.0.0.1:60640/api/reports/triangle-pair/calculate -H 'Content-Type: application/json' -d '{"inputs":{"base":3,"height":4}}' -o output/qualification/curl-output-3-4.json
curl --fail-with-body http://127.0.0.1:60640/api/reports/triangle-pair/calculate -H 'Content-Type: application/json' -d '{"inputs":{"base":6,"height":6}}' -o output/qualification/curl-output-6-6.json
pdfinfo output/pdf/triangle-3-4-same-run.pdf
pdfinfo output/pdf/triangle-6-6-same-run.pdf
pdftoppm -r 110 -png output/pdf/triangle-3-4-same-run.pdf output/qualification/pdf-3-4-page
pdftoppm -r 110 -png output/pdf/triangle-6-6-same-run.pdf output/qualification/pdf-6-6-page
pdftotext -layout output/pdf/triangle-3-4-same-run.pdf output/qualification/pdf-3-4-text.txt
pdftotext -layout output/pdf/triangle-6-6-same-run.pdf output/qualification/pdf-6-6-text.txt
.venv/bin/python output/qualification/assert-artifacts.py

The PDF marker command was node /Users/viktar/.codex/plugins/cache/openai-primary-runtime/pdf/26.1030.10813/skills/pdf/container_tools/mark_artifact_operation_started.mjs --operation-kind create --expected-output-count 2 --output-format pdf. Public Node scripts and shell/browser inspection commands are described above; the complete retained browser authoring script is output/qualification/browser-qualification.mjs.

The final bindings check passes with no stale files. npm run build passes; Vite emitted a non-fatal large-chunk warning. No package upgrade was performed to alter that behavior.

Actual statuses, kept separate

Judgment	Status	Evidence / limit
Source-to-document consistency	Passed, both final matching cases	Final CLI reports and same-run evidence
Independent numerical comparison	Passed, all six values	Decimal independent basis; `artifact-assertions.json`
Complete bound independent reference	Passed, 3/3 symbols per case	Final CLI and live run evidence
Wrong matching expectation	Expected failure proved	Exit 1 and two reference mismatch diagnostics
Unmatched input/reference	Pending correctly	CLI `not_applicable`; browser WIP
Formula/text binding invalidation	Passed	Both cases lose match after each edit
Explicit reviewed rebinding	Passed	Preserved independent expected entries, revisions 2/3
Live browser input editing	Passed	Both matching cases and unmatched case exercised
Output-only curl	Passed, both cases	Exactly declared public values
Same-run HTML/PDF/evidence retention	Passed	IDs, source/input/reference bindings and artifact hashes asserted
Automatic document retention/rendering	Passed, both cases	Downloaded evidence checks
Agent visual HTML review	Passed, both reports	Clean screenshots opened and inspected
Agent visual PDF review	Passed, every page	One page each, both Poppler page images opened and inspected
Automatic visualInspection field	Pending by design	Preserved verbatim in evidence
Human engineering approval	NOT SUPPLIED	No automated or agent visual check claims approval

No blocking documentation gaps or unresolved product failures were encountered in the isolated continuation. The shipped guide and public responses supplied the reference and download information needed. The starter recipe was adapted to include child symbols and both independently derived cases. The observed WIP label is recorded as pending, not passed. Broader issue acceptance and closure are the parent's responsibility.

Exact artifact paths and hashes

All following paths are under /private/var/folders/7h/rrzd96pd01dcj8tf0crkzzn00000gn/T/cso-73-doc-trial-c5wgt_nn/triangle-report. These final artifacts supersede the earlier unbound #73 HTML-only artifacts for this continuation.

Case	Artifact	Relative path	SHA-256
6-6	html	`output/qualification/triangle-6-6-same-run.html`	`2a049c0b4343de6314fe879ca50f1ab4d55af012c2df1936cc2cdf5d101cc303`
6-6	evidence	`output/qualification/triangle-6-6-same-run.evidence.json`	`fab077c4d3ee089fd3facb66e46236aa6d79041f4ac3faf01a92a99d914b8c7c`
6-6	pdf	`output/pdf/triangle-6-6-same-run.pdf`	`ad3aa9eb3fe67f9378f7af283cb5436a07776231eca8969bd2fd8edf204494c8`
3-4	html	`output/qualification/triangle-3-4-same-run.html`	`2876a732847108001f905b2375459aaeaca67b2502ac56cdf7ef47287d240653`
3-4	evidence	`output/qualification/triangle-3-4-same-run.evidence.json`	`65d38fae9190776401321e48c72fd509d0e8dcb7394a5cc4c722bbad783df71f`
3-4	pdf	`output/pdf/triangle-3-4-same-run.pdf`	`af032eb3ad3d2c018d6a3ce6a87bcf47bc2f0ede220821dabe97dbafb4175e05`

Primary evidence: output/qualification/reference-check-summary.json, output/qualification/browser-qualification.json, output/qualification/artifact-assertions.json, output/qualification/original-artifact-provenance.json. Visual evidence: output/qualification/pdf-3-4-page-1.png, output/qualification/pdf-6-6-page-1.png, output/qualification/same-run-html-3-4.png, output/qualification/same-run-html-6-6.png. The evidence index output/qualification/artifact-hashes.json records hashes of sources, references, scripts, checks, screenshots and final PDFs for retention.

Completed and closed after PR #125 merged at 2943192. All six acceptance criteria are now checked in the issue body.

The maintained installed-consumer acceptance and separate documentation-only triangle trial pass their reference, source-change/rebinding, browser, curl and same-run HTML/PDF checks. Every page of the four relevant PDFs was inspected. Full trial provenance, commands and exact hashes are retained in the trial record.

The final combined-head CI run passed quality, isolation, installed packages and both PowerShell shells; PR-title, dependency review and CodeQL also passed. There were no unresolved review threads. Initial test-harness/path errors were repaired; no failing acceptance remains.

Automated results and agent visual review are separate. Human engineering approval is NOT SUPPLIED, and registry publication was not performed.

Navigation Menu

Repository navigation

docs(initializer): verify the generated-project figure/reference authoring workflow #70

Completed verification

Documentation already present

Verification coverage

Acceptance criteria

Completion evidence

Ownership and dependencies

Historical context

Installed authoring trial: issues #73 and #70

Original installed artifact provenance

Read files and independently established brief

Complete bound references and negative checks

Live app, output-only API and same-run artifacts

PDF and HTML visual review

Commands and reproduction

Actual statuses, kept separate

Exact artifact paths and hashes

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

docs(initializer): verify the generated-project figure/reference authoring workflow #70

Description

Completed verification

Documentation already present

Verification coverage

Acceptance criteria

Completion evidence

Ownership and dependencies

Historical context

Activity

viktar-b commented on Nov 6, 2026

Installed authoring trial: issues #73 and #70

Original installed artifact provenance

Read files and independently established brief

Complete bound references and negative checks

Live app, output-only API and same-run artifacts

PDF and HTML visual review

Commands and reproduction

Actual statuses, kept separate

Exact artifact paths and hashes

viktar-b commented on Nov 6, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions