refactor: fix make shell and cleanup Makefile

Author: alee

.agent/working-memory/session.md

@@ -1,38 +1,25 @@
 # Working Memory
 
-## Active tasks
+## Active task
 
-- Task: Plan for dynamically embedding awesome-modeling-practices README into a Hugo page
-- Current status: Plan written (see .agent/working-memory/plan-awesome-list.md)
-- Open questions: None at this stage; ready to implement on request
-- Next actions: Implement plan steps on user approval
+- awesome-modeling-practices embed plan is ready: `.agent/working-memory/plan-awesome-list.md`.
+- Next step on request: implement the planned integration.
 
-## Deployment context (updated 2026-03-28)
+## Notes by date (newest first)
 
-- Workflow: `.github/workflows/gh-pages.yml`
-- Trigger: push to `develop` branch
-- Build: containerized via Docker Compose (`docker compose build hugo` + `docker compose run hugo hugo build --gc --minify`), mirroring local deployment toolchain and image
-- Deploy method: `actions/upload-pages-artifact` + `actions/deploy-pages` (OIDC, no branch write)
-- **No `main` branch is used for deployment.** The old `peaceiris/actions-gh-pages` approach that pushed to `main` has been replaced. The `main` branch is obsolete.
-- Required repo setting: Settings → Pages → Source must be **GitHub Actions** (not "Deploy from a branch").
+### 2026-03-31
 
-## CI troubleshooting (updated 2026-03-29)
+- `Makefile` maintenance completed: fixed `make shell`, refactored shared Docker Compose flags, removed global `.NOTPARALLEL`, and simplified `clean` with a merged `find`.
+- Validation: `make -n` checks passed for `build`, `serve`, `render`, `shell`, `stop`, and `clean`.
 
-- Hugo module/cache paths inside the container must resolve to absolute directories for the current CI image/version.
-- For Docker Compose workflows, use separate variables for host and container cache paths:
-	- host path for GitHub Actions cache: `./.hugo_cache`
-	- container path for Hugo `--cacheDir`: `/src/.hugo_cache`
-- Running the container as `--user "$(id -u):$(id -g)"` avoids root-owned workspace files, but it also means default cache locations like `/cache/modules` may be unwritable.
+### 2026-03-29
 
-## Shared build entrypoint planning (updated 2026-03-29)
+- CI/cache troubleshooting: keep host cache at `./.hugo_cache` and container cache at `/src/.hugo_cache`; `--user "$(id -u):$(id -g)"` avoids root-owned files.
+- Shared build entrypoint plan: `.agent/working-memory/plan-shared-build-entrypoint.md`.
+- Checkpoint: `.agent/checkpoints/checkpoint-20260329-0824.md`.
 
-- Plan created: `.agent/working-memory/plan-shared-build-entrypoint.md`
-- Objective: route local production render, htmltest render, and GitHub Pages build through one repository-owned build script.
-- Preferred shape: keep workflow orchestration in YAML, move only the canonical Hugo build logic into a shared container-executed shell script.
+### 2026-03-28
 
-## Checkpoint and docs sync (updated 2026-03-29)
-
-- Checkpoint added: `.agent/checkpoints/checkpoint-20260329-0824.md`.
-- Contributor docs synced: `README.md` now documents shared build entrypoint and `make render`.
-- Agent docs synced: `AGENTS.md` now references `.github/scripts/build-site.sh` and local production-style render guidance.
-- Repo hygiene: `.gitignore` now ignores generated `/.hugo_cache/` and `/dist/` build outputs.
+- Deployment workflow: `.github/workflows/gh-pages.yml` on `develop`.
+- Build/deploy path: Docker Compose `hugo` service + `.github/scripts/build-site.sh`, then `actions/upload-pages-artifact` and `actions/deploy-pages`.
+- Pages source requirement: GitHub Actions (not branch deployment); no `main` branch publishing.

.github/copilot-instructions.md

@@ -5,3 +5,5 @@ This file is intentionally minimal.
 The canonical agent policy for this repository is in `AGENTS.md`.
 
 Read and follow `AGENTS.md` first, then use this file only for Copilot-specific addenda (if any).
+
+If guidance here differs from `AGENTS.md`, `AGENTS.md` takes precedence.

AGENTS.md

