# Practical Development Simulation Audit - 2026-06-16

## Scope

This report records a read-mostly practical development simulation on branch `main` at commit `ff5c48a2fd657499c821b53d5913c9b8425c0480`.

The simulation followed the `/audit` workflow: map repository structure, identify development entry points, run representative local validation, exercise a deploy dry-run, and record gaps that would affect a real contributor loop.

## System Map

- Tracked files: 391.
- Files visible to `rg --files --hidden` excluding `.git`: 404.
- Primary domains: governance runtime, workflow routing, validators, deploy/install wrappers, skill metadata, tests.
- Top-level file concentration: `.agentcortex` 152 files, `.agent` 55, `docs` 50, `tests` 34, `.claude` 34, `.agents` 30.
- Main contributor commands observed: `powershell -ExecutionPolicy Bypass -File .\.agentcortex\bin\validate.ps1`, `bash .agentcortex/bin/validate.sh --no-python`, `powershell -ExecutionPolicy Bypass -File .\installers\deploy_brain.ps1 -DryRun <target>`.

## Evidence Summary

- `bash .agentcortex/bin/validate.sh --no-python` through PATH failed before project validation because `bash` resolved to `C:\Users\wen\AppData\Local\Microsoft\WindowsApps\bash.exe`.
- Explicit Git Bash validation: `C:\Program Files\Git\bin\bash.exe .agentcortex/bin/validate.sh --no-python` -> `pass=92 warn=6 fail=1 skip=17`.
- PowerShell lightweight validation: `validate.ps1 -NoPython` -> `pass=92 warn=6 fail=1 skip=15`.
- PowerShell full validation: `validate.ps1` -> `pass=104 warn=7 fail=1 skip=2`.
- Targeted unit test: `python -m pytest tests/guard/test_worklog_lock_blocking.py -q` -> `23 passed in 0.68s`.
- Installer dry-run: `powershell -ExecutionPolicy Bypass -File .\installers\deploy_brain.ps1 -DryRun .\temp_downstream` -> success, reported `Total: ~188 files would be deployed.`

## Double-Check Calibration

After a second pass, not every signal below should be treated as a governance defect. The practical simulation mixed three sources of evidence: framework behavior, local Windows/tooling behavior, and my own audit execution choices.

- Reclassified as AI-flow/doc-ambiguity, not proven governance failure: the active Work Log gate-receipt failure. `/audit` requires a report file, but does not explicitly require an active Work Log; I created one manually.
- Still likely product/tooling gaps: Windows raw `bash` misinvoke risk, deploy dry-run basename-only output, and signal-tier fixture leakage into the real workspace.
- Local-noise only unless reproduced elsewhere: existing untracked `zz-st-*` fixture files and PowerShell mojibake.

## Confirmed Findings After External Review

### LOW - Optional audit Work Logs need clearer support-receipt guidance

`/audit` says `NO GATE` and `REPORT ONLY`, while also requiring a report file under `docs/reviews/<date>-audit.md` (`.agent/workflows/audit.md:14`, `.agent/workflows/audit.md:28`). Active Work Logs, however, must contain a `## Gate Evidence` section with at least one receipt, or both validators emit `FAIL` (`.agentcortex/bin/validate.sh:1100`, `.agentcortex/bin/validate.sh:1108`, `.agentcortex/bin/validate.sh:1495`).

Second-pass correction: this failure was triggered by my choice to create an active Work Log for the audit. `/audit` itself does not explicitly require one. The validator already treats `audit` as an out-of-band support workflow for phase progression (`.agentcortex/bin/validate.sh:1263`), so the likely intended contract is: if an audit Work Log exists, support receipts are acceptable for traceability, but they do not advance the main gate state.

Recommended fix: either document that `/audit` should not create an active Work Log, or document that audit-created Work Logs must include a support-phase receipt such as `- Gate: audit | Verdict: PASS | Classification: quick-win | Timestamp: <ISO>`.

### LOW - Audit report filenames can collide on same-day repeated audits

