language-conditioned-psychometric-harmonization-model/.learnings/ERRORS.md

# Errors

Command failures and integration errors.

---
## [ERR-20260920-042] pdf-runtime-path-mismatch

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: environment

### Summary
Neither `pdftotext` nor `pypdf` was available in the project/system Python path used for the first survey-design source extraction attempt.

### Error
PowerShell could not find `pdftotext`; project Python raised `ModuleNotFoundError: pypdf`.

### Context
The failures were read-only and occurred before any design decision was recorded.

### Suggested Fix
Use the Codex workspace PDF runtime returned by the workspace dependency loader for document extraction; keep statistical builders in `.venv-research`.

### Metadata
- Reproducible: yes
- Related Files: `research/stage1/survey_design_source_audit.md`
- Pattern-Key: environment.pdf-runtime-path

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Official guide pages were extracted with the bundled PDF runtime and cross-checked against local fields.

---
## [ERR-20260920-041] gitea-cached-credential-rejected

**Logged**: 2026-09-20
**Priority**: medium
**Status**: resolved
**Area**: infra

### Summary
Gitea rejected the cached credential while pushing the verified response-layer commit.

### Error
`remote: Failed to authenticate user` and `fatal: Authentication failed`.

### Context
Local commit `89c20f3` was created successfully; no remote history changed. Earlier pushes to the same URL succeeded.

### Suggested Fix
Use the configured Git Credential Manager to refresh only the `git.jinome.org` credential, then push all pending commits and verify local/remote HEAD equality.

### Metadata
- Reproducible: not yet known
- Related Files: `.git/config`, `Progression.md`
- Pattern-Key: git.cached-credential-rejected

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Cleared only the stale `git.jinome.org` credential, reauthorized through Git Credential Manager, and pushed both pending commits.

---
## [ERR-20260920-040] system-python-missing-project-package

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: environment

### Summary
The first response-long build was launched with system Python, which does not contain the locked project package set.

### Error
`ModuleNotFoundError: No module named 'duckdb'`

### Context
The import failed before source data were read or an output table was created. The project environment is `.venv-research`.

### Suggested Fix
Run research builders with `.venv-research/Scripts/python.exe` and reserve system Python for dependency-free diagnostics.

### Metadata
- Reproducible: yes
- Related Files: `research/stage1/build_responses_long.py`, `research/audit/environment_audit.md`
- Pattern-Key: environment.wrong-python-runtime

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Re-ran with the locked project Python; the long table and independent checks completed.

---
## [ERR-20260920-026] sas-input-block-comment-collision

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: data

### Summary
The first YRBS fixed-width layout parser matched the words “Input Program” in the SAS header comment instead of the executable `Input` statement.

### Error
`ValueError: No fields parsed` for the official 2021 SAS input program.

### Context
The broad first-occurrence regular expression selected a comment fragment. No Parquet or audit output was written.

### Suggested Fix
Anchor the parser to a line containing only the SAS `Input` keyword, then parse the following field declarations.

### Metadata
- Reproducible: yes
- Related Files: `research/stage1/import_yrbs_2021_2023.py`
- Pattern-Key: parser.comment-keyword-collision

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: The input-block expression is line-anchored and the import is rerun from the official files.

---
## [ERR-20260920-036] pdf-text-console-encoding

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: docs

### Summary
An exploratory YRBS PDF text scan stopped when Windows console encoding could not print a soft-hyphen character.

### Error
`UnicodeEncodeError: 'gbk' codec can't encode character`.

### Context
PDF extraction itself succeeded; only diagnostic console output failed. Source files were unchanged.

### Suggested Fix
Configure diagnostic stdout as UTF-8 with replacement before printing extracted PDF text.

### Metadata
- Reproducible: yes
- Related Files: `research/stage1/yrbs_primary_outcome_source_audit.json`
- Pattern-Key: docs.console-encoding

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: The scan was rerun with UTF-8 stdout and all annual source pages were reviewed.

---
## [ERR-20260920-035] gshs-questionnaire-directory-assumption

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: docs

### Summary
The first questionnaire inventory command assumed a non-existent `03_questionnaires_and_codebooks` directory.

### Error
`rg` returned an OS error because that path does not exist.

### Context
The dataset uses `GSHS/Questionnaire`, while `03_examples` is a separate directory. No files were changed.

### Suggested Fix
Enumerate the GSHS root before applying a documentation-path convention.

