NoiseDoseLab

Abstract

This report evaluates NoiseDoseLab Level 1 CLI, an automatically generated ARCHCode Lab prototype for occupational noise exposure screening. Starting from a structured SpecBlock, ARCHCode Lab generated a working command-line application, produced a user manual, and subjected the result to executable black-box qualification. The prototype analyzes local baseline CSV files, computes energy-based normalized 8-hour exposure metrics, compares worker exposure against a reference dB level, emits deterministic text or JSON reports, and supports scenario-based prevention adjustments.

Qualification covered CLI discovery, user-error behavior, baseline and scenario validation, deterministic outputs, exact scientific metrics, user-manual conformance, and regression safety. The process identified three meaningful defects: acceptance of nonpositive reference levels, an internal field-dialect mismatch that corrupted scientific calculations, and failure to propagate invalid-row counts into the final report. Each defect was localized, patched with minimal changes, and revalidated.

The final run completed in 19 minutes, using 20 LLM calls across 6 agents, for an estimated total cost of 1.7391 USD. The experiment demonstrates that ARCHCode Lab can generate not only a functional scientific prototype, but also an auditable qualification trajectory including documentation, tests, defect detection, targeted correction, cost tracking, and final validation.

NoiseDoseLab Level 1 CLI — Scientific qualification note

NoiseDoseLab Level 1 CLI is a deterministic scientific command-line prototype for occupational noise exposure screening. It reads a local baseline CSV describing worker noise-exposure segments, computes energy-based normalized 8-hour exposure metrics, compares each worker’s result to a user-supplied reference level in dB, and produces stable text or JSON reports. The prototype also supports optional scenario adjustments through a separate CSV, allowing prevention strategies to be compared against the baseline exposure profile.

This page documents an ARCHCode Lab experiment. ARCHCode Lab is an automatic prototype-generation software system: it starts from a structured specification, generates a working software prototype, produces associated user documentation, and then subjects the result to executable qualification tests.

Here, the NoiseDoseLab CLI is used as a concrete case study. The page follows the full lifecycle of one generated prototype: SpecBlock, generated CLI, generated user manual, black-box tests, defect detection, targeted fixes, and final revalidation.

The complete specification used to frame this prototype is available here:

Open the complete NoiseDoseLab SpecBlock example

User manual

A downloadable user manual is available for the qualified NoiseDoseLab prototype.

This user manual was also generated by the ARCHCode Lab pipeline. It describes how a user is expected to discover the CLI, prepare baseline and scenario CSV files, run the analyze command, choose text or JSON output, and interpret the resulting exposure report. During qualification, the manual was not treated as decorative documentation only: its executable claims were converted into additional black-box tests and checked against the actual runtime behavior of the generated prototype.

Document: NoiseDoseLab Level 1 CLI User Manual
Schema version: 2.0
Generated: 2026-06-27 (UTC)

Download the NoiseDoseLab user manual as PDF

1. Identification

Prototype evaluated: NoiseDoseLab Level 1 CLI

Local qualification context:

C:\Users\Utilisateur\Documents\mARCHCode\pytest-5940\test_phase2_preflight_acw_chec0\repo\.archcode

CLI entry point:

C:\Users\Utilisateur\Documents\mARCHCode\pytest-5940\test_phase2_preflight_acw_chec0\repo\.archcode\app\cli.py

Black-box test battery:

C:\Users\Utilisateur\Documents\mARCHCode\tests\test_noisedoselab_blackbox.py

Execution command:

python tests/test_noisedoselab_blackbox.py -vv -o log_cli=true --log-cli-level=INFO

The prototype is a local scientific CLI for occupational noise exposure screening. It reads a baseline CSV, computes energy-based exposure metrics normalized to 8 hours, compares each worker’s exposure to a user-supplied reference level in dB, produces deterministic text or JSON reports, and optionally applies scenario adjustments from a second CSV.

The qualification described here is based on the new local prototype, tested and manually debugged in approximately 30 minutes.

2. Purpose of the qualification

The goal was to verify that the regenerated prototype satisfied both its user-facing contract and its scientific computation contract.

The qualification focused on:

CLI discovery and help behavior;
user-error handling;
baseline CSV validation;
scenario CSV validation;
deterministic text and JSON outputs;
positive and negative scenario behavior;
exact public scientific metrics;
regression safety after each targeted correction.