Second-pass correction: the Work Log write was my execution choice, not a stated `/audit` requirement. The remaining real concern is narrow: `/audit` writes `docs/reviews/<date>-audit.md`, so two same-day audits can collide unless the report name includes scope/session detail.

Recommended fix: use `docs/reviews/<date>-<scope>-audit.md` or document overwrite behavior.

### MEDIUM - Windows shell validation path is easy to misinvoke

README recommends the PowerShell validator on Windows, but also presents the Git Bash equivalent as `bash ./.agentcortex/bin/validate.sh --no-python` (`README.md:245`, `README.md:258`). In this environment, PowerShell resolves `bash` to the WindowsApps WSL placeholder, causing validation to fail before Agentic OS starts.

The deploy PowerShell wrappers already contain the right mitigation by preferring Git Bash and skipping WindowsApps (`installers/deploy_brain.ps1:41`, `installers/deploy_brain.ps1:49`).

Recommended fix: change the README wording to "from a Git Bash terminal" or provide a PowerShell-safe explicit Git Bash path example. Consider documenting `validate.ps1` as the primary Windows path and making the raw `bash` example clearly non-PowerShell.

### MEDIUM - Deploy dry-run output loses target path context

The dry-run file preview uses `basename` (`.agentcortex/bin/deploy.sh:743`) and prints only the leaf filename (`.agentcortex/bin/deploy.sh:745`). The observed output included repeated names such as `rules.md` and omitted important target directories such as `installers/`.

This makes dry-run less useful as a blast-radius review tool: a user cannot tell which `rules.md` or `deploy_brain.sh` target will change without reading the deploy script.

Recommended fix: print target-relative paths and tier in dry-run output, using the same target paths passed to `deploy_file`.

### LOW - Signal-tier tests can leave formal spec fixtures in the real workspace

`tests/guard/test_signal_tier_check.py` writes fixture specs directly into `docs/specs` (`tests/guard/test_signal_tier_check.py:119`, `tests/guard/test_signal_tier_check.py:127`). If a test run is interrupted, untracked `docs/specs/zz-st-*.md` files remain and pollute later validator output. This workspace currently contains those untracked fixtures.

Recommended fix: run these validator tests in a temporary copied repository, or write fixtures under a temporary directory that the validator is pointed at, rather than the real `docs/specs` tree.

### LOW - PowerShell validator output still has mojibake in some informational lines

Full `validate.ps1` output included replacement characters in informational text such as the command-sync line and governance eval section headings. This did not affect pass/fail behavior, but it makes Windows evidence harder to review.

Recommended fix: normalize PowerShell output encoding to UTF-8 for validator child processes, or avoid non-ASCII glyphs in validator-emitted status text.

## Secondary Signals

- Governance eval coverage reports 30 MUST-rule sections without eval cases. This is WARN-only and tier-blind, but it aligns with the project's own "MUST without enforcement" lesson.
- Global Lessons count is exactly at cap: `20/20`.
- Historical archived Work Log warnings remain present; they are not new regressions from this simulation.

## Post-Fix Resolution

- Fixed: Windows validation docs now keep `validate.ps1` as the PowerShell path and mark raw `bash` as Git Bash/POSIX-only.
- Fixed: deploy dry-run now prints target-relative paths and tier labels.
- Fixed: signal-tier validator tests now write fixtures in an isolated deployed temp repo instead of source `docs/specs`.
- Calibrated: `/audit` Work Log behavior is not treated as a confirmed governance defect.
- Local hygiene: active Work Log sentinel/Resume warnings were reduced locally; remaining WARNs are shipped-active release log, historical archives, and governance eval coverage.

## routing_actions

```yaml
routing_actions:
  - finding: "Optional audit-created Work Logs need support-phase receipt guidance."
    target_doc: "docs/architecture/document-governance.md"
    status: pending
    owner: "codex-session"
  - finding: "Audit report filenames can collide on same-day repeated audits."
    target_doc: "docs/architecture/document-governance.md"
    status: pending
    owner: "codex-session"
  - finding: "Deploy dry-run preview should print target-relative paths instead of basenames."
    target_doc: "docs/architecture/document-governance.md"
    status: pending
    owner: "codex-session"
```