### Metadata
- Reproducible: yes
- Related Files: `Dataset/GSHS-全球学生健康调查数据/GSHS/Questionnaire`
- Pattern-Key: docs.path-assumption

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Enumerating the root located the actual questionnaire directory and the audit continued there.

---
## [ERR-20260920-034] project-python-document-parser-missing

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: dependencies

### Summary
The project research environment does not include `python-docx`, `pypdf`, or `pdfplumber`, so an exploratory source-extraction import failed.

### Error
`ModuleNotFoundError: No module named 'docx'`.

### Context
These packages are available in the Codex bundled document runtime. The final component audit uses only the project standard library and records verified source paths, pages/sections, and hashes, so it does not introduce an undeclared runtime dependency.

### Suggested Fix
Use the bundled read-only document runtime for source inspection unless document parsing becomes a reproducible project pipeline dependency; only then add and lock the packages in the project environment.

### Metadata
- Reproducible: yes
- Related Files: `research/stage1/gshs_primary_outcome_component_audit.json`
- Pattern-Key: dependency.optional-document-parser

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Source text was extracted with the bundled runtime and key PDF pages were rendered with Poppler for visual verification.

---
## [ERR-20260920-033] repeated-gshs-pandas-memory-exhaustion

**Logged**: 2026-09-20
**Priority**: medium
**Status**: resolved
**Area**: runtime

### Summary
An exploratory pandas cross-tab scan again exhausted memory while parsing the 637-column GSHS CSV.

### Error
`pandas.errors.ParserError: Error tokenizing data. C error: out of memory`.

### Context
This is a recurrence of `ERR-20260920-029` during a new component-level relation check. The source file was not changed.

### Suggested Fix
Use a streaming `csv.reader` scan with fixed column indices for all full-file GSHS audits.

### Metadata
- Reproducible: yes
- Related Files: `research/stage1/audit_gshs_primary_outcome_components.py`
- Pattern-Key: runtime.memory-exhaustion
- Related Error: `ERR-20260920-029`
- Recurrence Count: 2

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: The streaming audit completed all 673,499 rows, all 191 components, and all three raw/binary relationship checks without a dense pandas load.

---
## [ERR-20260920-032] samhsa-pdf-direct-fetch-forbidden

**Logged**: 2026-09-20
**Priority**: medium
**Status**: resolved
**Area**: docs

### Summary
SAMHSA PDF endpoints returned HTTP 403 to the web reader, direct download, and in-app browser during the NSDUH source audit.

### Error
`403 Forbidden` from the official PDF URLs; the sandboxed first download attempt also had no network route.

### Context
The official documents remained indexed with searchable text, and SAMHSA HTML methodology pages plus year-specific search extracts exposed the required question, routing, variable, and disclosure-risk statements. No local or remote data were changed by the failed reads.

### Suggested Fix
Use SAMHSA's indexed official-document text and HTML pages for this audit, retain exact source URLs, and keep page-level PDF visual verification pending rather than claiming it occurred.

### Metadata
- Reproducible: yes
- Related Files: `research/stage1/nsduh_youth_attempt_source_audit.md`
- Pattern-Key: net.access-forbidden

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Triangulated the claim across official 2021–2023 restricted-use codebooks, the 2024 questionnaire, 2024 methodology definitions, the 2024 public-use guide, and the local public-use schema. Direct PDF page rendering remains explicitly unverified.

---
## [ERR-20260920-031] git-https-authentication-rejected

**Logged**: 2026-09-20
**Priority**: high
**Status**: resolved
**Area**: infra

### Summary
The remote rejected the previously authorized HTTPS credential when pushing the Stage 1 source-registry commit.

### Error
`remote: Failed to authenticate user` / `fatal: Authentication failed`

### Context
Local commit `fb30b60` was created successfully. Local `main` is one commit ahead of `origin/main`; no remote history changed.

### Suggested Fix
Reauthorize the `git.jinome.org` entry through Git Credential Manager, then retry `git push`. Do not store a password or token in repository files.

### Metadata
- Reproducible: yes
- Related Files: `.git/config`, `Progression.md`
- Pattern-Key: auth.token-expired

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Removed only the rejected `git.jinome.org` cached entry, reauthorized through Git Credential Manager, and pushed local `main` through `ca67e1f` without storing credentials in the repository.

---
## [ERR-20260920-030] gshs-workbook-column-name

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: docs

