Files

T

veronica f0d2dd9920 docs(W4): stamp kind and status front matter on 104 live documents

Applies the document contract from
docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md section 3, partially:
`kind` and `status` only. `parent` is deliberately held until the flatten in
section 4 lands, so that 127 documents do not have to be re-pointed by hand
when docs/fleet/NORTH_STAR.yaml moves to docs/NORTH_STAR.yaml.

Scope, measured on origin/next at 63069149:

  127 live docs   = all *.md under docs/ minus docs/archive/ minus docs/_old_structure/
  104 stamped     here
   19 held        operator judgement (plan section 9), worklist in the same PR
    3 held        the SUPERSEDED TASKS.md stamps, which cite the moving path
    1 untouched   docs/fleet/FLEET-DOCTRINE.md, already stamped in W1

Kinds applied: 54 guide, 34 record, 9 spec, 6 tracking, 1 projection.
Every row carries a confidence and a one-line rationale in the worklist.

Two collisions with the existing state, both flagged rather than resolved:

1. docs/README.md:150-160 already documents a front-matter convention
   (title/type/audience/status/source_of_truth) with its own allowed values.
   It is applied to 4 of 127 files. Its `status` vocabulary is
   current|draft|deprecated|historical; the new contract's is active|superseded-by.
   The key collides. This commit lets the new contract win and rewrites
   `status: current` to `status: active` on those 4 files, keeping their other
   legacy keys untouched. No code reads any of them: `git grep source_of_truth`
   outside docs/ returns nothing. docs/README.md still prescribes the old
   convention and is an operator row, so it is not edited here.

2. Two of the plan's 20 operator rows are YAML files, not markdown
   (docs/fleet/examples/roster-v2.yaml, docs/openapi-tess.yaml), and the
   contract's front-matter form has no defined meaning for a .yaml document.
   That gap also applies to docs/fleet/NORTH_STAR.yaml, the source of truth
   itself. Raised in the worklist.

A third row from the plan, docs/fleet/north-star.md, no longer exists: W1
renamed it to docs/fleet/FLEET-DOCTRINE.md.

Verification: 104/104 parse with the expected kind and status in front matter;
the check was shown to reject a wrong kind before it was trusted. The diff
removes 4 lines total, all of them `status: current`.

2026-08-20 19:30:25 -05:00

8.7 KiB

Raw Blame History

kind, status

kind	status
record	active

#1174 — Wrapper guard rounds 10–11

Objective

Make checkout enforcement judge Git placement operands rather than every HOME-shaped word in the command, without reopening --separate-git-dir placement under HOME.

Plan

Reproduce the four over-blocks and the placement-option control at head 20d86e39.
Add RED fixtures before production changes.
Extract clone/worktree placement operands from the existing shell-aware normalized stream.
Run the full guard corpus, historical-head discrimination, syntax/static checks, probes, review, and CI.

Progress and evidence

Reproduced: NOTE=$HOME, --reference=$HOME, GIT_DIR=$HOME/x, and --template=$HOME/t all blocked despite explicit /src/wt destinations.
RED at 20d86e39: expanded suite had 8 failures, all HOME-valued non-placement cases.
GREEN: expanded suite passes 242/242.
Round-10 probes: 7/7 placement expectations and 4/4 placement-option controls pass.
Earlier path probes remain green: 60/60, 24/24, and 17/17.
Historical discrimination with the 242-fixture suite:
- 3d0a882a: 216 pass / 26 fail.
- 4b8eba95: 222 pass / 20 fail.
- 20d86e39: 234 pass / 8 fail.
bash -n, ShellCheck warning-or-higher, and git diff --check: pass.

Residual / risk

Relative destinations whose effective path depends on cwd are tracked separately by #1197 and remain out of scope.
Unknown future Git options with a separate following value fail closed when that value is HOME-shaped. This may require classification when Git adds an unrelated path-taking option, but prevents a new placement option from silently bypassing the guard.

Round 11 objective and intake

Issue / PR: #1174.
Objective: Remove the finite boolean-flag allowlists that turn accepted clone/worktree flags into fake placement operands, while preserving all real HOME placement blocks.
Scope: wrapper-guard.sh, its hermetic fixtures, and task documentation. Relative cwd-dependent destinations remain in #1197.
Surfaces: security-sensitive Bash hook behavior and shell/Git option grammar; no API, DB, UI, auth, deploy, or dependency changes.
Budget assumption: 25K working tokens; reduce exploratory matrices before reducing acceptance coverage.

Round 11 plan

Use Git itself to classify accepted/rejected clone and worktree options, and Bash itself to resolve path-word expectations.
Add RED fixtures for all six reported clone flags, generated negations, and equivalent worktree grammar.
Replace the open-ended unknown-option fail-closed fallback with a parser based on the closed value-taking option surface; keep explicit placement options special.
Run the full corpus, historical discrimination, shell/static checks, targeted probes, independent code/security review, one push, and exact-head CI.

Root-cause evidence