This page replaces the earlier NoiseDoseLab qualification narrative. The current result is stronger: the prototype is not only executable and documented, but also covered by a black-box battery that reaches the scientific calculation layer.

3. User-facing contract

The user manual describes a single CLI command:

python -m app.cli analyze

Core options:

--csv
--reference-db
--scenario-csv
--format
--alert-margin-db

Expected behavior:

Help commands:
  rc=0
  stdout non-empty
  stderr empty

User errors:
  rc=2
  stderr non-empty
  stdout empty or non-business output

Successful analysis:
  rc=0
  stdout non-empty
  stderr empty

Supported formats:
  text
  json

The reference exposure level must be numeric and strictly positive. A reference equal to zero or below zero is not valid input.

4. Qualification method

The test method is intentionally black-box.

The test battery invokes the CLI through subprocess:

python -m app.cli

It does not import the application internals for the primary verdict. It creates temporary CSV fixtures, runs the public CLI, captures return code, stdout and stderr, then evaluates the observed behavior.

A lightweight preflight using rg was used only when the public documentation was not sufficient to identify hidden internal dialects, especially the exact scenario CSV schema and the public names of scientific JSON fields.

The correction strategy was minimal:

Observe failure
→ identify contract breach
→ patch the smallest responsible boundary
→ run py_compile
→ re-run the complete black-box battery

5. Initial result before the final fixes

The first stable battery confirmed that the visible CLI was already healthy.

Help behavior passed:

[OK] HELP_01  Aucun argument affiche l'aide top-level
[OK] HELP_02  --help affiche l'aide top-level
[OK] HELP_03  analyze --help affiche les options documentées

Parsing errors also passed:

[OK] ERROR_01  Commande inconnue
[OK] ERROR_02  analyze sans --csv
[OK] ERROR_03  analyze sans --reference-db
[OK] ERROR_04  Format invalide
[OK] ERROR_05  Référence non numérique
[OK] ERROR_06  Alert margin non numérique

The baseline CSV schema was then discovered successfully, and the baseline workflow became executable.

However, the first meaningful contract bug appeared immediately after that.

The prototype accepted invalid reference values:

--reference-db 0
--reference-db -1

Both returned rc=0, even though the manual contract requires a strictly positive reference level.

This was a real user-facing contract defect.

6. First correction: strict positive reference level

The first correction was applied to the CLI boundary.

Before correction, --reference-db was parsed as a simple float.

After correction, the CLI uses a strict argparse validator:

value must be numeric
value must be finite
value must be strictly positive

Expected behavior after correction:

--reference-db 0   => rc=2, stderr non-empty
--reference-db -1  => rc=2, stderr non-empty

The re-run confirmed the fix:

[OK] DOMAIN_02  Référence égale à zéro refusée
[OK] DOMAIN_03  Référence négative refusée

No regression was introduced in the other CLI tests.

7. Scenario schema preflight

The user manual described scenario support but did not provide exact column names.

A focused preflight found the actual scenario schema expected by the prototype:

scenario,leq_delta_db,duration_factor,protection_delta_db

The test battery was then extended to include:

positive scenario run
scenario JSON determinism
missing scenario columns
non-numeric scenario value
zero duration factor
duplicate scenario name

The scenario layer then passed all tests.

8. Second defect: scientific dialect mismatch

The final scientific test layer revealed a deeper internal bug.

The black-box JSON output showed that rows containing valid leq_db values were being calculated as if the sound level were 0.0.

Example failure observed before correction:

Input row:
  worker=W_REF
  leq_db=85
  duration_hours=8
  attenuation_db=0
  reference_db=85

Observed output before correction:
  level_db: 0.0
  effective_db: 0.0
  segment_lex_8h: 0.0
  energy_ratio: 0.0
  status: ok

The expected result was:

level_db: 85.0
effective_db: 85.0
segment_lex_8h: 85.0
energy_ratio: 1.0
status: above_reference

The root cause was an internal dialect mismatch:

Validator dialect:
  leq_db
  duration_hours

Calculation dialect:
  level_db
  duration_h

The row was valid at the validation layer but partially lost when passed to the calculation and scenario layers.