### Summary
An exploratory GSHS workbook filter referenced `column` instead of the actual `column_name` field.

### Error
`KeyError: 'column'`

### Context
The workbook schema was printed in the same command and showed the correct field name. The failed command was read-only and changed no data.

### Suggested Fix
Inspect the sheet columns first and filter on `column_name`.

### Metadata
- Reproducible: yes
- Related Files: `Dataset/GSHS-全球学生健康调查数据/GSHS/02_documentation/GSHS_数据字典.xlsx`
- Pattern-Key: runtime.python-exception

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Re-ran the read-only extraction using `column_name` and obtained the intended candidate rows.

---
## [ERR-20260920-028] python-assignment-expression-comprehension

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: tests

### Summary
An inline audit command used an assignment expression in a comprehension iterable, which Python rejects.

### Error
`SyntaxError: assignment expression cannot be used in a comprehension iterable expression`.

### Context
The command was a read-only attempt to aggregate GSHS design-field coverage; no data or project file changed.

### Suggested Fix
Use an ordinary loop in a maintained audit script instead of compressing stateful aggregation into a one-liner.

### Metadata
- Reproducible: yes
- Related Files: `research/stage1/audit_input_sources.py`
- Pattern-Key: runtime.python-syntax

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Replaced the inline expression with a reusable streaming audit script.

---
## [ERR-20260920-029] pandas-csv-memory-exhaustion

**Logged**: 2026-09-20
**Priority**: medium
**Status**: resolved
**Area**: tests

### Summary
Pandas exhausted memory while parsing the 0.77 GB, 637-column GSHS CSV even though only 12 columns were requested.

### Error
`pandas.errors.ParserError: Error tokenizing data. C error: out of memory`.

### Context
The failed read was non-mutating. The GSHS file is wide enough that the C parser's tokenization buffers remain material despite `usecols`.

### Suggested Fix
Stream rows with the standard CSV reader, map only required column indexes, and retain aggregate counters rather than a DataFrame.

### Metadata
- Reproducible: yes
- Related Files: `research/stage1/audit_input_sources.py`
- Pattern-Key: runtime.memory-exhaustion

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: The streaming implementation completed the full 673,499-row audit without loading the dataset into memory.

---
## [ERR-20260920-024] git-push-repository-not-found

**Logged**: 2026-09-20T06:55:24+12:00
**Priority**: high
**Status**: resolved
**Area**: infra

### Summary
The configured HTTPS remote accepted a network connection but did not resolve to a repository visible to the current credentials.

### Error
`remote: Not found.` followed by `fatal: repository 'https://git.jinome.org/Jinovo/' not found`.

### Context
- Added the user-provided address as `origin`: `https://git.jinome.org/Jinovo`.
- Attempted to push local `main` and set its upstream.
- No commits were uploaded and the local branch/history were unchanged.

### Suggested Fix
Obtain the complete clone URL for the concrete repository, including any repository slug and `.git` suffix required by the server, or configure credentials that can access the existing repository. Do not guess or rewrite the remote without user confirmation.

### Metadata
- Reproducible: yes
- Related Files: `.git/config`, `Progression.md`
- Pattern-Key: vcs.repository-not-found
- First-Seen: 2026-09-20
- Last-Seen: 2026-09-20

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Created the concrete Gitea repository and replaced the account-page URL with its full `.git` clone URL.

---

## [ERR-20260920-025] ssh-config-read-denied

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: infra

### Summary
A read-only probe for an existing SSH configuration could not access the user SSH directory under the managed filesystem profile.

### Error
`Access to the path 'C:\Users\Jino\.ssh' is denied.`

### Context
The probe was intended only to see whether an existing SSH identity could replace HTTPS authentication. No key content was requested or exposed.

### Suggested Fix
Do not weaken filesystem permissions; use the verified HTTPS remote and Git Credential Manager.

### Metadata
- Reproducible: yes
- Related Files: `.git/config`, `Progression.md`
- Pattern-Key: fs.permission-denied

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: HTTPS authentication succeeded after the user authorized Credential Manager; SSH inspection is no longer needed.

---

## [ERR-20260920-026] git-https-credential-unavailable

**Logged**: 2026-09-20
**Priority**: high
**Status**: resolved
**Area**: infra

### Summary
The new remote repository initially had no command-line HTTPS credential available to local Git.

### Error
`fatal: Cannot prompt because user interactivity has been disabled.` followed by `fatal: unable to get password from user`.

