docs(workflow+agents): add HARD BAN on day estimates + Tier 1 Track Initialization Rules section

AGENTS.md

@@ -57,6 +57,7 @@ The 14 deep-dive guides under `docs/` (`guide_architecture.md`, `guide_ai_client
 - `set_file_slice` IS valid for multi-line content. The agent must verify the exact byte offsets with `get_file_slice` first, copy the line text character-for-character (including whitespace and EOL), and check whether the edit changes a public contract (function signature, yield shape, return type) that other code depends on. See `conductor/edit_workflow.md` for the full contract.
 - Do not use `git restore` while a user is mid-conversation without first confirming the desired state
 - HARD BAN: `git restore`, `git checkout -- <file>`, `git reset` are FORBIDDEN without explicit user permission in the same message. They destroyed user in-progress src/* edits twice in one session (2026-06-07). If you think you need one, ASK FIRST.
+- **HARD BAN: Day estimates in track artifacts (Tier 1).** Do NOT include day / hour / minute estimates in spec.md, plan.md, metadata.json, or any other track artifact. Day estimates are inaccurate noise; Tier 2 capacity is bounded by attention, not time. Measure effort by **scope** (N files, M sites, N tasks) and **T-shirt size** (S/M/L/XL). The user / Tier 2 agent decides the actual pacing. See `conductor/workflow.md` §"Tier 1 Track Initialization Rules" for the full rule, replacement patterns, and rationale. (Added 2026-06-16 per user feedback: "Day estimates are inaccurate. Tier-2s can only do so much in a single track and there is no way in hell its going to be 'DAYS'.")
 
 ## File Size and Naming Convention (HARD RULE — added 2026-06-11)
 

conductor/workflow.md

@@ -554,6 +554,119 @@ The recommended execution order is the topological sort of the `blocked_by` grap
 
 ---
 
+## Tier 1 Track Initialization Rules (Added 2026-06-16)
+
+These are the rules a Tier 1 Orchestrator follows when initializing a new
+track. They exist because Tier 1 noise (day estimates, day-of-week
+schedules, etc.) propagates into the Tier 2's plans, the user's
+expectations, and the historical record — and most of that noise is
+just wrong.
+
+### 1. NO day / hour / minute estimates in track artifacts
+
+**HARD BAN.** Do NOT include day, hour, or minute estimates in
+`spec.md`, `plan.md`, `metadata.json`, or any other track artifact.
+
+**Why:** day estimates are inaccurate noise. Tier 2 capacity is bounded
+by **attention**, not time. A track that "should take 2 days" can take
+half a day (if the user is available and the Tier 2 is focused) or 3
+days (if interruptions come up, the user is unavailable for review, or
+the audit reveals scope growth). The Tier 1 cannot predict either
+scenario. Estimates also anchor the user's expectations incorrectly;
+"the spec said 2 days and it's been 3, what's wrong?".
+
+**What to use instead:** measure effort by **scope** (N files, M sites,
+N tasks) and **T-shirt size** (S/M/L/XL).
+
+| T-shirt | Typical scope |
+|---|---|
+| **S** | 1-5 small changes; mostly research or doc updates |
+| **M** | 1-2 small files; 1 commit |
+| **L** | 5-10 files; 2-5 commits; or 1 large file with mechanical changes |
+| **XL** | 1 huge file (100K+ lines); 5-10 commits; high coordination |
+
+**Replacement patterns:**
+
+| DON'T write | WRITE instead |
+|---|---|
+| `Estimated effort: 0.5-1 day Tier 2 work` | `Scope: N files, M sites; T-shirt size: S/M/L/XL` |
+| `Phase 1: investigation (1-2 hours)` | `Phase 1: investigation` |
+| `Track 5 takes 7-10 days total` | `Track 5: scope = N sites across M files` |
+| `R5: takes longer than 1 day` | `R5: implementation is larger than the spec suggests` |
+| `~12 min test run` | `the test run takes a while` |
+
+The user / Tier 2 agent decides the actual pacing.
+
+### 2. Spec format
+
+The `spec.md` follows the standard template (Overview, Current State
+Audit, Goals, Non-Goals, Architecture, Risks, Verification, etc.) with
+these specific Tier 1 rules:
+
+- **Current State Audit is MANDATORY** before writing requirements. Read
+  the actual code with MCP tools (`get_file_slice`, `py_get_skeleton`,
+  `py_get_definition`, `py_find_usages`). Document existing
+  implementations with `file:line` references in a "Current State
+  Audit" section. Failure to audit = track failure.
+- **Frame requirements as GAPS, not features.** "The existing X
+  (file.py:L100-200) has Y; this track fills the gap" — not "Build
+  feature Z".
+- **Write worker-ready tasks** in the plan. Each plan task must be
+  executable by a Tier 3 worker. The Tier 1 does NOT execute the
+  plan; the Tier 1 writes it for a Tier 3 to execute.
+- **Reference architecture docs** (`docs/guide_*.md`,
+  `conductor/code_styleguides/*.md`) in every spec. Every requirement
+  must point to the existing pattern it follows (or the new pattern it
+  establishes).
+- **For bug fix tracks: Root Cause Analysis** is mandatory. Read the
+  code, trace the data flow, list specific root cause candidates.
+  Don't ship "I tried X, the test still failed, here's a 200-line
+  report".
+
+### 3. Metadata format
+
+The `metadata.json` follows the standard schema. Specific Tier 1 rules:
+
+- `scope.new_files` / `scope.modified_files` / `scope.deleted_files`
+  are the file-level scope. No "lines of code changed" estimates.
+- `regressions_and_pre_existing_failures` is a list, not a count.
+- `pre_existing_failures_remaining` MUST be `[]` for the track to be
+  marked complete.
+- `deferred_to_followup_tracks` is a list of followup items with
+  title + description + track_status. No "estimated effort".
+- `estimated_effort` field uses `method: "scope (per workflow.md §Tier
+  1 Track Initialization Rules). NO day estimates."` and a per-phase
+  `scope` summary (e.g., `phase_1: "1 task: investigation"`).
+- `risk_register` entries use scope-relative likelihood ("medium"
+  means "the implementation may be larger than the spec suggests"),
+  not time-relative ("takes longer than 2 days").
+
+### 4. Plan format
+
+The `plan.md` follows the standard TDD red-first template. Specific
+Tier 1 rules:
+
+- Each task has WHERE / WHAT / HOW / SAFETY / COMMIT / GIT NOTE
+  fields. Tasks are NOT grouped by "day" or "hour".
+- Phase headers describe the WORK, not the TIME. ("Phase 1:
+  Investigation" not "Phase 1: Day 1").
+- The plan is read by a Tier 3 worker; the Tier 1 never executes it
+  themselves.
+
+### 5. The "Reasonable effort" guard
+
+If you find yourself writing a day estimate, ask: **"is this estimate
+based on data I actually have, or am I guessing?"** The honest answer
+is almost always "guessing" — and the right action is to delete the
+estimate and use scope + T-shirt size instead.
+
+The exception: if the user explicitly asks for an estimate (e.g., "how
+many tracks will this take?"), the answer is "I can't predict the
+duration; here's the scope and the recommended sequence". The user
+decides the pacing.
+
+---
+
 ## State.toml Template
 
 Every track's `conductor/tracks/<track_id>/state.toml` should follow this structure (used as the agent's "where am I in this track" source of truth):