[lbildzinkas]

Intent

This PR implements issue #1: the project skeleton. It sets up a uv-managed Python 3.13 project that runs ruff lint and format checks, pyright type checks, and a pytest suite with one smoke test through a single documented command, locally and in GitHub Actions on every pull request and on pushes to master. It contains no agent code yet.

Closes #1

What Changed

• Set up the Python 3.13 project with uv: pyproject.toml with a committed uv.lock, hatchling src layout, and a stub src/interview_coach package (no agent code yet).
• Configure dev tooling — ruff lint and format checks, pyright type checks, and pytest with a package-import smoke test — all runnable via one command, scripts/check.sh.
• Add a GitHub Actions workflow (.github/workflows/ci.yml) that runs the same checks on every pull request and pushes to master; README documents setup and check commands, and data/personal/ and data/study-material/ are git-ignored for local-only data.

Risk Assessment

✅ Low: The change is a small, well-bounded CI/project skeleton whose three prior findings are verifiably fixed, all external references (action tags, default branch, lockfile) check out against reality, and no source-verifiable acceptance criterion remains unmet.

Testing

Drove the real check pipeline live six ways: the documented local flow passes on a synced worktree and on a pristine checkout via the CI's exact install command; all four gates plus the --locked guard adversarially fail when broken; gitignore semantics verified with real git; workflow validated by actionlint and semantic parsing against the repo's actual master default branch; reference links all resolve after fixing one dead pyright URL (committed as c2b9ddd). The only untested surface is the GitHub-hosted Actions run, which belongs to the outer executor's push/PR/CI phases.

• Live validation: ✅ go - 7 of 8 scenarios driven live against the product

Scenario	Result	Live	Evidence
A developer runs the documented setup (uv sync) and one command (./scripts/check.sh) and all checks pass	✅ pass	live	uv sync installed 10 packages from the committed lock; ./scripts/check.sh exited 0 with ruff lint, format, pyright (0 errors) and pytest (1 passed) — artifacts 02-check-sh-pass.log
Files placed in data/personal/ and data/study-material/ never appear in git status, while .gitkeep stays tracked	✅ pass	live	git check-ignore -v matched notes.md and interview-prep.pdf to .gitignore lines 20/23; git status --porcelain was empty; git ls-files data/ listed only the two .gitkeep files; .venv/.pytest_cache/.ruf…
The CI job's exact steps succeed on a pristine checkout containing only committed files	✅ pass	live	git archive HEAD copy: uv sync --locked exited 0 leaving uv.lock byte-identical, then ./scripts/check.sh exited 0 — artifacts 03/04 logs
Adversarial: introducing a lint error, a format error, a type error, or a failing test each makes ./scripts/check.sh exit non-zero at the right step	✅ pass	live	Four disposable-copy runs each exited 1 at their respective gate (ruff check, ruff format --check with lint passing, pyright, pytest) — artifact 05-adversarial-gates.log
Adversarial: uv sync --locked fails fast when pyproject.toml drifts from uv.lock and does not rewrite the lockfile	✅ pass	live	Changed pytest>=8.4 to >=8.5: uv sync --locked exited 1 with 'The lockfile at uv.lock needs to be updated, but --locked was provided'; uv.lock diff-empty afterwards
The workflow triggers on every pull request and pushes to the repo's default branch, with least-privilege permissions, running the same script as local developers	✅ pass	live	actionlint exit 0; semantic parse asserts pull_request (unfiltered) + push to [master] (matches git ls-remote --symref default branch master), contents:read, ubuntu-latest job running uv sync --locked…
Technical-reference links in code/config comments resolve for a reader studying while reviewing	✅ pass	live	All 17 distinct URLs curl-checked; the pyright configuration docs URL was 404 and was fixed to https://github.com/microsoft/pyright/blob/main/docs/configuration.md (200, commit c2b9ddd); check.sh re-p…
GitHub Actions actually runs the workflow on the pull request and on a push to master and passes	⏸️ untested	no	Driving this requires pushing the branch/PR to the real lbildzinkas/interview-coach repo and observing the Actions run, but push/PR/CI execution belongs exclusively to the outer executor's phases and…

Evidence: Local one-command checks pass (uv sync + ./scripts/check.sh)