### Context
Browser login created the repository, but browser cookies did not authenticate command-line Git. The user subsequently authorized Git Credential Manager.

### Suggested Fix
Authorize Git Credential Manager without placing credentials in the remote URL, shell history, or tracked files.

### Metadata
- Reproducible: yes
- Related Files: `.git/config`, `Progression.md`
- Pattern-Key: auth.missing-credential

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Credential Manager authorization completed; `main` pushed successfully and now tracks `origin/main`.

---

## [ERR-20260920-027] apply-patch-context-mismatch

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: docs

### Summary
A combined archival patch failed because its expected context omitted a blank line before the separator in the error log.

### Error
`apply_patch verification failed: Failed to find expected lines`.

### Context
The failed patch made no partial changes. The actual file section was reread before retrying with exact context.

### Suggested Fix
Inspect the precise surrounding lines before a multi-file patch and include blank-line structure in the patch context.

### Metadata
- Reproducible: yes
- Related Files: `.learnings/ERRORS.md`, `Progression.md`
- Pattern-Key: docs.patch-context-mismatch

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Reapplied with exact file context.

---

## [ERR-20260920-006] powershell-empty-pipe

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: infra

### Summary
A final artifact verification command piped directly from a PowerShell `foreach` statement and produced an empty-pipe parser error.

### Error
`ParserError: An empty pipe element is not allowed.`

### Context
Read-only existence and size verification for the four Stage 0 deliverables and Progression.md.

### Suggested Fix
Collect `foreach` output into an array first, then pipe the array to `Format-Table`.

### Metadata
- Reproducible: yes
- Related Files: `Progression.md`
- Pattern-Key: shell.nonzero-exit

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: The corrected command verified all required deliverables exist and contain data.

---

## [ERR-20260920-004] progression-patch-context

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: docs

### Summary
A combined large patch failed because one Progression.md context line did not match byte-for-byte.

### Error
`apply_patch verification failed: Failed to find expected lines`

### Context
Attempted to create the project charter and update multiple distant sections of the progress archive in one patch.

### Suggested Fix
Split artifact creation from progress updates and use smaller, exact context anchors confirmed with `rg`.

### Metadata
- Reproducible: unknown
- Related Files: `Progression.md`, `research/protocol/project_charter.md`
- Pattern-Key: config.patch-context-mismatch

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Re-read the mandatory context and split the operation into smaller patches.
- **Recurrence-Count**: 2
- **Last-Seen**: 2026-09-20

---

## [ERR-20260920-005] spreadsheet-marker-path

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: infra

### Summary
The spreadsheet skill's operation marker was not located at the dependency-root path shown by the generic example.

### Error
`Cannot find module ...dependencies\\container_tools\\mark_artifact_operation_started.mjs`

### Context
Preparing to author the literature matrix with the bundled artifact runtime.

### Suggested Fix
Resolve the marker from the installed spreadsheet skill directory rather than the dependency root.

### Metadata
- Reproducible: yes
- Related Files: `research/protocol/literature_matrix.xlsx`
- Pattern-Key: config.missing-script

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Located the marker under the versioned spreadsheet skill and ran it successfully before authoring.

---

## [ERR-20260920-002] restricted-system-inventory

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: infra

### Summary
WMI, `Get-Volume`, and `systeminfo` returned access denied during the environment audit.

### Error
`Access denied` / `拒绝访问`

### Context
Attempted read-only OS, RAM, and volume inventory inside the managed Windows execution environment.

### Suggested Fix
Use unprivileged fallbacks: .NET runtime information, `Microsoft.VisualBasic.Devices.ComputerInfo`, and `Get-PSDrive`.

### Metadata
- Reproducible: yes
- Related Files: `research/audit/environment_audit.md`
- Pattern-Key: fs.permission-denied

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Fallback interfaces returned OS architecture, physical RAM, and filesystem free space without escalation.

---

## [ERR-20260920-003] python-package-detection

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: infra

### Summary
The first package audit used import names derived mechanically from distribution names and produced unreliable missing-package results; a follow-up also attempted to import absent `psutil`.

### Error
`ModuleNotFoundError: No module named 'psutil'`

### Context
Auditing the local Python scientific stack. Distribution names such as `scikit-learn` do not map mechanically to import names.

### Suggested Fix
Query installed distribution versions directly with `importlib.metadata.version()` and handle `PackageNotFoundError` without importing packages.

