Why: The approved contract requires exactly three safe attempts for Cursor, agy, and PI, then one Codex emergency attempt, never host implementation authority.
Evidence: Routing/config tests were RED for never, max attempts, forbidden adapters, and legacy host fallback; 133 related tests now pass with one opt-in probe skipped.
Impact: Normal emergency-mode roles reject all non-Cursor/agy/PI adapters, project fallback is never, and Codex remains available through emergency/review paths.
Refs: independent Codex review of feature/agent-cli-enforcement
Why: Agents must use configured CLIs for implementation and testing, while remaining free to inspect, plan, test, and iterate within bounded scope.
Evidence: Task-card contract tests and the full 430-test governance discovery pass with 19 existing skips; diff-check passes.
Impact: Defines three safe attempts per normal CLI, one emergency Codex attempt, fail-stop terminals, and mandatory apply/admit integration.
Refs: feature/agent-cli-enforcement
Why: Ensure implementation authorship is delegated per unit while the primary model remains responsible for planning and delivery management.
Evidence: The focused task-card generation regression went red then green, and git diff --check passed.
Impact: Every repository-writing implementation unit gets a fresh Cursor CLI run; unavailable or failed Cursor work is recorded as a blocker instead of being silently implemented by the primary model.
Refs: .task/feature-goal-first-delivery.md
Why: Keep authorized work focused on its stated outcome, prevent private scope expansion, and remove mechanical human stage gates.
Evidence: make test-governance passed 344 tests with 18 environment-dependent skips; receipt is recorded in the task card.
Impact: New tasks use goal-first execution while retaining real decision points, independent review, evidence, platform admission, and high-consequence dual keys.
Refs: .task/feature-goal-first-delivery.md
Why: card_merge only recognized "Merge ... from <branch> into main"
merge commits, so a PR landed as a squash (real case: #457) left its
task card in .task/ forever; task-close reported nothing to close and
precheck showed no debt. Closing required a manual backfill (PR #541).
Evidence: card_merge now returns sha|subject|pr and falls back to a
Gitea API lookup by head ref or label (deleted branches keep the
original name only in label), gated by merge_commit_sha ancestry in
origin/main; precheck [cards] reuses card_merge so both surfaces agree.
Live probe against production Gitea returns 226a4af15791|Reset
per-service runtime state in svc.sh env_config|457 for
feature/svc-pidcheck-leak; stub-server tests cover squash landing,
decoy skip and the not-on-main refusal; full governance suite follows
in-card evidence.
Impact: scripts/task.sh close and precheck detect squash-merged cards
when GITEA_TOKEN is set (merge-commit path unchanged without token);
tests/test_task.py adds two regressions; no protocol change for
existing merge-commit closures beyond the appended pr field.
Refs: card-merge-misses-squash-merges (memory); PR #541 manual closure.
Why: F2 token extraction predates the two-section (HOME/IMC) layout of
~/.secrets/gitea so it concatenated both tokens and always failed; F6
registered a grep BRE alternation that facts-verify unescapes into a
literal pipe, failing re-verification and misaligning precheck's naive
pipe split into a spurious F6 date-format expiry warning, while both
underlying facts still hold.
Evidence: make facts-verify now 6/6 PASS with last_verified refreshed
to 2026-10-14; new regression test for escaped pipes in facts rows;
full governance suite 342 tests OK (18 skipped); precheck [facts] line
reports all facts fresh on the fixed parser.
Impact: policy/facts.md F2 (HOME-section awk extraction) and F6
(negated pipe-free grep); scripts/task.sh precheck neutralizes escaped
pipes the same way facts-verify does; tests/test_task.py covers it.
Refs: precheck WARN 过期事实 F6(日期格式); AGENTS.md 证据与验证门禁.
Why: pipefail treated a recent merged-card match as a failed git log after grep exited early, hiding completed cards from precheck and task-close.
Evidence: A disposable long-history regression failed before the fix and passed after it; make test-governance passed 341 cases. Git history confirms PR #489/#488/#486 merge SHAs.
Impact: Detect merged cards reliably and archive only the three authorized trial cards; four unrelated eligible cards remain untouched.
Refs: Dev merge queue #518; Dev #489, #488, #486
Why: agents need consistent entrypoints and recording defaults to avoid retrying synchronization and CI outside the final delivery window.
Evidence: SELF generated-task-card red-green regression and governance suite recorded through make evidence; pending shared record created as Issue #518.
Impact: rules, task template and capability matrix stay explicit about pending activation, default strict startup, manual coordination and unchanged CI triggers.
Refs: U4; policy/merge-queue.md; .task/feature-merge-queue-policy-draft.md
Why: an existing authorized task should not merge a moving target merely to resume local work, while new task startup and delivery remain strict.
Evidence: SELF red-green recovery and environment regressions; task, recovery, evidence and local-mode write-guard suites passed through make evidence.
Impact: add explicit LOCAL_READY and task-resume, validate worktree/card/baseline and receipt purpose, preserve schema 1 and prevent local receipts from starting or releasing tasks.
Refs: U2; policy/merge-queue.md; .task/feature-merge-queue-policy-draft.md
Why: repeated task-sync calls changed HEAD and invalidated CI even when main had not advanced.
Evidence: SELF red-green regression and 58 task lifecycle tests recorded through make evidence in the task card.
Impact: sync still fetches and validates components, creates records only for an actual merge, and reports the complete final source SHA.
Refs: U1; policy/merge-queue.md; .task/feature-merge-queue-policy-draft.md
Why: make the agent responsible for merging reviewed PRs without another human merge step.
Evidence: SELF governance and generated-card checks are captured in .task/feature-agent-pr-merge.md; CI remains required on the final PR HEAD.
Impact: update project delivery policy, agent entry points, task metadata and closure guidance; preserve platform protection and scoped authorization.
Refs: .task/feature-agent-pr-merge.md; user instruction on 2026-10-12
Why: preserve project direction across tasks and require grounded next-task recommendations.
Evidence: the generated task-card regression fails before the template update and passes afterward; original SELF receipts are in the task card.
Impact: document the planning entrypoint and extend task records without granting new-task execution rights.
Refs: .task/feature-goal-continuity.md; policy/delivery.md
Why: archived task cards change directory and must retain an unambiguous policy reference.
Evidence: review finding 1, focused red-green proof and 104 passing governance tests are preserved in the task card.
Impact: use a repository-root text reference; record the completed review and its resolved finding.
Refs: .task/feature-iterative-delivery.md; .task/reviews/iterative-delivery.json
Why: main advanced with merged-task-name and legacy evidence guards during this task.
Evidence: SELF 44 lifecycle regressions pass after resolving both hunks; independent review repairs are recorded in the task card.
Impact: retains both task-start protections and the stronger JSON/legacy receipt reader, without rewriting either branch history.
Refs: Dev PR #211 and #212; .task/feature-governance-reliability.md
Why: independent review found shared submodule metadata risk, quoted header leakage, stale JSON receipt blindness and missing abandon coverage.
Evidence: SELF 92 governance regressions pass; the original review receipt and replay output are recorded in the task card.
Impact: preserves external component worktrees, handles both evidence formats and adds targeted failure-path coverage; no product behavior changes.
Refs: .task/feature-governance-reliability.md; .task/reviews/governance-reliability.json
Why: cleanup, component synchronization, receipt recording and credential handling could contradict the documented development boundaries.
Evidence: SELF 75 isolated governance tests and source checks are captured in .task/feature-governance-reliability.md; combination and CI verification follow.
Impact: hardens local task and CI tooling, aligns policy and component documentation, and adds continuous regression tests without changing product behavior.
Refs: .task/feature-governance-reliability.md; policy/governance.md; policy/platform-admission.md
Why: evidence rows are written before their containing card commit, so a naive
HEAD-diff would flag every task's evidence as stale and train people to ignore
the warning.
Evidence: bash -n clean; the live task-sync for this task exercises the new
path (warning fires only when a non-.task diff follows an evidence row's HEAD).
Impact: scripts/task.sh cmd_sync now excludes .task from the staleness diff;
AGENTS.md wording aligned (three-output evidence via make evidence).
Refs: task card evidence table; guidelines verification.md tool-written rule.
Why: the make-variable pass-through re-quoted CMD and broke any command
containing quotes (caught by the redaction self-test before it could run).
Evidence: redaction self-test now records 'token <redacted> hello' with quoting
intact (row sha256 aae6a895); negative 'false' case earlier recorded exit=1
row and propagated rc — both in the task card evidence table.
Impact: CMD now travels via environment (CMD="..." make evidence); SRC/TAIL
stay make variables; usage strings updated in Makefile/AGENTS.md/task.sh
template comment.
Refs: task card evidence table; guidelines draft.10 tool-written-evidence rule.
Why: declarations were passing as capability; hand-transcribed outputs flowed
through cards and PR bodies as if they were execution evidence, and stale
external facts (e.g. the dead git-panel host) kept being trusted until burned.
Evidence: guidelines draft.10 (PR Development-Guidelines#4, merged af199ee)
pinned here; policy/facts.md F1-F4 each re-verified on 2026-10-05 before
registration (endpoint version, token HTTP 200 via header only, SSH ls-remote,
dead-host negative probe); scripts syntax-checked (bash -n); tool self-tests
and make test recorded in the task card via the new make evidence.
Impact: new AGENTS.md section (SELF/REPLAY/GATE, tool-written evidence,
replay-on-review, zero-trust facts, honest-empty); make evidence/facts-verify;
precheck gains [hooks]/[facts], task-sync gains stale-evidence-HEAD warning;
task-start cards now embed the evidence table; gitlink advances to draft.10.
Refs: task card .task/feature-evidence-driven-gates.md; guidelines CHANGELOG
0.1.0-draft.10.
Why: Merge commits share a tree with the pinned feature commit, the import ratchet downloaded modules during CI, and task sync wrote the checkpoint onto the wrong card.
Evidence: check-pins accepts 6c0f1e8 (same tree as Backend squad 8e987bf) and rejects empty-tree 8db069d; both objects stayed local. An empty GOMODCACHE run of lint-boundaries matches the cached go list, 14 pairs. bash -n scripts/task.sh.
Impact: make pin no longer checks out Backend nested core or agent-command, and a failing pin check does not fail the target. task sync writes the branch card or warns. precheck reports completed-but-unarchived cards and card-close branches older than 24 hours.
Refs: feature/agent-stack-r0-r1
Co-authored-by: Cursor <cursoragent@cursor.com>
Why: two recurring papercuts from 2026-09-30 sessions — (1) task-start treated a zero-exit submodule update as complete, but a worktree could still carry 12 drifted/uninitialized nested submodules that only surfaced at build time; (2) close ran a single git push, so a tunnel hiccup left the card-close branch unpushed and the auto-PR never created (hand-patched twice that day).
Evidence: bash -n clean; smoke start of a throwaway task measured nested drift count explicitly and abandon-path finish recycled worktree and branch cleanly (both PASS); fresh-clone commit identity probe also PASS after setting the global identity outside this repo.
Impact: scripts/task.sh cmd_start (+3-line status check) and cmd_close (one retry on push); no interface change.
Refs: .task/fix-followup-hardening.md
Why: cmd_close posted the PR with a single curl wrapped in
2>/dev/null || true, so any transient TLS/timeout on the git-home
HTTPS surface left the card-close branch pushed with no PR and no
diagnostics; this hit three times on 2026-09-30 and each needed a
manual API call to recover.
Evidence: bash -n clean; stub-server harness running the block
verbatim (sed-extracted from this file, executed inside the worktree
branch context): ok mode recovers the PR URL on first POST; exists
mode (POST always 500) retries 4x with visible stderr then recovers
the pre-existing open PR via GET ?state=open matching head ref;
fail mode against the retired git-panel host shows four visible
retry notices and falls through to the existing [next] hint.
Impact: scripts/task.sh cmd_close only; precheck/start/sync/finish
untouched; card-close merge authority unchanged (owner merges).
post-merge hook and task-finish auto-close inherit the fix through
the same function.
Refs: task card fix-close-pr-retry
Why: cmd_finish ran git submodule deinit --all, but submodule.<name>.url entries live in the shared .git/config — finishing any task silently marked every other checkout and worktree uninitialized (observed twice on 2026-09-30: main checkout uninit=12 after each finish; a parallel session hit it minutes before this fix landed). The deinit serves no purpose: worktree removal with gitlinks is refused regardless, so cleanup already goes through rm -rf + prune. Also aligns AGENTS.md with observed hook behavior (post-merge fires on ff-only pulls too, and its inline close cannot see cards merged remotely until they are pulled), and ignores the ZCode-generated .zcodeignore that tripped the BUSY gate in every session.
Evidence: bash -n clean; abandon-path smoke of the patched script — start + FORCE_ABANDON=1 finish of a throwaway branch left shared submodule url config at 12 entries (pre-fix: 0), main checkout submodule status uninit=0, smoke worktree and branch fully recycled; the smoke close also backfilled a parallel session card left open (gitea-access-facts) via a card-close branch, proving the fallback path.
Impact: scripts/task.sh cmd_finish only (removes one line, updates comment), AGENTS.md card-close paragraph, .gitignore one entry. No product or gitlink change; make test not applicable (repo-level tooling/docs only). web_base default fix intentionally withdrawn from this PR — landed via parallel PR #73.
Refs: .task/fix-task-finish-close-followups.md
Why: the TASK_CARD_WEB_BASE default in scripts/task.sh still pointed at
git-panel.u1680832.nyat.app:30319, which now fails the TLS handshake
(curl exit 35), breaking card-close PR links and API calls; agents also
kept rediscovering hosts and credential locations from scratch each
session.
Evidence: curl https://git-panel...:30319/api/v1/version -> exit 35; curl
https://git-home...:30319/api/v1/version with token from ~/.secrets/gitea
-> {"version":"1.27.3"}; ssh -p 31411 git@git-ssh... -> 'Hi there,
weichen!' with key ~/.ssh/home_gitea (ED25519, fingerprint
SHA256:GYXaOXIMeloQ1fKSfdJ/ndgPQzs/Ix7Hk62ekfkfQ20, key name GMKtec).
Impact: task.sh default web base now resolves to the live host; AGENTS.md
gains a Gitea access-facts section recording hosts plus credential
locations only (no secret values, per baseline hard boundary 2). Follow-up
PRs propagate the same section to the other project repos.
Refs: task card feature-gitea-access-facts
Why: cmd_start derived the worktree location from $PWD, so running task.sh start from a repository subdirectory (or inside a task worktree) placed the new worktree at the wrong spot — e.g. scripts-wt-<slug> nested inside the repo.
Evidence: bash -n clean; functional smoke of the patched script from both the main checkout scripts/ subdir and the repo root created ../Agent-System-Dev-wt-<slug> as a sibling of the main checkout (paths asserted; pre-fix subdir run would nest inside the repo); git rev-parse --git-common-dir resolves to the main checkout from both locations (relative ../.git vs absolute).
Impact: scripts/task.sh cmd_start only; from the main checkout root the derived path is identical to before; new worktrees now always land as siblings of the main checkout regardless of invocation directory.
Refs: .task/feature-task-start-rootfix.md
Why: 11 merged branches had left their task cards open (bookkeeping debt found on 2026-09-30); closure was manual and never triggered, so card status rotted after each merge.
Evidence: dogfood run of `task.sh close --fold` closed and archived the 11 cards (previous commit); temp-repo matrix 33/33 PASS covering detection, pending-branch idempotence, dirty/no-fold refusals, post-merge auto-close on merge-type pulls, worktree guard, and the full lifecycle (closure PR merge archives cards on main).
Impact: scripts/task.sh (+close, precheck [cards] report, finish-tail trigger), scripts/hooks/post-merge (new), Makefile (+task-close target, setup chmod), AGENTS.md rule; archive fixes correct PR links missed by the first dogfood run; no module or gitlink change.
Refs: task card feature/card-autoclose-r1
Why: Provider repos merged for T1 (core PR#2, agent-command PR#2, frontend
PR#3, ui PR#3, documents PR#9); gitlinks pinned to those mains. The
task-finish guard prevents a repeat of the T0 incident where running
finish from the main checkout deleted it (scripts/task.sh treated $PWD as
the worktree to remove).
Evidence: make test green on the pinned combo — core, backend 13 pkgs,
frontend 9, ui 6, agent-command (vet + tests incl. conformance); make build
produces the binary; combo version string now includes agentcmd SHA.
Impact: combo grows its version traceability; AGENTS.md documents the
worktree-cwd requirement for finish.
Refs: modules/documents docs/records/2026-09-30-t1-core-cards-commands-verification.md
Why: the pin-documents flow exposed guard divergence — precheck counted
submodule drift while task-start checked porcelain only, letting a task
start despite a BUSY verdict; and PR#8 overcorrected by treating
uninitialized (-) submodules as BUSY when they only block builds, not
writes.
Evidence: bash -n clean; precheck on this checkout prints tree line with
drift/uninit split and READY verdict; negative path exercised by the
real divergence that started this task.
Impact: precheck warns on uninitialized, BUSY only on +/U; task-start now
refuses on porcelain dirt and +/U drift, matching precheck.
Refs: PR#8; policy/tool-adaptation-matrix.md A1
Why: precheck missed uninitialized submodules (git submodule status '-'
prefix), and the branch protection configured today plus the second live
probe outcome must be recorded honestly in the matrices.
Evidence: platform negative: direct push to protected main rejected
(pre-receive hook declined, Logging-System probe); second write-guard probe
confirmed session-start config loading (no hook run in the pre-config
session log).
Impact: precheck sub_dirty now counts '-' prefixed entries; A3 registered
enforced at platform layer across 11 repos; zcode matrix pending-live
annotated with the loading-timing proof.
Refs: policy/tool-adaptation-matrix.md; policy/tool-adaptation-zcode.md
Why: git unconditionally refuses worktree remove when the tree contains
gitlinks (index-level check; deinit does not bypass it), so the PR#4 fix
path still failed on the second real task.
Evidence: after deinit the worktree was clean and submodule dirs empty, yet
remove refused; rm -rf + worktree prune is the documented workaround and
was proven manually on the empty-list task worktree.
Impact: task-finish now completes the recycle path automatically after its
merge verification; no guard weakened.
Refs: Agent-System-Dev PR#4; policy/tool-adaptation-matrix.md A5
Why: git refuses to remove a worktree with initialized submodules; the first
real dogfood run of task-finish hit this on the empty-list fix task.
Evidence: the fix task's worktree recycled only after manual force-remove;
deinit-then-remove path exercised on the same state afterwards.
Impact: finish deinitializes submodules, removes, prunes, and deletes the
remote branch; unmerged-result guard unchanged.
Refs: .task/fix-empty-list-json.md
Why: agents skipped triggered reading and wrote into shared checkouts holding
other tasks' in-flight changes; the 2026-09-30 empty-list incident session
found 24 overlapping in-flight files only by accident at first write.
Evidence: positive/negative suite in a real scratch repo passed 19/19
(precheck READY/BUSY/SYNC_REQUIRED, start refuse/establish, hook main/badname/
longsubject refusals, sync checkpoint, finish recycle and abandon double-
confirm); the suite caught three real defects (pipefail empty-grep abort,
worktree gitdir COMMIT_EDITMSG resolution, message checks in the wrong hook
phase).
Impact: make setup enables pre-commit/commit-msg hooks; make precheck/task-
start/task-sync/task-finish provide the governed path; no existing workflow
removed. AGENTS.md carries the resident gate rules.
Refs: Development-Guidelines 0.1.0-draft.7; task card .task/delivery-mechanism.md
agent-exec-transport
weichen