This was not a CLI problem. It was a multi-module contract mismatch between baseline validation, baseline calculation and scenario analysis.

9. Second correction: normalize baseline/scenario dialects

The correction preserved the existing modules and added compatibility at the module boundaries.

Applied principles:

Do not rewrite the scientific formula.
Do not remove existing public fields.
Do not remove docstrings.
Do not regress accepted CSV dialects.
Add canonical aliases where the pipeline crosses module boundaries.

Corrected behavior:

baseline_validator emits both:
  leq_db
  level_db
  duration_hours
  duration_h

noise_calculations reads:
  level_db or leq_db

scenario_analysis reads:
  level_db or leq_db
  duration_h or duration_hours

This fixed the scientific calculations and preserved the existing black-box surface.

9 bis. Third defect: invalid-row evidence not propagated to the final report

A final user-manual conformance layer was added after the scientific tests. Its purpose was to verify that every executable claim in the user manual was reflected in the runtime behavior of the prototype.

This additional layer revealed a third defect. The user manual states that invalid baseline rows are ignored for calculations but counted in invalid-row statistics. The prototype correctly ignored invalid rows for exposure computation, but the final JSON report did not preserve the invalid-row evidence.

Observed behavior before correction:

Input CSV:
  total rows: 2
  valid rows: 1
  invalid rows: 1

Observed final report:
  total_rows: 1
  valid_rows: 1
  invalid_rows: 0

The defect did not corrupt the exposure calculation for accepted rows. However, it created a misleading data-quality report: the user could believe that the input dataset was fully valid, while one row had actually been rejected.

Severity assessment:

Severity: Major / data-quality reporting defect

This was not classified as a critical scientific computation defect because the invalid row was not used in the LEX,8h calculation. The core acoustic computation remained correct for accepted rows. The issue affected auditability, traceability and user-manual conformance.

The resolution was straightforward. The baseline validator already produced row counts internally. The missing step was to propagate these counts into the exposure result and final report payload before verdict evaluation and rendering.

Corrected behavior:

Input CSV:
  total rows: 2
  valid rows: 1
  invalid rows: 1

Final report:
  total_rows: 2
  valid_rows: 1
  invalid_rows: 1

The correction was small and localized to the orchestration boundary. No scientific formula was rewritten, and no CLI behavior was changed. After the patch, the complete black-box battery was rerun and the new user-manual conformance test passed:

[OK] MANUAL_05  User manual : ligne invalide ignorée mais comptée

This defect is important for the ARCHCode Lab demonstration because it shows that qualification does not stop at “the command runs”. The user manual itself becomes an executable contract. When the documentation says that invalid rows are counted, the test battery verifies that this is true in the final public report.

The economics of this finding are also significant. The user manual phase represented only:

model used: gpt-5.1
USER phase tokens : 15413
USER phase cost   : 0.0546 USD

At this cost level, the generated manual is already useful enough to expose a precise runtime conformance gap. More importantly, the cost is so low that there is clear room to upgrade the quality of future user manuals: richer examples, stricter data dictionaries, explicit CSV schemas, executable acceptance claims, and manual-to-test traceability can be added without materially changing the overall economics of the prototype generation run.

In other words, the low cost of the user manual is not a limitation. It is an opportunity. ARCHCode Lab can afford to make user documentation more precise, more testable, and more demanding, then use it as an additional quality gate against the generated software.

10. Final black-box validation

Final run:

====================================================================================================
NOISEDOSelab BLACK-BOX TEST BATTERY
====================================================================================================
Package root : C:\Users\Utilisateur\Documents\mARCHCode\pytest-5940\test_phase2_preflight_acw_chec0\repo\.archcode
Hard fails   : 0
Soft fails   : 0

Complete result:

[OK  ] HELP_01      hard  rc=  0  Aucun argument affiche l'aide top-level
[OK  ] HELP_02      hard  rc=  0  --help affiche l'aide top-level
[OK  ] HELP_03      hard  rc=  0  analyze --help affiche les options documentées

[OK  ] ERROR_01     hard  rc=  2  Commande inconnue
[OK  ] ERROR_02     hard  rc=  2  analyze sans --csv
[OK  ] ERROR_03     hard  rc=  2  analyze sans --reference-db
[OK  ] ERROR_04     hard  rc=  2  Format invalide
[OK  ] ERROR_05     hard  rc=  2  Référence non numérique
[OK  ] ERROR_06     hard  rc=  2  Alert margin non numérique