### Metadata
- Reproducible: yes
- Related Files: `research/audit/environment_audit.md`
- Pattern-Key: deps.module-not-found

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: The final package table was generated directly from distribution metadata; hardware memory used a .NET fallback.

---

## [ERR-20260920-001] pdf-to-markdown-encoding

**Logged**: 2026-09-20
**Priority**: medium
**Status**: resolved
**Area**: docs

### Summary
PDF text extraction failed because Python wrote a Unicode character that could not be encoded using the Windows default code page.

### Error
`UnicodeEncodeError: 'gbk' codec can't encode character`

### Context
Attempted to extract text from `Document/项目的正式定位.pdf` before passing it through Pandoc.

### Suggested Fix
Force UTF-8 output with `PYTHONIOENCODING=utf-8`.

### Metadata
- Reproducible: yes
- Pattern-Key: shell.encoding-error

---
## [ERR-20260920-007] winget-access-denied

**Logged**: 2026-09-20
**Priority**: medium
**Status**: pending
**Area**: infra

### Summary
The Windows Package Manager launcher exists but cannot be executed from the managed environment.

### Error
`Program 'winget.exe' failed to run: 系统无法访问此文件。`

### Context
Attempted to inventory/install R, Python, and CUDA Toolkit through the standard Windows package manager after the user authorized environment remediation.

### Suggested Fix
Use vendor-provided official installers, or retry `winget` outside the restricted environment if explicit escalation makes the launcher accessible.

### Metadata
- Reproducible: yes
- Related Files: `Progression.md`, `research/audit/environment_audit.md`
- Pattern-Key: tool.access-denied

---
## [ERR-20260920-008] uv-python-patch-path

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: infra

### Summary
The virtual-environment command hard-coded a Python 3.12 patch-version path that differed from the version resolved by `uv`.

### Error
`No interpreter found at path .python\\cpython-3.12.11-windows-x86_64-none\\python.exe`

### Context
`uv python install 3.12` correctly resolved CPython 3.12.14, while the following command assumed 3.12.11.

### Suggested Fix
Resolve the installed interpreter path from `uv python find` or enumerate the installation directory rather than hard-coding a patch version.

### Metadata
- Reproducible: yes
- Related Files: `Progression.md`
- Pattern-Key: config.version-path-mismatch

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Located `E:\\Model\\.python\\cpython-3.12.14-windows-x86_64-none\\python.exe`; subsequent environment creation will use this exact path.

---
## [ERR-20260920-009] research-env-smoke-failures

**Logged**: 2026-09-20
**Priority**: high
**Status**: pending
**Area**: infra

### Summary
The first research-environment runtime test found cache-permission, package-API, and CPU-only PyTorch problems despite a clean dependency-metadata check.

### Error
`PermissionError` for PyTensor/Matplotlib/skrub cache paths; `TypeError: check_array() got an unexpected keyword argument 'force_all_finite'`; `torch.cuda.is_available() is false`.

### Context
Executed PyMC sampling, semopy CFA, factor analysis, module imports, and a CUDA matrix multiplication in the new Python 3.12 environment.

### Suggested Fix
Redirect all caches into the writable project tree, pin a factor-analyzer-compatible scikit-learn release, and reinstall a matched Torch/TorchVision/TorchAudio set from the official CUDA wheel index.

### Metadata
- Reproducible: yes
- Related Files: `research/environment/smoke_test.py`, `research/environment/smoke-test-result.json`, `Progression.md`
- Pattern-Key: deps.runtime-compatibility

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Redirected caches into `E:\\Model\\.cache`, pinned scikit-learn 1.6.1, and installed matched CUDA 13.0 builds of Torch 2.14.0 and TorchVision 0.29.0. Torchaudio was removed because no same-generation official wheel exists and the project has no audio workload. Final closure is supported by the second smoke test recorded in `Progression.md`.

---
## [ERR-20260920-010] torchaudio-release-mismatch

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: infra

### Summary
The requested CUDA 13.0 Torch 2.14 stack could not be resolved because the official index does not publish torchaudio 2.14.0 for Windows/Python 3.12.

### Error
`No solution found ... there is no version of torchaudio==2.14.0`.

### Context
Attempted to align torch, torchvision, and torchaudio at the Torch 2.14 generation using the official CUDA 13.0 wheel index.

### Suggested Fix
Do not install torchaudio when the project has no audio workload; keep only matched torch and torchvision CUDA builds.