== ruff check (lint) ==
All checks passed!
== ruff format --check (formatting) ==
3 files already formatted
== pyright (type check) ==
0 errors, 0 warnings, 0 informations
== pytest (tests) ==
============================= test session starts ==============================
platform darwin -- Python 3.13.7, pytest-9.1.1, pluggy-1.6.0
rootdir: ~/.no-mistakes/worktrees/94024bdabd59/01M3PKYDGN6JGHYW4Y45VYSY6T
configfile: pyproject.toml
testpaths: tests
collected 1 item

tests/test_smoke.py .                                                    [100%]

============================== 1 passed in 0.00s ===============================

Evidence: CI job replay: uv sync --locked on pristine checkout (lockfile unchanged)

Using CPython 3.13.7 interpreter at: /opt/homebrew/opt/python@3.13/bin/python3.13
Creating virtual environment at: .venv
Resolved 11 packages in 4ms
   Building interview-coach @ file://~/.no-mistakes/worktrees/94024bdabd59/01M3PKYDGN6JGHYW4Y45VYSY6T/.ci-sim
      Built interview-coach @ file://~/.no-mistakes/worktrees/94024bdabd59/01M3PKYDGN6JGHYW4Y45VYSY6T/.ci-sim
Prepared 1 package in 190ms
Installed 10 packages in 57ms
 + iniconfig==2.3.0
 + interview-coach==0.1.0 (from file://~/.no-mistakes/worktrees/94024bdabd59/01M3PKYDGN6JGHYW4Y45VYSY6T/.ci-sim)
 + nodeenv==1.11.0
 + packaging==26.3
 + pluggy==1.6.0
 + pygments==2.21.0
 + pyright==1.1.414
 + pytest==9.1.1
 + ruff==0.16.9
 + typing-extensions==4.16.0

Evidence: CI job replay: ./scripts/check.sh passes on pristine checkout

== ruff check (lint) ==
All checks passed!
== ruff format --check (formatting) ==
3 files already formatted
== pyright (type check) ==
0 errors, 0 warnings, 0 informations
== pytest (tests) ==
============================= test session starts ==============================
platform darwin -- Python 3.13.7, pytest-9.1.1, pluggy-1.6.0
rootdir: ~/.no-mistakes/worktrees/94024bdabd59/01M3PKYDGN6JGHYW4Y45VYSY6T/.ci-sim
configfile: pyproject.toml
testpaths: tests
collected 1 item

tests/test_smoke.py .                                                    [100%]

============================== 1 passed in 0.00s ===============================

Evidence: Adversarial: each check gate fails on its own error class; uv sync --locked refuses drift

=== adversarial gate runs (in pristine .ci-sim copy) ===
--- run 1 exit code ---
--- run 2 exit code ---
--- run 3 exit code ---
--- run 4 exit code ---
\### Adversarial: each check gate fails when its error class is introduced (pristine .ci-sim copy)

## Run 1: lint error (unused import) -> EXIT 1
== ruff check (lint) ==
F401 [*] `os` imported but unused
 --> tests/test_bad_lint.py:1:8
  |
1 | import os
  |        ^^
help: Remove unused import: `os`
  |
  - import os
  |

Found 1 error.
[*] 1 fixable with the `--fix` option.

## Run 2: format error (single quotes; lint passes) -> EXIT 1
== ruff check (lint) ==
All checks passed!
== ruff format --check (formatting) ==
unformatted: File would be reformatted
 --> tests/test_bad_fmt.py:3:24
  |
2 |     greeting = "hi"
  -     assert greeting == 'h'
3 +     assert greeting == "h"
  |

1 file would be reformatted, 3 files already formatted

## Run 3: type error (passes ruff) -> EXIT 1
== ruff check (lint) ==
All checks passed!
== ruff format --check (formatting) ==
4 files already formatted
== pyright (type check) ==
~/.no-mistakes/worktrees/94024bdabd59/01M3PKYDGN6JGHYW4Y45VYSY6T/.ci-sim/tests/test_bad_type.py
  ~/.no-mistakes/worktrees/94024bdabd59/01M3PKYDGN6JGHYW4Y45VYSY6T/.ci-sim/tests/test_bad_type.py:2:18 - error: Type "Literal['not an int']" is not assignable to declared type "int"
    "Literal['not an int']" is not assignable to "int" (reportAssignmentType)
1 error, 0 warnings, 0 informations

## Run 4: failing test (passes ruff+pyright) -> EXIT 1
== ruff check (lint) ==
All checks passed!
== ruff format --check (formatting) ==
4 files already formatted
== pyright (type check) ==
0 errors, 0 warnings, 0 informations
== pytest (tests) ==
============================= test session starts ==============================
platform darwin -- Python 3.13.7, pytest-9.1.1, pluggy-1.6.0
rootdir: ~/.no-mistakes/worktrees/94024bdabd59/01M3PKYDGN6JGHYW4Y45VYSY6T/.ci-sim
configfile: pyproject.toml
testpaths: tests
collected 2 items

tests/test_bad_test.py F                                                 [ 50%]
tests/test_smoke.py .                                                    [100%]

=================================== FAILURES ===================================
_________________________________ test_failing _________________________________

    def test_failing() -> None:
>       assert 1 == 2, "intentional failure"
E       AssertionError: intentional failure
E       assert 1 == 2

tests/test_bad_test.py:2: AssertionError
=========================== short test summary info ============================
FAILED tests/test_bad_test.py::test_failing - AssertionError: intentional fai...
========================= 1 failed, 1 passed in 0.01s ==========================

## Run 5: uv sync --locked with drifted pyproject -> EXIT 1, lockfile not rewritten
Resolved 11 packages in 122ms
The lockfile at `uv.lock` needs to be updated, but `--locked` was provided. To update the lockfile, run `uv lock`.

Evidence: Workflow semantic assertions (triggers, permissions, job steps) after actionlint passed

workflow semantic assertions PASSED:
  triggers: pull_request (unfiltered) + push to ['master']
  job 'checks' on ubuntu-latest: ['actions/checkout@v7', 'astral-sh/setup-uv@v10'] then ['uv sync --locked', './scripts/check.sh']
  permissions: {'contents': 'read'}
  CI runs the exact same script as local developers: ./scripts/check.sh

Evidence: HTTP status of every technical-reference link (one 404 fixed, re-checked 200)

200 https://docs.astral.sh/ruff/
200 https://docs.astral.sh/ruff/rules/
200 https://docs.astral.sh/uv/
200 https://docs.astral.sh/uv/concepts/projects/
200 https://docs.astral.sh/uv/concepts/projects/#dependency-groups
200 https://docs.astral.sh/uv/reference/cli/#uv-sync
200 https://docs.github.com/en/actions
200 https://docs.pytest.org/
200 https://docs.pytest.org/en/stable/
200 https://docs.pytest.org/en/stable/how-to/cache.html
200 https://docs.pytest.org/en/stable/reference/reference.html#ini-options
200 https://github.com/actions/checkout
200 https://github.com/astral-sh/setup-uv
200 https://hatch.pypa.io/latest/config/build/#packages
200 https://microsoft.github.io/pyright/
404 https://microsoft.github.io/pyright/docs/configuration/

## Fixed link now 200: https://github.com/microsoft/pyright/blob/main/docs/configuration.md

- Outcome: ⚠️ 1 info across 1 run (5m3s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 3 issues found → auto-fixed ✅

• ⚠️ .gitignore:13 - gitignore has no trailing comments: everything after the pattern is literal, so .pytest_cache/ # pytest https://... (line 13) and .ruff_cache/ # ruff https://... (line 14) are broken patterns. Verified with git check-ignore: paths like .pytest_cache/foo and .ruff_cache/foo are NOT ignored, so the first run of ./scripts/check.sh leaves both cache dirs untracked and committable. Fix: move each comment onto its own line above the pattern.
• ⚠️ .github/workflows/ci.yml:7 - The push trigger targets branches: [main], but git ls-remote --symref https://github.com/lbildzinkas/interview-coach.git HEAD shows the repository's default and only branch is master, so the push half of this workflow can never fire — the 'runs on pushes to main' acceptance criterion is dead in this repo as it exists. The issue text says 'pushes to main' verbatim while repo reality is master, so the remedy needs your decision: either change the filter to [master] (or drop it) and update README.md's matching 'on pushes to main' wording, or rename the repo's default branch to main. Note the pull_request trigger is unfiltered, so CI on this PR itself is unaffected.
• ℹ️ .github/workflows/ci.yml:26 - uv sync without --locked will silently re-resolve and rewrite uv.lock in CI if pyproject.toml ever drifts from it, contradicting the README's promise that everyone (including CI) gets versions pinned by the committed lock. uv sync --locked fails fast instead; scripts/check.sh's implicit uv run syncs would then also stay consistent since the install step already validated the lock.

🔧 Fix applied.
✅ Re-checked - no issues remain.

⚠️ **Test** - 1 info

• ℹ️ pyproject.toml:44 - The [tool.pyright] comment linked to https://microsoft.github.io/pyright/docs/configuration/, which returns 404 (the pyright docs site was restructured; its /docs/ subtree is gone). This broke the issue's acceptance criterion that config comments link to working technical references. Found during link validation, fixed in this phase (commit c2b9ddd) by pointing to the canonical current reference https://github.com/microsoft/pyright/blob/main/docs/configuration.md (verified 200); all 17 reference links in the change now resolve and ./scripts/check.sh still passes.
• Live validation: ✅ go - 7 of 8 scenarios driven live against the product

Scenario	Result	Live	Evidence
A developer runs the documented setup (uv sync) and one command (./scripts/check.sh) and all checks pass	✅ pass	live	uv sync installed 10 packages from the committed lock; ./scripts/check.sh exited 0 with ruff lint, format, pyright (0 errors) and pytest (1 passed) — artifacts 02-check-sh-pass.log
Files placed in data/personal/ and data/study-material/ never appear in git status, while .gitkeep stays tracked	✅ pass	live	git check-ignore -v matched notes.md and interview-prep.pdf to .gitignore lines 20/23; git status --porcelain was empty; git ls-files data/ listed only the two .gitkeep files; .venv/.pytest_cache/.ruf…
The CI job's exact steps succeed on a pristine checkout containing only committed files	✅ pass	live	git archive HEAD copy: uv sync --locked exited 0 leaving uv.lock byte-identical, then ./scripts/check.sh exited 0 — artifacts 03/04 logs
Adversarial: introducing a lint error, a format error, a type error, or a failing test each makes ./scripts/check.sh exit non-zero at the right step	✅ pass	live	Four disposable-copy runs each exited 1 at their respective gate (ruff check, ruff format --check with lint passing, pyright, pytest) — artifact 05-adversarial-gates.log
Adversarial: uv sync --locked fails fast when pyproject.toml drifts from uv.lock and does not rewrite the lockfile	✅ pass	live	Changed pytest>=8.4 to >=8.5: uv sync --locked exited 1 with 'The lockfile at uv.lock needs to be updated, but --locked was provided'; uv.lock diff-empty afterwards
The workflow triggers on every pull request and pushes to the repo's default branch, with least-privilege permissions, running the same script as local developers	✅ pass	live	actionlint exit 0; semantic parse asserts pull_request (unfiltered) + push to [master] (matches git ls-remote --symref default branch master), contents:read, ubuntu-latest job running uv sync --locked…
Technical-reference links in code/config comments resolve for a reader studying while reviewing	✅ pass	live	All 17 distinct URLs curl-checked; the pyright configuration docs URL was 404 and was fixed to https://github.com/microsoft/pyright/blob/main/docs/configuration.md (200, commit c2b9ddd); check.sh re-p…
GitHub Actions actually runs the workflow on the pull request and on a push to master and passes	⏸️ untested	no	Driving this requires pushing the branch/PR to the real lbildzinkas/interview-coach repo and observing the Actions run, but push/PR/CI execution belongs exclusively to the outer executor's phases and…

• uv sync (verbatim README flow) then ./scripts/check.sh in the worktree — all four checks pass, exit 0
• git check-ignore -v with scratch files in data/personal/, data/study-material/, .venv, .pytest_cache, .ruff_cache; git status --porcelain empty; git ls-files data/ shows only .gitkeep files
• Pristine-checkout CI replay: git archive HEAD into .ci-sim, uv sync --locked (lockfile byte-identical after), ./scripts/check.sh — exit 0
• Adversarial gates in the disposable copy: unused import -> exit 1 at ruff check; single-quoted string -> exit 1 at ruff format --check (lint passed); int/str mismatch -> exit 1 at pyright; failing assert -> exit 1 at pytest
• Adversarial lock guard: sed pyproject to pytest>=8.5, uv sync --locked -> exit 1 with 'lockfile needs to be updated', uv.lock not rewritten
• actionlint .github/workflows/ci.yml — exit 0; YAML parsed via PyYAML and asserted: pull_request (unfiltered) + push to [master], contents:read permission, ubuntu-latest job running uv sync --locked then ./scripts/check.sh after checkout@v7 and setup-uv@v10 (Python 3.13)
• HTTP link validation of all reference URLs in changed files (one 404 found and fixed; re-checked 200); ./scripts/check.sh re-run after fix — exit 0
• gh run list --repo lbildzinkas/interview-coach (read-only) — no runs exist yet; remote HEAD default branch confirmed master

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.