docs(issues): file 160 - concurrent plcc-scan/plcc-make build dir race

dev-docs/issues/.next-id.txt

@@ -1 +1 @@
-160
+162

dev-docs/issues/160-concurrent-plcc-build-dir-race.md

@@ -0,0 +1,57 @@
+# 160 - Concurrent plcc-scan/plcc-make invocations race on shared build dir
+
+**Type:** fix
+**Date:** 2026-07-22
+
+## Description
+
+Running two `plcc-scan` (or presumably any plcc-ng CLI, since they all shell
+out to `plcc-make`) invocations concurrently in the same working directory
+crashes both processes with a `FileNotFoundError`. Both invocations build
+into the same `./plcc-ng/` directory using a temp file
+(`tempfile.mkstemp(..., dir=build_dir)`), and there is no locking or
+per-process isolation, so one process's cleanup/recreation of the build
+directory races with the other's attempt to write or hash its temp file.
+
+This surfaced in the plcc-ng-demo repo while comparing an in-progress
+activity spec against the solution spec using
+`diff <(plcc-scan -s activity/spec.plcc < in.txt) <(plcc-scan -s solution/spec.plcc < in.txt)`
+— a natural thing for an instructor or student to try, since the two specs
+live in sibling directories but the build directory (`plcc-ng/`) is created
+relative to the current working directory, not per-spec.
+
+Sequential invocations of the same commands work fine and produce correct,
+matching output — this is purely a concurrency/shared-state bug, not a
+scanning correctness issue.
+
+## Steps to Reproduce
+
+1. In a directory with a `spec.plcc` (or two sibling directories each with
+   their own `spec.plcc`), clear any cached build dir: `rm -rf plcc-ng`
+2. Run two invocations concurrently, e.g.:
+   ```
+   diff <(plcc-scan -s activity/spec.plcc < activity/testprog.txt) \
+        <(plcc-scan -s solution/spec.plcc < activity/testprog.txt)
+   ```
+3. One or both sides crash with:
+   ```
+   FileNotFoundError: [Errno 2] No such file or directory: '.../plcc-ng/tmpXXXXXXXX.json'
+   ```
+   traced back through `plcc-make`'s `main()` → `tempfile.mkstemp` or
+   `compute_hash`.
+4. Running the two commands sequentially (not via process substitution)
+   instead of concurrently succeeds every time.
+
+## Notes
+
+- Relevant code: `src/plcc/cmd/make.py`, `src/plcc/build/staleness.py` — the
+  shared `./plcc-ng/` build directory needs either a lock around build-dir
+  mutation, a per-invocation/per-spec temp directory, or at least a
+  graceful retry/error instead of an unhandled traceback.
+- Low severity for solo interactive use (a student typing one command at a
+  time won't hit it), but plausible for instructors/graders who script
+  comparisons, run parallel test suites, or use tools like
+  `diff <(...) <(...)` — and the failure mode is a raw Python traceback,
+  not a friendly error.
+- Originally filed as issue #2 in `ourPLCC/plcc-ng-demo`, which is where it
+  surfaced during workshop test-drive.

dev-docs/issues/161-rename-plcc-rep-to-plcc-eval.md

@@ -0,0 +1,54 @@
+# 161 - Consider renaming plcc-rep to plcc-eval for phase-naming consistency
+
+**Type:** feat
+**Date:** 2026-07-22
+
+## Description
+
+The three plcc-ng CLI tools are named inconsistently relative to the phases
+of language processing they perform:
+
+- `plcc-scan` — named after the phase (lexical analysis / scanning)
+- `plcc-parse` — named after the phase (syntactic analysis / parsing)
+- `plcc-rep` — named after the *interaction mode* (REPL), not the phase
+  (semantic analysis / evaluation)
+
+This came up while onboarding to the plcc-ng-demo repo: before reading its
+`03-semantic/README.md`, the reader guessed the third tool would be called
+`plcc-run` by analogy with a scan → parse → run pipeline, and was wrong —
+it's `plcc-rep`. `rep` names the fact that the tool loops
+read-eval-print-style, which is true, but it doesn't tell a newcomer which
+phase of language processing it belongs to, breaking the pattern the other
+two tool names establish.
+
+Renaming `plcc-rep` to `plcc-eval` would restore the pattern:
+`plcc-scan` → `plcc-parse` → `plcc-eval`, each named after its phase
+(lexical, syntactic, semantic/evaluation), with the REPL behavior remaining
+an implementation detail of how `plcc-eval` runs rather than part of its
+name.
+
+## Notes
+
+- Two ways to do this, with different classifications:
+  - **Hard rename** (drop `plcc-rep`, ship only `plcc-eval`): breaking for
+    anyone with `plcc-rep` in muscle memory, scripts, or course materials
+    (including plcc-ng-demo's `03-semantic/README.md` and
+    `solution/README.md`, which would need updating in lockstep). Not a
+    plain `feat` — needs a breaking-change marker (`feat!` / `BREAKING
+    CHANGE:` footer) so semantic-release cuts a major version, not a minor
+    one.
+  - **Alias** (keep `plcc-rep` working, add `plcc-eval` as a synonym):
+    purely additive, non-breaking — a plain `feat`. Newcomers get the
+    phase-consistent name to guess at (as happened, incorrectly, with
+    `plcc-run`), existing muscle memory and scripts keep working, and the
+    docs can migrate to `plcc-eval` as the primary name over time while
+    `plcc-rep` quietly remains as a deprecated-but-working alias.
+  - The alias approach gets most of the discoverability benefit without
+    forcing a major version bump or breaking anyone immediately — probably
+    the better starting point, with a hard rename (and removal of the
+    alias) reserved for a later major version if ever.
+- Not urgent — `plcc-rep` is accurate and "REPL" is well-understood PL
+  vocabulary — but if the project revisits CLI naming, `plcc-eval` (not
+  `plcc-run`) is the name that best matches the existing `scan`/`parse`
+  convention.
+- Originally filed as issue #5 in `ourPLCC/plcc-ng-demo`.

dev-docs/roadmap.md

@@ -2,6 +2,16 @@
 
 ## Open Issues
 
+### Fix
+
+- **[#160](issues/160-concurrent-plcc-build-dir-race.md) — Concurrent plcc-scan/plcc-make invocations race on shared build dir**
+  Two CLI invocations sharing the same `./plcc-ng/` build dir race on temp-file creation/cleanup and crash with a raw `FileNotFoundError` traceback instead of a friendly error.
+
+### Feat
+
+- **[#161](issues/161-rename-plcc-rep-to-plcc-eval.md) — Consider renaming plcc-rep to plcc-eval for phase-naming consistency**
+  `plcc-rep` is named after its interaction mode (REPL), not its phase, breaking the `scan`/`parse`/`?` naming pattern; an alias or rename to `plcc-eval` would restore it.
+
 ### Test
 
 - **[#153](issues/153-test-artifacts-outside-project-dir.md) — Test artifacts land outside the project directory**