### Metadata
- Reproducible: yes
- Related Files: `research/environment/python-requirements.in`, `Progression.md`
- Pattern-Key: deps.release-mismatch

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Removed torchaudio from the project requirements and smoke-test contract after verifying the official index.

---
## [ERR-20260920-011] r-installer-file-race

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: infra

### Summary
The silent R installer returned before the first immediate `Rscript` invocation observed the completed target files.

### Error
`Rscript.exe is not recognized` immediately after installer return.

### Context
Installed R 4.6.1 into the project-local tools directory with the official CRAN Windows installer.

### Suggested Fix
After installer return, poll for the expected executable or perform a separate verification step before declaring failure.

### Metadata
- Reproducible: unknown
- Related Files: `Progression.md`
- Pattern-Key: installer.completion-race

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: A follow-up inventory showed a complete installation; `Rscript` reported R 4.6.1 x64 successfully.

---
## [ERR-20260920-012] r-smoke-false-positive

**Logged**: 2026-09-20
**Priority**: high
**Status**: resolved
**Area**: tests

### Summary
The first R smoke test marked the mirt test as passed even though the fitted model reported non-convergence.

### Error
The JSON result contained `status: passed` together with `converged: false`.

### Context
The test wrapper treated any expression that returned without raising an R error as success; the mirt block returned its optimizer flag but did not assert it.

### Suggested Fix
Use data generated from an identifiable 2PL model and raise an explicit error unless `fit@OptimInfo$converged` is true.

### Metadata
- Reproducible: yes
- Related Files: `research/environment/r-smoke-test.R`, `research/environment/r-smoke-test-result.json`, `Progression.md`
- Pattern-Key: tests.missing-assertion

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Added an explicit convergence assertion, identifiable 2PL simulation, and a higher EM-cycle ceiling. A second run is required for environmental acceptance.

---
## [ERR-20260920-013] tool-poll-key-escaping

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: infra

### Summary
Two CUDA installer status polls failed because a hyphenated nested-tool argument key was not quoted in JavaScript.

### Error
`SyntaxError: Unexpected string` / `SyntaxError: Invalid or unexpected token`.

### Context
Polling an already-running installer session; the failed polls did not send input or alter the installer process.

### Suggested Fix
Quote hyphenated object keys, e.g. `{"yield-time_ms": 30000}`.

### Metadata
- Reproducible: yes
- Related Files: `Progression.md`
- Pattern-Key: tooling.javascript-object-key

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Corrected the key quoting and continued polling the same session until the installer returned exit code 0.

---
## [ERR-20260920-014] vsdevcmd-nested-quoting

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: infra

### Summary
The first CUDA compile command failed before invoking the compiler because nested `cmd.exe` quoting truncated the Visual Studio path at the first space.

### Error
`'""C:\\Program' is not recognized as an internal or external command`.

### Context
Attempted to chain `VsDevCmd.bat`, nvcc, and the smoke executable in a single quoted `cmd.exe /c` string.

### Suggested Fix
Capture the environment emitted by `VsDevCmd.bat && set`, import it into the PowerShell process, then invoke nvcc directly with argument boundaries managed by PowerShell.

### Metadata
- Reproducible: yes
- Related Files: `research/environment/cuda-smoke.cu`, `Progression.md`
- Pattern-Key: shell.windows-nested-quoting

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Switched to importing the Visual Studio environment before compiler invocation; the corrected compile is recorded separately in `Progression.md`.

---
## [ERR-20260920-015] nvcc-host-compiler-path

**Logged**: 2026-09-20
**Priority**: medium
**Status**: resolved
**Area**: infra

### Summary
nvcc could not find `cl.exe` after Visual Studio environment variables were copied from a child cmd process into PowerShell.

### Error
`nvcc fatal: Cannot find compiler 'cl.exe' in PATH`.

### Context
The MSVC component and compiler file were installed, but cross-shell environment import was insufficient for nvcc host-tool discovery.

### Suggested Fix
Run `vcvars64.bat`, nvcc, and the resulting binary inside one cmd process using a checked-in build script.

### Metadata
- Reproducible: yes
- Related Files: `research/environment/cuda-smoke-build.cmd`, `research/environment/cuda-smoke.cu`, `Progression.md`
- Pattern-Key: toolchain.environment-propagation

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Created a single-shell build script after verifying the exact MSVC 14.44 compiler path with vswhere.

---
## [ERR-20260920-016] lock-cache-permissions

