[codex] Harden pyc5 build flow and add CI gates

[zhoubot]

Summary

• harden the pyc5 timed-domain build path so pycircuit.cli build accepts both supported entrypoint forms, resolves public probe targets correctly, invalidates stale JIT cache artifacts after frontend changes, and keeps StateSignal recurrence reads on the current logical occurrence
• add focused unit and system pytest coverage for those behaviors, plus a smoke test around the semantic regression script
• add GitHub Actions CI, pre-commit, markdown lint, Python formatting/lint hooks, contributor workflow docs, and GitHub issue/PR templates that match the actual pyCircuit review process

Decision / Contract Impact

• Decision IDs: 0010
• Contract areas touched:
  • pyc5 public build entrypoints
  • cycle-aware state/read semantics
  • probe target naming and manifest generation
  • JIT cache invalidation behavior
  • contributor workflow, gate matrix, and CI expectations

Root Cause

The timed-domain lane still had a few gaps relative to the current pyc5 contract:

• the CLI/JIT path treated domain like a user JIT parameter instead of a framework-owned timed-domain argument
• probe target base-name resolution did not honor __pycircuit_name__
• cached frontend artifacts could survive compiler edits because the frontend package content was not part of the cache key
• StateSignal arithmetic/comparisons were still reading from the original occurrence, which could synthesize bogus balance registers in recurrences like q.set(q + 1, when=en)

Validation

Commands run:

• export PYTHONPATH=compiler/frontend; . .venv-ci-mini/bin/activate; pytest tests/unit -m unit
• export PYTHONPATH=compiler/frontend; export PYC_TOOLCHAIN_ROOT=$PWD/.pycircuit_out/toolchain/install; . .venv-ci-mini/bin/activate; pytest tests/system -m system
• mkdocs build
• PYTHONPATH=compiler/frontend python3 flows/tools/check_api_hygiene.py compiler/frontend/pycircuit designs/examples/digital_filter designs/examples/trace_dsl_smoke designs/examples/bundle_probe_expand docs/development README.md CONTRIBUTING.md
• PYC_GATE_RUN_ID=20260402-pr-continue PYTHONPATH=compiler/frontend PYC_TOOLCHAIN_ROOT=$PWD/.pycircuit_out/toolchain/install bash flows/scripts/run_semantic_regressions_v40.sh

Evidence paths:

• docs/gates/logs/20260402-pr-continue/

Documentation

Docs updated:

• README.md
• CONTRIBUTING.md
• docs/development/index.md
• docs/development/contributing-workflow.md
• docs/development/testing-and-gates.md
• docs/development/review-and-merge.md
• AGENTS.md
• .github/PULL_REQUEST_TEMPLATE.md
• .github/ISSUE_TEMPLATE/*

Risk / Compatibility

• User-visible impact:
  • timed-domain tops now build through the supported public CLI path without leaking domain into JIT param collection
  • cycle-aware recurrences no longer synthesize bogus balancing state in the covered cases
  • CI now enforces changed-file quality checks, unit tests, docs build, Linux system smoke, and wheel smoke
• Remaining risk:
  • the repo still has unrelated historical API-hygiene backlog outside this change set, so full-repo pre-commit run --all-files is not yet the routine path
  • this PR does not attempt a repo-wide cleanup of older examples/tutorials that still reference removed APIs

Related Issues

• Fixes #

[gemini-code-assist]

Code Review

This pull request transitions the repository to the pyc5 frontend surface, introducing updated contributor workflows, pre-commit hooks, and comprehensive documentation. Key technical changes include enhancing the JIT evaluator to support v5 cycle-aware and state signals, and refining StateSignal logic to ensure reads are rebased to the current logical occurrence, thereby preventing unnecessary balance registers. New system and unit tests have been added to validate CLI entrypoints and v5 semantics. Feedback highlights a missing rebase in the StateSignal indexer and suggests implementing reverse subtraction to remove a current JIT limitation.