Rule 4 now tests two axes — reachability (the pointer resolves) and
comprehension (a linearly-reading human understands the entry without
absorbing the target). A reachable-but-opaque reference no longer passes.
References go host-free: absolute URLs with a server name or port are
banned; the canonical clickable forms are Gitea relative links —
src/commit/<sha>/path#user-content-<slug> for a file section/line and
issues/N#issuecomment-M for a comment. Verified against live Gitea 1.26.2.
Bind every author, not just an explicit invocation, and pull milestones
into scope (rules 1/2/4 on the description; the title names the
container). Propagate the comment-link form and the rule-4 rename to boss.
An issue or decision-log entry must state the situation, not the
orchestration loop's next move. "Next step: enter `specify`" — and its
role-periphrasis "hand it off to the spec writer next", which names no
skill — is Claude-Code session control-flow, meaningless to a tracker
reader who is not the loop. A distinct defect class from rule 4
reachability, and not curable by declarative phrasing: the content is
harness-native.
issue rule 1 retitled "No direct address" -> "Impersonal and
tool-neutral". The discriminator is status vs. dispatch, name-independent
(describes the work's condition -> keep; directs who runs what next ->
cut), and rule 1 now also bars first-person loop narration. boss § The
reference issue gains "Record the decision, not the dispatch". Triple-
encoded in both skills (rule/mechanic + table/rationalisation + red-flag).
Future-only; existing entries are not edited.
The rule-4 carve-out example wrapped the date inside the quotation
marks; close the quote right after the words so the date reads as
metadata, not part of the verbatim quote.
Rule 4 ("Self-contained") forbade dangling pointers by example only, so
a reference reachable only through the producing chat slipped past it --
e.g. a shipped comment "Approach B (the mechanism refinement decided +
logged above)", whose "logged above" names no resolvable entry and whose
"Approach B" indexes an A/B fork the entry never reproduces.
Reframe rule 4 around one test: a reference is valid iff a reader who
lands on the entry alone (e.g. via a direct comment-anchor link) can
follow it to its target. A survey of the live tracker (63 issues / 96
comments) found 56 violations in six classes, now each named as an
unreachable form: chat references, weak intra-thread pointers
("above" / "logged above"), artifacts named by role, out-of-repo paths,
bare un-glossed codes, and locator-shaped tokens that resolve to nothing.
Carve-outs keep inline quotations, #N / SHA / URL / repo-path locators,
glossed codes, and restated forks legitimate. The constructive escape
hatch (log a chat decision to the tracker first, then cite that comment)
cross-references boss "The reference issue".
Align the Common-mistakes table, the Red-flags STOP gate, and the boss
cross-reference. Prescribe a comment's full URL rather than a bare
#issuecomment-NNNN fragment, which is not auto-linked on Gitea and so
does not itself satisfy the test.
Existing tracker entries are left unedited; the rule governs future
writing only.
Under /boss only, when the orchestrator hits a durable deficiency in the
plugin itself (a skill, agent, convention, or pipeline/cascade gap)
mid-run, it files an issue against the plugin's own tracker and continues,
marking provenance with a body block — no new label, so the fixed work-type
vocabulary stays intact.
Adds the trigger and its evidence gate (a citable path:line inside the
plugin), dedupe-as-gate over open and recently-closed issues, and the
discipline that filing is neither a notify event nor a substitute for a due
bounce-back. Wires the new section into issue/SKILL.md (boss joins the
issue-filing callers) and docs/conventions.md (Issue-tracker pointer).
closes#9
docs/specs and docs/plans hold only the active cycle's artefacts: a spec/plan is committed while its cycle is live and git-rm'd in the cycle-close commit (after audit drift-clean), so HEAD shows only in-flight work while git history keeps the full text. No issue-posting, no gitignore branch — git history + the design ledger are the durable record.
Rewrites conventions.md § Lifecycle as the single source of truth; pipeline.md, design.md, README.md, specify, planner, glossary, brainstorm, issue, and the CLAUDE.md fragment follow it. Naming stays NNNN-slug.md (a within-cycle handle; recycling on an emptied directory is fine).
The profile was never parsed — it was prose the skill bodies told the model to read, so most slots were dead, constant across every project, or fiction (the whole pipeline block, including the "tdd is opt-in" claim, was enforced by nothing).
Split it in two: constants become fixed conventions named directly by the skills (new docs/conventions.md), and the few genuinely per-project facts move to each project's CLAUDE.md under '## Skills plugin: project facts'. tdd/fieldtest/docwriter are now always available; the only behavioural toggle left is spec auto-sign.
Delete docs/profile-schema.md and templates/project-profile.yml; add docs/conventions.md and a project-facts section to templates/CLAUDE.md.fragment; rewrite all SKILL/agent prose and the pipeline/design/migration/README/INSTALL docs accordingly.
The `spec-skeptic` `scope-fork` juror reads only the seeding issue plus
the spec. On the legitimate `specify` direct-entry path — a fork settled
in a long in-context design discussion — that resolution lives only in
ephemeral chat the juror cannot replay. When the issue body lags the
discussion (still lists the fork open), the juror correctly blocks, and
a design BLOCK escalates without self-correction. The result: auto-sign
was structurally almost unreachable for the in-context entry path.
Close the blind spot by giving the juror an auditable source instead of
weakening the gate. When `specify` enters in-context and a tracker issue
still lists a now-resolved fork as open, the orchestrator posts a
reconciliation comment recording each fork's resolution WITH provenance
(a record of the user's decision, never a fresh orchestrator one) before
writing the spec. The comment is persistent and audit-able — unlike a
carrier digest — so it, not the orchestrator's confidence, is what the
juror checks.
Separation of powers keeps it honest: the orchestrator writes the
comment, the adversarial juror enforces the provenance requirement. A
bare `decision: X` with no provenance does not resolve the fork — the
re-dispatched juror blocks on it. The escalation rule and the
three-field carrier are untouched; only the juror's information changes.
Mechanics:
- specify Step 1.5: reconciliation-comment sub-step, provenance format,
issue-less fallback (auto-sign -> human sign-off, no weak spec-note).
- spec-skeptic: replace the "quoted in the dispatch" drift; juror reads
the issue WITH comments via `issue_tracker.show_cmd`; provenance check.
- new profile slot `issue_tracker.show_cmd` (must render comments);
documented in schema + template.
- issue skill: `tea issues <idx>` is body-only; `--comments` required
(verified against tea 0.14.1 and Aura #55 — 180 vs 144 lines).
- consistency: design.md out-of-scope, README, pipeline.md, boss skill.
Rule 2 (validated-or-flagged) now suggests dropping in a fenced code
snippet where it sharpens the point — the input that triggers the
failure or the call as it should behave — preferred over a prose
paraphrase.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Unifies four issue-writing rules — impersonal voice, every claim
validated-with-evidence or flagged as a claim, imperative concise
title (checkboxes allowed for sub-points), and self-containment
(every reference directly resolvable, no unresolvable tags) — and
records the tea-CLI mechanics for create/edit/comment/close.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Brummel