mirror of
https://github.com/Dicklesworthstone/coding_agent_session_search.git
synced 2026-09-22 11:59:25 +08:00
Dicklesworthstone
66cee37273
Pulls all of the long-form evidence the project has been accumulating
into a small, named set of `docs/` subtrees and tightens `.gitignore`
plus the CI hygiene gate so freshly-generated scratch artifacts cannot
quietly become tracked again. Pure repo-hygiene change: no application
code, schema, or build behavior is touched.
New canonical locations under `docs/`:
- `docs/artifacts/` is the durable home for evidence we want to keep
reviewable in-tree: migration baselines, refactor proof bundles, the
no-mock CI audit, and per-pass simplification dashboards. A new
`docs/artifacts/README.md` documents the policy: anything under here
is curated evidence, not scratch.
- `docs/artifacts/migration-baseline/` absorbs the entire former
`.beads/migration_baseline/` tree (BASELINE_SUMMARY, SUMMARY, all
`baseline_*.{log,txt,json}` outputs, the `search_quality/*.json` and
`search_queries/q*.json` fixtures, and `binary_size.txt`) plus a new
`fs_verification.log` so the migration evidence is not buried under a
beads daemon directory.
- `docs/artifacts/refactor-runs/` collects every dated
`20260424T*` … `20260427T*` and `20260428T*` codex/repeated-simplify
pass directory that previously lived under `refactor/artifacts/`.
Every per-pass report (`pass1_*.md` … `pass10_*.md`, `DASHBOARD.md`,
`architecture.md`, `baseline.md`, plus the Twelfth/Thirteenth
twelve-pass dashboards) moves verbatim — only the path changes.
- `docs/artifacts/no-mock-audit.md` replaces
`test-results/no_mock_audit.md` as the durable copy of the no-mock
policy report; the `test-results/` directory is now treated as
ephemeral.
- `docs/assets/` becomes the project's image / screenshot home, with a
new `docs/assets/README.md`. `cass_illustration.webp`,
`gh_og_share_image.jpg`, and `screenshots/screenshot_0{1,2,3}.webp`
move out of the repo root into `docs/assets/images/` and
`docs/assets/screenshots/`.
- `docs/planning/` gains the formerly root-level
`cli-robot-enhancements.md` and the dated investigation
`2026-05-05-franken-agent-detection.md` (now under
`docs/planning/sessions/`), so all planning material is in one
predictable subtree.
- `docs/reference/E2E_LOGGING_SCHEMA.md` is added as the durable
schema definition for the JSONL E2E log, replacing inline references
to `tests/e2e/exports/setup-metadata.json` paths.
- `tests/policies/` becomes the home for machine-enforced policy
inputs. `test-results/no_mock_allowlist.json` moves to
`tests/policies/no_mock_allowlist.json` so that CI-relevant policy
files survive `test-results/` being ignored.
- `tests/performance/lighthouse-budget.json` moves to
`tests/fixtures/performance/lighthouse-budget.json` to consolidate
test inputs under `tests/fixtures/`.
Tracked-artifact hygiene (`.gitignore`):
- Search-demo data: keeps the frozen v1 index and `watch_state.json`
visible (`!tests/fixtures/search_demo_data/index/`,
`!.../watch_state.json`, `!.../v1/**`) while ignoring later
scratch generations (`v*/` minus `v1/`), `index-run.lock`, the
doctor scratch directory, and the `.lexical-publish-backups/`
staging tree.
- Test outputs: `test-results/*` is now ignored wholesale (no
per-file allowlist; durable inputs live under `tests/policies/`).
`/test-results-*.txt`, `claude-upgrade-progress.json`,
`tests/test-results/`, `tests/tests/`, `tests/e2e/exports/`,
`tests/e2e/pages_preview/`, `tests/artifacts/`, `tests/e2e/.env.test`,
and root-level `/artifacts/` and `tmp/` are all explicitly ignored.
- Local SQLite sidecars: `*.db-wal`, `*.db-shm`, `*.db-journal`,
`*.sqlite-wal`, `*.sqlite-shm`, `*.sqlite-journal`, `*.sqlite3-wal`,
`*.sqlite3-shm`, `*.sqlite3-journal` are added globally so
process-local journal files cannot leak in next to a deliberately
checked-in fixture DB. Root-level `/*.db`, `/*.db-wal`,
`/*.db-shm`, `/*.sqlite`, `/*.sqlite-wal`, `/*.sqlite-shm` follow
the same rule.
- Aider state: `.aider.chat.history.md` and friends remain ignored
globally, with an explicit
`!tests/fixtures/aider/.aider.chat.history.md` exception so the
intentional fixture survives.
- Root noise: `/cass_illustration.webp`, `/gh_og_share_image.*`,
`/screenshots/`, `/UPGRADE_LOG.md`, `/refactor/`, `/perf/`,
`/*.log`, `/*.mcp.json`, `cline.mcp.json`, `opencode.json`,
`*.mcp.json.*.bak`, and `__pycache__/` plus `.ruff_cache/` are
explicitly ignored at root so future regenerations of these
artifacts do not become tracked.
- Preserved-by-name carve-out: an explicit
`!docs/planning/MODES_OF_REASONING_REPORT_AND_ANALYSIS_OF_PROJECT.md`
re-include line guards against developer-level globals that still
match the pre-reorganization scratch filename.
Ephemeral artifact removals (now ignored):
- `.ntm/logs/am-coding_agent_session_search.log`,
`.ntm/logs/bd-coding_agent_session_search.log`,
`.ntm/logs/cm-coding_agent_session_search.log`, and
`.ntm/summaries/coding_agent_session_search-20260407-115237.json`
(~230 lines, all NTM session bookkeeping).
- `tests/e2e/.env.test` (regenerated per run).
- `tests/e2e/exports/setup-metadata.json`, `test-basic.html`,
`test-encrypted.html`, `test-large.html`, `test-no-cdn.html`,
`test-tool-calls.html`, `test-unicode.html` (~41,400 lines of
generated Playwright export HTML).
- `tests/e2e/pages_preview/bundle/{private,site}/*` — the entire
generated preview bundle (HTML, JS, CSS, payload chunk, master-key
+ integrity-fingerprint scratch). All produced by the preview build
step.
- `tests/e2e/pages_preview/db/agent_search.db{,-shm,-wal}`,
`tests/e2e/pages_preview/encrypt/{config.json,payload/chunk-00000.bin}`,
`tests/e2e/pages_preview/export/export.db`,
`tests/e2e/pages_preview/preview-server.log` (binary test DBs and
encrypt/export scratch produced by the preview server).
- `tests/tests/test-results/e2e/placeholder` (zero-byte placeholder).
Total: ~52,900 deletion lines removed, all generated test artifacts
that the new `.gitignore` patterns now block from re-entering the tree.
CI gate (`.github/workflows/ci.yml` + `scripts/validate_ci.sh`):
- A new "Run repository artifact hygiene check" step runs
`./scripts/validate_ci.sh --artifact-hygiene-only` first, before the
no-mock policy check, so the build fails fast if any of the patterns
above ever become tracked again.
- The no-mock workflow step is repointed at the new policy location
(`tests/policies/no_mock_allowlist.json`); the in-workflow
remediation guidance string in `AUDIT_REPORT` is updated to match.
- `scripts/migration_e2e_validate.sh` and `scripts/lib/e2e_log.sh`
are repointed to the new schema doc and policy paths.
- `tests/e2e/reporters/jsonl-reporter.ts` and `tests/util/e2e_log.rs`
reference the moved schema doc.
Companion docs (no behavioral change):
- `README.md` updates `<img>` `src` attributes for the project
illustration and the three TUI screenshots to point at the new
`docs/assets/...` paths, and adds a Remote Archive Safety subsection
documenting that `cass doctor`/`health`/`status` JSON treats
`remote_source_*` gaps as preservation signals (no behavior change,
doc only).
- `docs/planning/TESTING.md` adds an "Artifact hygiene check" intro
paragraph and a Doctor-V2 filesystem-portability section that names
the `CASS_TEST_DOCTOR_RENAME_FAILURE=cross-device` simulation and
the `fallback_kind: cross_device_copy_replace` evidence contract.
- `docs/planning/UPGRADE_LOG.md`, `docs/ftui_visual_parity_*` are
re-pointed at the new artifact paths.
- `tests/fixtures/README.md` and `tests/fixtures/sources/probe/README.md`
pick up the new path references.
Project Assets
This directory holds project-owned visual assets that are useful to keep in the repository but should not live in the project root.
images/cass_illustration.webpis the README hero image.images/gh_og_share_image.jpgis the GitHub/OpenGraph social preview image.screenshots/*.webpare README screenshots and FTUI visual-parity baselines.
Generated screenshots, ad-hoc exports, and local test captures should stay out of Git unless a test, README, or visual-baseline manifest explicitly depends on them.