Git 2.39.5 accepts all six reported clone flags and the broader generated family measured in the brief: --bare, --mirror, --ipv4, --ipv6, -4, -6, --no-local, --no-reject-shallow, --no-bare, --no-sparse, --no-dissociate, --no-shallow-submodules, --no-quiet, --no-progress, and --no-recurse-submodules; it rejects --relative-paths as unknown.
Git 2.39.5 accepts worktree negations including --no-force, --no-detach, --no-lock, --no-guess-remote, and --no-track; the current finite worktree flag list does not describe that generated family.
bash -c "printf '%s' <word>" resolves $HOME/source, ${HOME}/source, and "$HOME"/source under HOME while /src/wt remains outside it.
Hypothesis: only separate-value options need positive classification. Treat every other option token as a no-value flag unless it is the explicit placement option; this matches Git's non-enumerable boolean family and confines the residual to genuinely new future value-taking options.

TDD and verification checkpoints

RED against the unmodified 91cc37bc guard: 253 pass / 22 fail in the initial expanded 275-fixture suite. Failures include all 15 accepted clone flags, accepted long abbreviations, short value-taking bundles, abbreviated placement, worktree metadata abbreviation, and both directions of bundled worktree branch parsing.
An exploratory fail-closed residual test drove emission of every worktree positional. Re-review correctly showed that this over-blocked HOME-shaped commit-ish metadata; a new commit-ish fixture failed RED against that intermediate implementation (278 pass / 2 fail, including one transient message assertion) and the parser was restored to emit only the actual path.
GREEN after remediation: 280/280.
Ultron's 13-shape option probe: 13/13 correct, including the six reported over-blocks, HOME destinations, end-of-options, worktree controls, and a later-command placement.
Round-10 probes remain green: 7/7 subject-placement expectations and 4/4 --separate-git-dir controls.
Earlier shell/path probes remain green: 60/60, 24/24, and 17/17.
bash -n, ShellCheck warning-or-higher, and git diff --check: pass.

Deliberate residual

A future Git release could add a new separate-value option absent from the closed value grammar. It defaults to no-value flag parsing, which leaves the following word positional. For clone, this can fail open if that future option itself creates repository state at its value. For worktree, it can shift which word is read as the path. This hypothetical future ambiguity is accepted deliberately because failing closed on every unclassified option is proven to over-block Git's open-ended present-day boolean/--no-* family. Every value-taking and placement option Git currently supports is classified, including accepted abbreviations of --separate-git-dir. Relative cwd-dependent targets remain in #1197.

Independent review checkpoint

Initial Codex code/security review raised --orphan as value-taking. Upstream Git master contradicts that premise: the synopsis is [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>], and the prose derives the branch from the path when -b/-B is absent. --orphan is therefore correctly handled as a boolean flag.
The security review separately identified the generic future worktree shift residual. An attempted fail-closed remediation emitted every positional, but code re-review correctly rejected it because valid grammar has only one placement positional and an optional commit-ish. Final behavior checks only the path and documents the hypothetical future option shift deliberately; paired actual-grammar --orphan fixtures cover safe/HOME paths and -b metadata.
Security re-review initially had no findings. Code re-review's commit-ish blocker was remediated with a RED fixture and path-only restoration; final code re-review approved with no findings.
Final security review then found non-canonical absolute and symlink aliases. Eight lexical fixtures failed RED against the prior implementation, followed by three symlink fixtures failing RED. Remediation expands only shell-visible HOME tokens, resolves the longest existing directory prefix physically, and lexically normalizes the nonexistent suffix. The suite is now 292/292.
Inherent residual: a symlink can be replaced between pre-tool inspection and Git execution. Existing aliases are resolved; eliminating the race requires enforcement inside the filesystem mutation path rather than a text pre-hook. Security review classified this medium, and architectural closure is tracked in #1199.
Final independent code review: APPROVE, 0 findings. Final security review: no critical/high findings; the single medium TOCTOU residual is explicitly tracked in #1199.

Final local evidence

Final hermetic suite: 292/292; the same suite against 91cc37bc discriminates at 256 pass / 36 fail.
Ultron option probe: 13/13; round-10 probes: 7/7 plus 4/4 controls; earlier shell/path probes: 60/60, 24/24, and 17/17.
bash -n, ShellCheck warning-or-higher, git diff --check, sanitization gate, and test-enumeration gate (population 55; 38 enumerated; 18 signed exclusions): pass.
Independent code review: APPROVE, 0 findings. Security review's remaining medium TOCTOU architecture residual is tracked in #1199; no critical/high findings remain.
Repository-wide TypeScript gates require dependencies absent from this worktree; the canonical Woodpecker pipeline will run them against the pushed exact head.

Documentation checklist

docs/PRD.md updated with WPG requirements, acceptance, canonicalization, and residual risk.
Task scratchpad updated in the same logical change set; docs/TASKS.md remains orchestrator-only.
No API, auth, UI, navigation, deployment, user-guide, or admin-guide surface changed; OpenAPI, endpoint index, sitemap, and publishing are not applicable.

8.7 KiB Raw Blame History Unescape Escape