DanMcInerney / DanMcInerney/architect-loop

multi-run docs-finish: product docs + solutions

Open
#92 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
627
Forks
54
PR merge metrics
No merged PRs in 30d

Description

Finish-boundary docs job for run multi-run (spec: docs/spec/multi-run.md, tracking issue #89). Consume docs debt, update product docs. No cold judge (human-ruled exception): the orchestrator grades checkrun evidence directly.

## Change-context digest

- #90 s1 (merged c6a3821, 11 files +1054/-107): status scripts run-pinned. Signature `status.ps1 [] [-RepoRoot ]` / `status.sh [] [--repo-root ]`; TRACK from `docs/runs//manifest.md` (never a tracker-wide max); SUB rows = parent edge + authenticated-author filter; `STATUS_GH_STUB` now stubs raw pre-filter records, `STATUS_GH_LOGIN_STUB` stubs the login; no slug + one ACTIVE manifest auto-selects, multiple ACTIVE lists `RUN # ` lines; display paths run-namespaced. Fixtures: tests/fixtures/status-run-pinned/.
- #91 s2 (merged 1ae275d, 4 files +306/-63): skill text pins runs. Manifest frontmatter (`run`, `tracking-issue`, `factory-branch`, `tracker`, `spec`, `state`, `created`); run marker `` in every run issue body; foreign sub-issue rule (wrong author or missing marker -> never dispatched, digest escalation); per-run namespaces `docs/checks//`, `docs/jobs//`, `docs/issues//` (per-run numbering), `job//` branches, `.architect/wt//` worktrees; one checkout per live run (`.architect/runs/` convention); `docs/STOP` global kill-all + `docs/runs//STOP` per-run stop (never committed; `.gitignore` has `!/docs/runs/` + `/docs/runs/*/STOP`).
- Rulings files: docs/jobs/multi-run/s1-scripts-rulings.md (run-marker check is a dispatch-time orchestrator duty, not the status emitter's), docs/jobs/multi-run/s2-skilltext-rulings.md (docs/jobs bookkeeping exemption; sibling-owned scripts).
- Domain language: run, run slug, run manifest, run marker, foreign issue, run checkout. The word "sentinel" is validator-retired for skill text; DESIGN.md may quote it as history.
- Run evidence worth recording in DESIGN.md: pre-freeze grill caught the validator-retired term before it wedged the run and an unenforced acceptance criterion; postflight lessons below; live smoke: `status.ps1 multi-run` printed `tracker: #89` from the manifest pin with both sub-issues merged.

## What to write

1. README.md: document multi-run isolation where usage/config already live - run manifests under `docs/runs/`, status run-slug argument, per-run stop file, concurrent runs each in their own worktree. PRESERVE the human-directed product-page shape (tagline/usage/design/details/config/license), the hand-written SVG diagrams in assets/, the Details quality|token-savings tags, and the Config section as the only ini example. Extend; do not restructure.
2. DESIGN.md: add the multi-run design rationale + evidence (pin-don't-scan, why manifest over labels, foreign-issue immunity, per-run stop) with this run's evidence.
3. docs/solutions/postflight-lane-commit.md: the orchestrator MUST commit the builder's worktree changes onto the job branch before postflight; symptom of skipping = POSTFLIGHT: ERROR exit 5 with an untouched factory head (merge was a no-op against the freeze SHA).
4. docs/solutions/worktree-cleanup-locks.md: worktree removal failure modes seen live - relative `worktree` config paths resolve against the script cwd and silently skip removal; the orchestrator shell's own cwd inside a worktree blocks deletion; lingering codex child processes hold the directory (search by command signature, kill, retry; piecemeal child deletion isolates the holder).

## Acceptance

Frozen check: docs/checks/multi-run/docs-finish.md (read-only; editing it fails the job).
Report path: docs/jobs/multi-run/docs-finish-01.md (raw evidence only, one STATUS line).

## Boundaries

- MAY TOUCH: README.md, DESIGN.md, new files under docs/solutions/.
- MUST NOT TOUCH: anything under docs/checks/, skills/, tests/, installers, docs/spec/, docs/runs/.
- Out of scope: skill text, scripts, new features.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading the frozen check at docs/checks/multi-run/docs-finish.md, then compare README.md and DESIGN.md with the multi-run evidence in the issue. Update README.md, DESIGN.md, and the two named files under docs/solutions/ without touching the forbidden paths; confirm the documented status, stop-file, worktree, and postflight behavior matches the evidence and record raw results in docs/jobs/multi-run/docs-finish-01.md.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.