**Logged**: 2026-09-20
**Priority**: medium
**Status**: resolved
**Area**: infra

### Summary
Python and R lock export failed because uv and renv attempted to initialize caches under restricted user-profile directories.

### Error
`Failed to initialize cache ... uv\\cache` and `failed to create directory ... R/cache/R/renv`.

### Context
The runtime caches had been redirected, but the package-manager-specific cache variables were not yet included.

### Suggested Fix
Set `UV_CACHE_DIR` and `RENV_PATHS_ROOT` to writable project-local directories for both activation and export commands.

### Metadata
- Reproducible: yes
- Related Files: `research/environment/activate-research.ps1`, `Progression.md`
- Pattern-Key: fs.package-manager-cache-permission

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Added project-local uv and renv cache roots; lock export is retried as a separate audited action.

---
## [ERR-20260920-017] r-lock-export-schema

**Logged**: 2026-09-20
**Priority**: medium
**Status**: resolved
**Area**: infra

### Summary
The R lock snapshot was written, but the auxiliary installed-package export failed due to an assumed metadata column and an incomplete library search path.

### Error
`subscript out of bounds` for the `Repository` column; renv warned that R-recommended packages were missing.

### Context
The export indexed a fixed column list from `installed.packages(lib.loc=project_library)` and passed only the project library to renv.

### Suggested Fix
Combine the project library with `.Library`, and select only metadata columns that actually exist before writing CSV.

### Metadata
- Reproducible: yes
- Related Files: `research/environment/renv.lock`, `Progression.md`
- Pattern-Key: data.schema-assumption

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: The corrected export uses both library roots and intersects requested fields with returned column names; final verification is a separate action.

---
## [ERR-20260920-018] apply-patch-same-file-multiple-operations

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: docs

### Summary
A patch attempted to delete and add the same audit file in one invocation and was rejected before making changes.

### Error
`multiple operations target ... environment_audit.md`.

### Context
Replacing the completed environment audit while also adding usage documentation and updating progression state.

### Suggested Fix
Split full-file replacement into separate delete and add operations, then patch other files separately.

### Metadata
- Reproducible: yes
- Related Files: `research/audit/environment_audit.md`, `Progression.md`
- Pattern-Key: tooling.patch-operation-conflict

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: No file changed in the rejected patch; the replacement is retried in valid discrete operations.

---
## [ERR-20260920-019] apply-patch-hunk-order

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: docs

### Summary
A combined README/progression patch was rejected because two progression hunks were ordered opposite to their line order in the file.

### Error
`Failed to find expected lines in Progression.md` even though the lines existed.

### Context
One hunk targeted a later risk-table line before another hunk targeted an earlier confirmed-facts line.

### Suggested Fix
Order update hunks from top to bottom within each file, or split unrelated file additions and updates.

### Metadata
- Reproducible: yes
- Related Files: `research/environment/README.md`, `Progression.md`
- Pattern-Key: tooling.patch-hunk-order

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Added the README separately and applied progression hunks in file order.

---
## [ERR-20260920-020] git-dubious-ownership

**Logged**: 2026-09-20
**Priority**: medium
**Status**: resolved
**Area**: infra

### Summary
Git refused repository status checks after initialization because the workspace owner differs from the managed execution account.

### Error
`fatal: detected dubious ownership in repository at 'E:/Model'`.

### Context
The repository directory is owned by the Windows Administrators group while commands run as CodexSandboxOffline.

### Suggested Fix
Add only the exact repository path to Git's global `safe.directory`; do not use a wildcard.

### Metadata
- Reproducible: yes
- Related Files: `.git`, `Progression.md`
- Pattern-Key: git.safe-directory

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: The exact-path exception is applied as the next audited action before staging.

---
## [ERR-20260920-021] git-candidate-node-modules

**Logged**: 2026-09-20
**Priority**: medium
**Status**: resolved
**Area**: infra

### Summary
The first Git candidate set unintentionally included a nested `node_modules` tree, expanding the proposed commit to 7,832 files and about 321 MiB.

### Error
Candidate-size audit showed large native modules and generated JavaScript under `research/experiments/node_modules`.

### Context
The initial `.gitignore` covered research runtimes and caches but omitted generic nested Node dependencies.

### Suggested Fix
Add `**/node_modules/` before staging and rerun the size audit.