[OK  ] BUSINESS_00  hard  rc=  0  Découverte automatique du schéma CSV baseline

[OK  ] DOMAIN_01    hard  rc=  2  CSV baseline absent
[OK  ] DOMAIN_02    hard  rc=  2  Référence égale à zéro refusée
[OK  ] DOMAIN_03    hard  rc=  2  Référence négative refusée
[OK  ] DOMAIN_04    hard  rc=  2  Colonnes baseline invalides refusées
[OK  ] DOMAIN_05    hard  rc=  2  CSV scénario absent refusé si --scenario-csv est fourni

[OK  ] BUSINESS_01  hard  rc=  0  Baseline valide avec format par défaut
[OK  ] BUSINESS_02  hard  rc=  0  Baseline text déterministe
[OK  ] BUSINESS_03  hard  rc=  0  Baseline JSON valide et déterministe
[OK  ] BUSINESS_04  soft  rc=  0  Payload JSON contient les repères métier minimaux
[OK  ] BUSINESS_05  soft  rc=  0  Ligne invalide ignorée mais analyse encore possible

[OK  ] SCIENCE_01   hard  rc=  0  Référence exacte 85 dB sur 8h : ratio=1 et LEX,8h=85
[OK  ] SCIENCE_02   hard  rc=  0  Atténuation auditive appliquée : 90 dB - 10 dB = 80 dB effectifs
[OK  ] SCIENCE_03   hard  rc=  0  Durée normalisée 8h : 88 dB pendant 4h donne LEX,8h≈84.9897
[OK  ] SCIENCE_04   hard  rc=  0  Scénario : baisse de 5 dB et durée x0.5 réduit le LEX,8h d'environ 8.0103 dB

[OK  ] SCENARIO_00  soft  rc=  0  Découverte automatique du schéma CSV scénario
[OK  ] SCENARIO_01  hard  rc=  0  Scénario JSON valide et déterministe
[OK  ] SCENARIO_02  hard  rc=  2  Colonnes scénario incomplètes refusées
[OK  ] SCENARIO_03  hard  rc=  2  Valeur scénario non numérique refusée
[OK  ] SCENARIO_04  hard  rc=  2  Duration factor nul refusé
[OK  ] SCENARIO_05  hard  rc=  2  Nom de scénario dupliqué refusé

VERDICT: OK

Final result:

Hard fails: 0
Soft fails: 0
VERDICT: OK

11. Validated test coverage

The final battery validates the following layers.

CLI layer

no args
--help
analyze --help
unknown command
missing required options
invalid format
invalid numeric values

User-error contract

rc=2
stderr non-empty
no traceback
no silent user failure

Baseline input contract

baseline CSV exists
baseline CSV has valid rows
invalid columns are rejected
invalid rows are ignored and counted
baseline analysis runs in text format
baseline analysis runs in JSON format

Scenario input contract

scenario CSV exists when requested
required scenario columns are enforced
scenario numeric fields are validated
duration_factor must be strictly positive
scenario names must be unique
scenario outputs are deterministic

Scientific calculation contract

energy-domain dB calculation
effective dB after attenuation
normalized 8-hour exposure
LEX,8h
energy ratio to reference
status classification
scenario reduction versus baseline

12. Validated CSV dialects

Baseline dialect used by the scientific tests:

worker,task,leq_db,duration_hours,attenuation_db

Scenario dialect validated by black-box execution:

scenario,leq_delta_db,duration_factor,protection_delta_db

The prototype also accepts several baseline aliases through the validator, but the qualification page intentionally documents the stable dialect used by the final scientific battery.

13. Scientific checks

The final layer validates exact public numerical behavior.

Reference equality

Input:

leq_db=85
duration_hours=8
attenuation_db=0
reference_db=85

Expected public result:

effective_db = 85
LEX,8h = 85
energy_ratio = 1
status = above_reference

Validated:

[OK] SCIENCE_01

Hearing protection attenuation

Input:

leq_db=90
duration_hours=8
attenuation_db=10
reference_db=85

Expected public result:

effective_db = 80
LEX,8h = 80
energy_ratio ≈ 0.316228
status = ok