@@ -10,6 +10,7 @@ For a contributor-facing overview, see the Agent Harness section in [README.md](
 
 - This file defines the shared operating contract for all AI agents.
 - If guidance in `.github/copilot-instructions.md` or `CLAUDE.md` differs, follow this file.
+- `README.md` provides contributor-facing context; this file remains authoritative for agent behavior.
 - Agent-specific files should provide adapter notes only and link back here.
 
 ## Agent harness
@@ -30,7 +31,7 @@ Agent-generated artifacts must be written under `.agent/`.
 ## Command execution environment
 
 - Run project commands in containers only; do not assume local `go`, `hugo`, `node`, or `npm` are installed on the host.
-- Use Docker Compose with the `hugo` service for build/test/update tasks (for example: `docker compose run --rm hugo <command>`).
+- Use Docker Compose with the `hugo` service for build/test/update tasks (for example: `docker compose run --rm --no-deps --entrypoint sh hugo -c '<command>'`).
 - Prefer the shared Hugo production build entrypoint `.github/scripts/build-site.sh` for render operations used by CI and local production-style checks.
 - Use `make render` for the local production-style render path and `make serve` for local hot-reload preview.
 - If a command cannot run in the current container setup, document the limitation and propose a container-based alternative.

CLAUDE.md

@@ -5,3 +5,5 @@ This file is intentionally minimal.
 The canonical agent policy for this repository is in `AGENTS.md`.
 
 Read and follow `AGENTS.md` first, then use this file only for Claude-specific addenda (if any).
+
+If guidance here differs from `AGENTS.md`, `AGENTS.md` takes precedence.

Makefile

@@ -6,47 +6,40 @@
 MAKEFILES=Makefile $(wildcard *.mk)
 UID=$(shell id -u)
 GID=$(shell id -g)
+DOCKER_COMPOSE=docker compose
+HUGO_RUN_SH=$(DOCKER_COMPOSE) run --rm --no-deps --entrypoint sh
+HUGO_USER_ENV=--user "$(UID):$(GID)" -e HOME=/tmp -e npm_config_cache=/tmp/.npm -e HUGO_CACHEDIR=/src/.hugo_cache
 
 # Controls
-.PHONY : commands clean stop serve render
-.NOTPARALLEL:
+.PHONY : all commands build clean stop serve render shell
 all : commands
 
 ## commands         : show all commands.
 commands :
 	@grep -h -E '^##' ${MAKEFILES} | sed -e 's/## //g'
 
 ## build            : build files but do not run a server.
-build : 
-	docker compose build --pull
+build :
+	$(DOCKER_COMPOSE) build --pull
 
 ## serve            : start and run a local server.
 serve : build
-	@docker compose up -d
+	@$(DOCKER_COMPOSE) up -d
 
 ## render           : run the production-style site render locally.
 render : build
-	docker compose run --rm --no-deps \
-		--entrypoint sh \
-		hugo -c 'rm -f /src/.hugo_build.lock && rm -rf /src/public /src/resources/_gen'
-	docker compose run --rm --no-deps \
-		--entrypoint sh \
-		--user "$(UID):$(GID)" \
-		-e HOME=/tmp \
-		-e npm_config_cache=/tmp/.npm \
-		-e HUGO_CACHEDIR=/src/.hugo_cache \
-		hugo -c '.github/scripts/build-site.sh'
+	$(HUGO_RUN_SH) hugo -c 'rm -f /src/.hugo_build.lock && rm -rf /src/public /src/resources/_gen'
+	$(HUGO_RUN_SH) $(HUGO_USER_ENV) hugo -c '.github/scripts/build-site.sh'
 
 ## shell            : open a hugo shell
 shell : build
-	docker compose run --rm hugo shell
+	$(HUGO_RUN_SH) $(HUGO_USER_ENV) hugo
 
 ## stop             : stop the docker server and clean up
 stop :
-	docker compose down -v
+	$(DOCKER_COMPOSE) down -v
 
 ## clean            : clean up junk files.
 clean :
 	@rm -rf ./resources/_gen
-	@find . -name .DS_Store -print -exec rm {} \;
-	@find . -name '*~' -print -exec rm {} \;
+	@find . \( -name .DS_Store -o -name '*~' \) -print -exec rm {} +

README.md

@@ -12,6 +12,7 @@ This repository includes an agent collaboration harness for AI-assisted work.
 
 - Canonical policy: `AGENTS.md` is the source of truth for agent behavior.
 - Agent notes: `.github/copilot-instructions.md` and `CLAUDE.md` are adapter files that defer to `AGENTS.md`.
+- Command environment for agents: run project commands in containers via Docker Compose (`hugo` service).
 - Agent artifacts: `.agent/` stores generated working context and transfer records.
 	- `.agent/working-memory/` for in-progress notes
 	- `.agent/checkpoints/` for progress snapshots
@@ -25,7 +26,7 @@ The site is deployed to GitHub Pages via the workflow at `.github/workflows/gh-p
 
 ### How it works
 
-1. The `build` job checks out `develop`, configures the Pages base URL, then builds the site inside the same Docker Compose `hugo` service used for local development (`docker compose build hugo` + `docker compose run hugo ...`). The Hugo invocation itself is centralized in `.github/scripts/build-site.sh`, which is shared across local production-style rendering and CI workflows.
+1. The `build` job checks out `develop`, configures the Pages base URL, then builds the site inside the same Docker Compose `hugo` service used for local development (`docker compose build --pull hugo` + `docker compose run --rm --no-deps --entrypoint sh hugo -c ...`). The Hugo invocation itself is centralized in `.github/scripts/build-site.sh`, which is shared across local production-style rendering and CI workflows.
 2. The `deploy` job receives that artifact and publishes it directly to GitHub Pages via GitHub's OIDC-based Pages API (`actions/deploy-pages`).
 
 **No "built" branch is used.** The old approach pushed compiled HTML to a `main` branch using `peaceiris/actions-gh-pages`. That is no longer the case — the deployment artifact goes straight to GitHub's Pages infrastructure. The `main` branch (if it still exists in the remote) is a leftover and is no longer updated.