### Metadata
- Reproducible: yes
- Related Files: `.gitignore`, `Progression.md`
- Pattern-Key: git.generated-dependency-tree

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Added the nested dependency ignore rule before any files were staged.

---
## [ERR-20260920-022] git-index-lock-permission

**Logged**: 2026-09-20
**Priority**: medium
**Status**: resolved
**Area**: infra

### Summary
The first staging attempt could read the repository but could not create `.git/index.lock` under the managed filesystem profile.

### Error
`fatal: Unable to create 'E:/Model/.git/index.lock': Permission denied`.

### Context
The workspace is writable, while repository metadata is protected and requires the authorized elevated Git operation path.

### Suggested Fix
Retry only the required Git index/commit operations with escalation; do not change workspace ownership or weaken filesystem permissions.

### Metadata
- Reproducible: yes
- Related Files: `.git`, `Progression.md`
- Pattern-Key: git.index-lock-permission

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: No files were staged in the failed attempt; the audited candidate set is retried with scoped Git authorization.

---
## [ERR-20260920-023] git-null-excludesfile

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: infra

### Summary
Git for Windows rejected `NUL` as an explicit global excludes file override.

### Error
`fatal: cannot use NUL as an exclude file`.

### Context
The override was intended only to silence warnings from an unreadable user-level ignore file; project ignore rules were already valid.

### Suggested Fix
Remove the override and tolerate the harmless warning, or use an actual readable empty file if silence is necessary.

### Metadata
- Reproducible: yes
- Related Files: `.gitignore`, `Progression.md`
- Pattern-Key: git.excludesfile-windows-device

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: The override is removed; no index changes occurred in the failed attempt.

---
## [ERR-20260920-037] parquet-field-name-assumption

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: data

### Summary
A diagnostic PyArrow read requested a non-existent `survey_year` field from the NSDUH full Parquet.

### Error
The full NSDUH schema uses `YEAR`, not `survey_year`.

### Context
The field name was inferred from the YRBS convention instead of checked against the NSDUH schema. No data were modified.

### Suggested Fix
Inspect the authoritative schema before column projection and use the source-specific `YEAR` field; DuckDB then verified the intended annual counts.

### Metadata
- Reproducible: yes
- Related Files: `Dataset/可直接分析数据包_NSDUH_YRBS/NSDUH/nsduh_2021_2024_full.parquet`
- Pattern-Key: schema.field-name-assumption

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Re-ran the count query against `YEAR` and obtained annual distributions for `YUSUITHK` and `YUSUIPLN`.

---
## [ERR-20260920-038] yrbs-attempt-response-shape

**Logged**: 2026-09-20
**Priority**: medium
**Status**: resolved
**Area**: data

### Summary
The first Gate-1 package build assumed all YRBS primary outcomes were binary and stopped on attempt response code 3.

### Error
`ValueError: Unsupported response code: survey='YRBS' construct='suicide_attempt' code='3' label='2 or 3 times'`

### Context
Annual source audits correctly retained five attempt-frequency categories, but the canonical response function handled the ordinal mapping only for GSHS. The fail-closed check prevented output files from being written.

### Suggested Fix
Apply the shared five-level frequency mapping to both GSHS and YRBS attempt items and rerun all package validations.

### Metadata
- Reproducible: yes
- Related Files: `research/stage1/build_primary_outcome_package.py`, `research/stage1/yrbs_primary_outcome_source_audit.json`
- Pattern-Key: response-dictionary.shape-assumption

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Canonical attempt categories are now `zero`, `one`, `two_or_three`, `four_or_five`, and `six_or_more` in both surveys.

---
## [ERR-20260920-039] sas-input-parser-edge-cases

**Logged**: 2026-09-20
**Priority**: low
**Status**: resolved
**Area**: data

### Summary
The first two YRBS fixed-width parser attempts encountered a SAS header-comment keyword collision and the SAS numeric missing token `.`.

### Error
The first attempt found no layout fields; the second could not convert `.` to a float.

### Context
Both failures occurred before a complete Parquet/audit output was accepted.

### Suggested Fix
Anchor the layout parser to a line containing only `Input` and map the SAS numeric missing token `.` to null.

### Metadata
- Reproducible: yes
- Related Files: `research/stage1/import_yrbs_2021_2023.py`
- Pattern-Key: parser.sas-fixed-width-edge-cases

### Resolution
- **Resolved**: 2026-09-20
- **Notes**: Both cases are handled explicitly and the official-layout import is rerun from source.

---