Validated:

[OK] SCIENCE_02

Duration normalization

Input:

leq_db=88
duration_hours=4
attenuation_db=0
reference_db=85

Expected public result:

LEX,8h ≈ 84.9897
energy_ratio ≈ 0.997631
status = alert

Validated:

[OK] SCIENCE_03

Scenario reduction

Baseline:

leq_db=90
duration_hours=8
attenuation_db=0
reference_db=85

Scenario:

leq_delta_db=-5
duration_factor=0.5
protection_delta_db=0

Expected public result:

scenario max_worker_lex_8h ≈ 81.9897
scenario max_worker_energy_ratio = 0.5
reduction_db_vs_baseline_max ≈ 8.0103
workers_above_reference = 0
segments_above_reference = 0

Validated:

[OK] SCIENCE_04

14. Manual debugging timeline

The new prototype was stabilized through a short manual loop of approximately 60 minutes.

Sequence:

1. Run black-box battery.
2. Detect reference_db positivity bug.
3. Patch CLI validator.
4. Re-run battery.
5. Preflight scenario schema.
6. Extend scenario tests.
7. Re-run battery.
8. Add scientific numerical tests.
9. Detect leq_db / level_db and duration_hours / duration_h mismatch.
10. Patch module-boundary aliases.
11. Re-run full battery.
12. Obtain VERDICT: OK.

This is an important demonstration point for ARCHCode.

The value is not that the first generated prototype is perfect. The value is that the defect surface becomes visible, reproducible, locally patchable, and fully revalidated in a short loop.

15. Interpretation for ARCHCode

NoiseDoseLab demonstrates a complete qualification loop for a generated scientific CLI.

ARCHCode Lab produced a usable domain prototype

The prototype is not a mock shell. It reads CSV files, validates input, computes exposure metrics, generates reports, and compares prevention scenarios.

The black-box battery detected real defects

The battery found two meaningful defects:

reference_db accepted zero or negative values
validated baseline fields were not consistently consumed by calculation modules

Both defects were observable only through executable behavior.

The defects were corrected locally and safely

The corrections were targeted:

CLI boundary for reference validation
module-boundary dialect normalization for scientific calculations

The full battery was rerun after correction and returned:

VERDICT: OK

The final prototype is stronger than a simple generated artifact

The final deliverable includes:

generated source code
user manual
black-box test battery
scenario validation
scientific numerical assertions
manual debug trace
final revalidation

This is the key ARCHCode Lab message: the system produces not only code, but an auditable trajectory from generation to qualification.

16. Metrics

The qualification run completed successfully.

Final test status : PASS
Pytest result     : 1 passed
Duration          : 1168.61s (0:19:28)
LLM calls         : 20
Agents involved   : 6
Effort profile    : medium
Model stack       : gpt-5.1, gpt-5.3-codex, gpt-5.4-mini

Token usage summary:

input_tokens        : 396291
cached_input_tokens : 23552
output_tokens       : 146004

Estimated total cost:

1.73906565 USD

High-level cost distribution:

Planning and normalization : 0.7346 USD
Code generation            : 0.5878 USD
System checking and harness: 0.3350 USD
Packaging                  : 0.0270 USD
User manual                : 0.0546 USD

High-level token distribution:

Planning and normalization : 125140 tokens
Code generation            : 130674 tokens
System checking and harness: 266761 tokens
Packaging and user manual  :  43272 tokens

For publication purposes, the detailed per-call execution trace is intentionally not exposed. The public metric layer reports only aggregated operational data sufficient to document reproducibility, cost envelope, and qualification effort without disclosing the internal execution choreography.

17. Final qualification statement

NoiseDoseLab Level 1 CLI is qualified as a scientific command-line prototype for deterministic occupational noise exposure screening.

Final state:

CLI contract: OK
baseline workflow: OK
scenario workflow: OK
error handling: OK
JSON determinism: OK
scientific public metrics: OK
final black-box verdict: OK

The prototype was regenerated, tested, manually debugged in a short targeted loop, and revalidated with zero hard failures and zero soft failures.

Final verdict:

VERDICT: OK

NoiseDoseLab is therefore suitable for inclusion in the ARCHCode Lab Lab showcase as a qualified scientific prototype.