Merge pull request 'Develop' (#37) from develop into main

Reviewed-on: #37

.agents/skills/trellis-meta/references/local-architecture/bundled-skills.md

@@ -31,30 +31,42 @@ The list is discovered at runtime, so adding a new directory under `bundled-skil
 
 ## Where Bundled Skills Land Per Platform
 
-Each platform configurator calls `writeSkills(<root>, <workflowSkills>, resolveBundledSkills(ctx))` during `trellis init`. `resolveBundledSkills` reads every directory under `templates/common/bundled-skills/`, resolves placeholders, and returns a flat list of `{relativePath, content}` entries. `writeSkills` then mirrors them under the platform's skill root.
+A platform's whole file set — commands, workflow skills, agents, hooks, bundled skills — is described exactly once, by `collect<Platform>Templates()` in `packages/cli/src/configurators/<platform>.ts`. For bundled skills that description is two calls: `resolveBundledSkills(ctx)` reads every directory under `templates/common/bundled-skills/`, resolves placeholders, and returns a flat list of `{relativePath, content}` entries; `collectSkillTemplates(<skillsRoot>, <workflowSkills>, <bundledSkills>)` folds them into the platform's `Map<filePath, content>` under `<skillsRoot>/<skill>/<relativePath>`.
 
-| Platform | Bundled skill root | Notes |
+All 21 platforms receive the full bundled-skill set:
-| --- | --- | --- |
-| Claude Code | `.claude/skills/<skill>/` | `configureClaude` |
-| Cursor | `.cursor/skills/<skill>/` | `configureCursor` |
-| Codex | `.agents/skills/<skill>/` | `configureCodex` writes the shared `.agents/skills/` root, which Gemini CLI 0.40+ also reads |
-| Gemini CLI | `.agents/skills/<skill>/` | Same shared root as Codex; the two configurators are required to produce byte-identical output |
-| Kiro | `.kiro/skills/<skill>/` | `configureKiro` (skills-based platform — no commands) |
-| Qoder | `.qoder/skills/<skill>/` | `configureQoder` |
-| Codebuddy | `.codebuddy/skills/<skill>/` | `configureCodebuddy` |
-| Copilot | `.github/skills/<skill>/` | `configureCopilot` |
-| Droid | `.factory/skills/<skill>/` | `configureDroid` |
-| Antigravity | `.agent/skills/<skill>/` | `configureAntigravity` |
-| Devin | `.devin/skills/<skill>/` | `configureDevin` |
-| Kilo | `.kilocode/skills/<skill>/` | `configureKilo` |
-| ZCode | `.zcode/skills/<skill>/` | `configureZcode` |
-| OpenCode | (handled by `collectOpenCodeTemplates`) | Uses the same `resolveBundledSkills(ctx)` output |
-| Pi, Reasonix | (their own collectors) | Same `resolveBundledSkills(ctx)` output |
 
-Two paths exercise the same data:
+| Platform | Bundled skill root |
+| --- | --- |
+| Claude Code | `.claude/skills/<skill>/` |
+| Cursor | `.cursor/skills/<skill>/` |
+| OpenCode | `.opencode/skills/<skill>/` |
+| Codex | `.agents/skills/<skill>/` |
+| Gemini CLI | `.agents/skills/<skill>/` |
+| Pi | `.agents/skills/<skill>/` |
+| Kimi | `.agents/skills/<skill>/` |
+| Kilo | `.kilocode/skills/<skill>/` |
+| Kiro | `.kiro/skills/<skill>/` |
+| Antigravity | `.agent/skills/<skill>/` |
+| Devin | `.devin/skills/<skill>/` |
+| Qoder | `.qoder/skills/<skill>/` |
+| Codebuddy | `.codebuddy/skills/<skill>/` |
+| Copilot | `.github/skills/<skill>/` |
+| Droid | `.factory/skills/<skill>/` |
+| Reasonix | `.reasonix/skills/<skill>/` |
+| ZCode | `.zcode/skills/<skill>/` |
+| Trae | `.trae/skills/<skill>/` |
+| OMP | `.omp/skills/<skill>/` |
+| Grok | `.grok/skills/<skill>/` |
+| Snow | `.snow/skills/<skill>/` |
 
-1. `configureX(cwd)` writes files during `trellis init`.
+Codex, Gemini CLI, Pi and Kimi share the `.agents/skills/` root (the upstream Agent Skills workspace alias). Their collectors are required to emit byte-identical content for every file more than one of them writes there.
-2. `collectPlatformTemplates(platformId)` (in `configurators/index.ts`) returns a `Map<filePath, content>` that `trellis update` uses to detect drift and to populate `.trellis/.template-hashes.json`. Both must produce byte-identical output, so they both call `resolveBundledSkills(ctx)` and `collectSkillTemplates(root, …, resolveBundledSkills(ctx))`.
+
+One description, two consumers:
+
+1. `trellis init` → `configurePlatform(platformId, cwd)` → `writeTemplateMap(cwd, collect<Platform>Templates())`. For 18 of the 21 platforms the registry entry in `configurators/index.ts` is literally `fromTemplates(collect<Platform>Templates)`, which *is* that composition. Claude Code, Codex and ZCode spell out a `configure` of their own, each for work a `Map<path, content>` cannot express (an opt-in `--with-statusline` flag, an intentionally empty `.codex/skills/` directory, a one-shot console notice) — none of them restates the file list.
+2. `trellis update` → `collectPlatformTemplates(platformId)` (in `configurators/index.ts`) → the same map, used to detect drift and to populate `.trellis/.template-hashes.json`.
+
+Because both consumers read the one description, init and update cannot disagree about which files a bundled skill produces.
 
 ## Dispatch Wiring (Code Path)
 
@@ -67,10 +79,10 @@ The mechanism that auto-dispatches bundled skills to platform skill roots lives
 
 2. `packages/cli/src/configurators/shared.ts`
    - `resolveBundledSkills(ctx)` flattens that list into `ResolvedSkillFile[]` with `<skill>/<relativePath>` paths and resolved placeholders.
-   - `writeSkills(skillsRoot, workflowSkills, bundledSkills)` writes both workflow skills and bundled skill files under `skillsRoot`.
+   - `collectSkillTemplates(skillsRoot, workflowSkills, bundledSkills)` returns workflow skills and bundled skill files together as a `Map<filePath, content>` rooted at `skillsRoot`.
-   - `collectSkillTemplates(skillsRoot, workflowSkills, bundledSkills)` returns the same shape as a `Map<filePath, content>` for the update / hash pipeline.
+   - `writeTemplateMap(cwd, files)` is the single writer that puts a collected map on disk.
 
-Every platform configurator that supports skills imports both helpers (see `claude.ts`, `cursor.ts`, `codex.ts`, `gemini.ts`, `kiro.ts`, `qoder.ts`, `codebuddy.ts`, `copilot.ts`, `droid.ts`, `antigravity.ts`, `devin.ts`, `kilo.ts`). The `index.ts` `PLATFORM_FUNCTIONS` registry also calls `resolveBundledSkills(ctx)` inside each `collectTemplates` closure so `trellis update` tracking stays consistent.
+Every platform that supports skills reaches those two helpers from its own `collect<Platform>Templates()` — either directly (`claude.ts`, `codex.ts`, `copilot.ts`, `gemini.ts`, `grok.ts`, `kimi.ts`, `kiro.ts`, `omp.ts`, `opencode.ts`, `pi.ts`, `reasonix.ts`, `snow.ts`, `zcode.ts`) or through `collectBothTemplates(ctx, cmdPath, skillRoot)` in `shared.ts`, which makes the same two calls on behalf of platforms that have both a commands directory and a skills root (`antigravity.ts`, `codebuddy.ts`, `cursor.ts`, `devin.ts`, `droid.ts`, `kilo.ts`, `qoder.ts`, `trae.ts`).
 
 ## Adding a New Bundled Skill
 
@@ -137,7 +149,7 @@ There is no per-project opt-out flag for bundled skills. Two options:
 
 2. **Pin a Trellis version that did not ship the skill.** The bundled-skill set is determined at build time, so installing an older release of the CLI is the only way to permanently exclude a skill that the current release ships.
 
-A third option — globally disabling all bundled skills — is not supported. The dispatch is unconditional in every configurator. Adding such a flag would require changing `PLATFORM_FUNCTIONS` in `configurators/index.ts` and every `configureX` function.
+A third option — globally disabling all bundled skills — is not supported. The dispatch is unconditional: `collect<Platform>Templates()` takes no arguments, so there is nowhere for a flag to enter. Adding one would mean changing that signature across all 21 platforms plus `collectPlatformTemplates` in `configurators/index.ts`.
 
 ## Operating Rules
 

.agents/skills/trellis-meta/references/platform-files/hooks-and-settings.md

@@ -19,7 +19,7 @@ Common files:
 | Claude Code | `.claude/settings.json` |
 | Cursor | `.cursor/hooks.json` |
 | Codex | `.codex/hooks.json`, `.codex/config.toml` |
-| OpenCode | `.opencode/package.json`, `.opencode/plugins/*` |
+| OpenCode | `.opencode/package.json`, `.opencode/plugins/*`, `.opencode/hooks/inject-spec-context.py` |
 | Kiro | `.kiro/hooks/` + platform config |
 | Gemini CLI | `.gemini/settings.json` |
 | Qoder | `.qoder/settings.json` |
@@ -40,6 +40,7 @@ Whether these files exist in a project depends on which `trellis init --<platfor
 | `session-start.py` | Generates session-start context. |
 | `inject-workflow-state.py` | Parses `[workflow-state:STATUS]` blocks in `.trellis/workflow.md` and emits the body matching the current task status. Falls back to `Refer to workflow.md for current step.` when no matching block exists. |
 | `inject-subagent-context.py` | Injects PRD, JSONL context, and related spec/research into sub-agents. |
+| `inject-spec-context.py` | Matches path-scoped specs and manages budgeted delivery state. |
 | `inject-shell-session-context.py` | Lets shell commands inherit Trellis session identity. |
 
 Not every platform has every hook. Do not copy files from another platform just because a platform lacks a hook; first confirm whether that platform supports the corresponding event.

.codex/hooks.json

@@ -1,5 +1,17 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "^(?:clear|compact)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -X utf8 .codex/hooks/inject-spec-context.py",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [
@@ -22,6 +34,19 @@
           }
         ]
       }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -X utf8 .codex/hooks/inject-spec-context.py",
+            "timeout": 15,
+            "additionalContextLimit": 0
+          }
+        ]
+      }
     ]
   }
 }

.codex/hooks/inject-spec-context.py

@@ -0,0 +1,844 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Path-Scoped Spec Context Injection Hook (ticket-refresh model)
+
+When the agent touches a file, the specs that govern that file are surfaced
+right then — small, relevant, budgeted — instead of everything up front or
+nothing at all. Spec .md files under .trellis/spec/ declare which code paths
+they govern via YAML frontmatter (`paths:` glob list); the matching engine
+lives in .trellis/scripts/common/spec_match.py and the decision engine in
+.trellis/scripts/common/spec_inject.py. This file is the IO shell: stdin,
+config, identity, state files, locking, GC, one print.
+
+Triggers:
+
+* Claude Code PostToolUse (matcher "Read|Edit|Write|MultiEdit") receives one
+  structured file path after the tool runs.
+* Codex PreToolUse (matcher "Edit|Write") receives an ``apply_patch`` command.
+  Every patch header is matched before the patch runs. When a FULL spec is
+  emitted, the patch is denied once so the model can read the injected rules
+  and retry; ticket-only reminders do not block.
+* OpenCode ``tool.execute.before`` adapts ``write``, ``edit``, and
+  ``apply_patch`` into the same PreToolUse payload. FULL delivery uses the same
+  deny-once decision before the JS plugin surfaces context as a tool error.
+
+Behavior — per matched spec, per event (recency-decay aware):
+
+    h    = sha256(spec bytes)
+    last = newest emission recorded for (identity, spec)   # stateless → None
+    if stateless:               emit TICKET  # bounded cost, always
+    elif last is None:          emit FULL    # first time this session
+    elif last.sha256 != h:      emit FULL    # spec changed → re-teach
+    elif reset since last:      emit FULL    # the text is gone, re-teach
+    elif within window:         silent       # fixed window; no state append
+    else:                       emit TICKET  # refresh attention cheaply
+
+A FULL block inlines the (budgeted) spec body with a sha256 attr; a TICKET is
+a short reminder pointing back at the spec. Both append a state record; silent
+hits do not (fixed window, not sliding — continuous editing is exactly when
+drift is worst).
+
+Identity (misfire asymmetry: a collision that MISSES an injection is
+unacceptable; drift that OVER-injects is fine): the session/window key is
+delegated to common.active_task.resolve_context_key — the shared resolver
+every other hook uses — called payload-first, environment-inclusive second,
+so two live sessions can never collapse onto one exported env value. A
+`+a-<agent_id>` suffix (appended after each part is sanitized) keeps a
+subagent's state separate from its parent's. When the resolver is unavailable
+(older installed scripts tree), a minimal payload-only ladder (session keys,
+then transcript hash) keeps the hook working. No key from any source, or an
+unwritable state dir → stateless: no state IO at all, every hit is a TICKET
+(circuit breaker — never a FULL re-emission loop).
+
+State: user-global, out of the repo, one append-only JSONL file per identity
+under ${TRELLIS_SPEC_STATE_DIR:-~/.trellis/spec-inject}/<project16>/<identity>.jsonl.
+SessionStart(clear|compact) appends an opaque reset marker to the base session
+shard; parent and subagent emission histories stay separate but observe that
+shared marker. A best-effort fcntl lock is held across read→decide→append;
+where fcntl is unavailable (Windows) the worst case is a duplicate injection.
+A once-per-hour GC prunes conforming shards older than 48 h.
+
+Budget (config.yaml `spec_injection:`): per-spec cap `max_spec_chars`
+(default 9400) with code-point truncation + in-body notice; per-event cap
+`max_total_chars` (default 9500 — below Claude Code's documented
+additionalContext ceiling, and enforced directly for Codex). Once the total
+budget is exhausted, remaining FULL bodies degrade to one <spec-index> block;
+tickets are counted last and dropped (with a stderr warning) only if even they
+do not fit.
+
+Refresh window (config.yaml `spec_injection:`): `refresh_window_seconds`
+(default 2700; `0` = never refresh unchanged content solely because time
+passed).
+
+Fail-open on errors: non-matching events, malformed paths, no matches, or any
+internal error → exit 0 with no stdout (stderr warnings allowed). The only
+deliberate block is a Codex patch that just received a FULL governing spec.
+"""
+from __future__ import annotations
+
+# IMPORTANT: Suppress all warnings FIRST
+import warnings
+warnings.filterwarnings("ignore")
+
+import hashlib
+import json
+import os
+import re
+import sys
+import time
+import uuid
+from pathlib import Path
+
+# IMPORTANT: Force UTF-8 on Windows for the streams this hook uses.
+# stdin carries the payload (non-ASCII file paths), stdout carries the spec
+# bodies, stderr carries warnings that quote both; without this the default
+# ANSI codepage raises UnicodeDecodeError / UnicodeEncodeError.
+if sys.platform.startswith("win"):
+    import io as _io
+    for _stream_name in ("stdin", "stdout", "stderr"):
+        _stream = getattr(sys, _stream_name, None)
+        if _stream is None:
+            continue
+        if hasattr(_stream, "reconfigure"):
+            try:
+                _stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+            except Exception:
+                pass  # Optional Windows stream setup; keep hook startup non-fatal.
+        elif hasattr(_stream, "detach"):
+            try:
+                setattr(sys, _stream_name, _io.TextIOWrapper(_stream.detach(), encoding="utf-8", errors="replace"))
+            except Exception:
+                pass  # Optional Windows stream setup; keep hook startup non-fatal.
+
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+DIR_WORKFLOW = ".trellis"
+DIR_SPEC = "spec"
+
+# Tools whose events trigger spec matching (Claude Code tool names). Touching a
+# file — even a Read — counts; the miss path stays a fast exit. Overridable via
+# config `spec_injection.tools` (e.g. to drop "Read").
+DEFAULT_EDIT_TOOLS = ("Read", "Edit", "Write", "MultiEdit")
+
+# Budget defaults sized against Claude Code's documented 10,000-CHARACTER
+# additionalContext ceiling — stay under with margin. The <spec-context>
+# wrapper (~152 chars with typical rel paths) counts against the total, so a
+# spec lands whole only up to ~9348 chars; at the per-spec cap the block is
+# derived-truncated further to fit the event ceiling. `0` = unlimited.
+DEFAULT_MAX_SPEC_CHARS = 9400
+DEFAULT_MAX_TOTAL_CHARS = 9500
+
+# Refresh-window default. `0` = never refresh solely because time passed.
+DEFAULT_REFRESH_WINDOW_SECONDS = 2700
+
+# State-file base dir (overridable for tests / hermeticity) and GC policy.
+STATE_ENV_DIR = "TRELLIS_SPEC_STATE_DIR"
+STATE_DEFAULT_DIR = "~/.trellis/spec-inject"
+GC_MARKER = ".last-gc"
+GC_INTERVAL_SECONDS = 60 * 60          # GC runs at most once per hour
+STATE_MAX_AGE_SECONDS = 48 * 60 * 60   # shards older than this are pruned
+
+# GC scope: exactly `<base>/<project16>/<identity>[.<pid>].jsonl`, never a
+# recursive walk — a hostile or mistyped TRELLIS_SPEC_STATE_DIR must not turn
+# this hook into an unlink loop over someone's files. The optional `.<pid>`
+# alternative covers shards written by the pre-lock layout.
+GC_PROJECT_DIR_RE = re.compile(r"^[0-9a-f]{16}$")
+# `+` is part of the identity charset: subagent shards use the `+a-<agent_id>`
+# suffix (contract amendment 2 — without it those shards were never pruned).
+GC_SHARD_NAME_RE = re.compile(r"^[A-Za-z0-9_+-]+(\.[0-9]+)?\.jsonl$")
+PATCH_PATH_RE = re.compile(
+    r"^\*\*\* (?:(?:Add|Update|Delete) File|Move to): (.+)$"
+)
+
+def _warn(message: str) -> None:
+    print(f"[inject-spec-context] WARN: {message}", file=sys.stderr)
+
+
+def _patch_paths(command: str) -> list[str]:
+    """Return file paths from the shared apply_patch grammar."""
+    paths: list[str] = []
+    for line in command.splitlines():
+        match = PATCH_PATH_RE.fullmatch(line)
+        if match:
+            path = match.group(1).strip()
+            if path and path not in paths:
+                paths.append(path)
+    return paths
+
+
+def _agent_id(payload: dict) -> str:
+    """The subagent id carried by the event, or "" for a main-session event."""
+    raw = payload.get("agent_id")
+    return raw.strip() if isinstance(raw, str) else ""
+
+
+def find_trellis_root(start: Path) -> Path | None:
+    """Walk up from start to find the directory containing .trellis/.
+
+    Handles CWD drift: subdirectory launches, monorepo packages, etc.
+    Returns None if no .trellis/ found (silent no-op).
+    """
+    cur = start.resolve()
+    while cur != cur.parent:
+        if (cur / DIR_WORKFLOW).is_dir():
+            return cur
+        cur = cur.parent
+    return None
+
+
+def _scripts_dir_on_path(root: Path) -> None:
+    scripts_dir = root / DIR_WORKFLOW / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+
+
+# =============================================================================
+# Config (.trellis/config.yaml `spec_injection:` section)
+# =============================================================================
+
+
+def _read_trellis_config(root: Path) -> dict:
+    """Load .trellis/config.yaml via the bundled trellis_config helper.
+
+    The helper lives in .trellis/scripts/common; the hook lives outside the
+    scripts tree, so we extend sys.path before importing.
+    """
+    _scripts_dir_on_path(root)
+    try:
+        from common.trellis_config import read_trellis_config  # type: ignore[import-not-found]
+    except Exception:
+        return {}
+    try:
+        return read_trellis_config(root)
+    except Exception:
+        return {}
+
+
+def _parse_tools(raw: object) -> tuple[str, ...] | None:
+    """Parse `spec_injection.tools` into a tuple of tool names.
+
+    Two grammars, because the bundled YAML reader hands the value over in two
+    shapes: a block list (``- Edit`` items) arrives as a list, a flow sequence
+    (``tools: [Edit, Write]``) arrives as the raw string. ``[]`` in either
+    shape is a deliberate "never trigger" and is respected. Returns None for a
+    value that is neither (the caller warns and keeps the defaults).
+    """
+    if isinstance(raw, list):
+        return tuple(t.strip() for t in raw if isinstance(t, str) and t.strip())
+    if isinstance(raw, str):
+        text = raw.strip()
+        if text.startswith("[") and text.endswith("]"):
+            items = (part.strip().strip("\"'").strip() for part in text[1:-1].split(","))
+            return tuple(item for item in items if item)
+    return None
+
+
+def get_spec_injection_settings(
+    root: Path,
+) -> tuple[bool, int, int, int, tuple[str, ...]]:
+    """Return (enabled, max_spec_chars, max_total_chars,
+    refresh_window_seconds, tools).
+
+    Reads the ``spec_injection:`` section of ``.trellis/config.yaml``:
+
+        spec_injection:
+          enabled: true
+          max_spec_chars: 9400
+          max_total_chars: 9500
+          refresh_window_seconds: 2700
+          tools:
+            - Read
+            - Edit
+            - Write
+            - MultiEdit
+
+    Missing keys use their defaults; ``0`` disables the corresponding limit
+    (``max_spec_chars: 0`` = inline the whole body, ``max_total_chars: 0`` =
+    no per-event ceiling) or refresh (window keys). ``tools`` also accepts a
+    flow sequence (``tools: [Edit, Write]``), and ``tools: []`` disables every
+    trigger. Invalid values fall back to the default for that key with a
+    stderr warning; tool names outside the known set warn once.
+    """
+    enabled = True
+    tools = DEFAULT_EDIT_TOOLS
+    numbers = {
+        "max_spec_chars": DEFAULT_MAX_SPEC_CHARS,
+        "max_total_chars": DEFAULT_MAX_TOTAL_CHARS,
+        "refresh_window_seconds": DEFAULT_REFRESH_WINDOW_SECONDS,
+    }
+
+    config = _read_trellis_config(root)
+    section = config.get("spec_injection") if isinstance(config, dict) else None
+    if isinstance(section, dict):
+        raw_enabled = section.get("enabled", True)
+        if isinstance(raw_enabled, bool):
+            enabled = raw_enabled
+        else:
+            s = str(raw_enabled).strip().lower()
+            if s in ("false", "no", "0", "off"):
+                enabled = False
+            elif s not in ("true", "yes", "1", "on"):
+                _warn(
+                    f"invalid spec_injection.enabled value: {raw_enabled!r}; "
+                    f"using true (default)"
+                )
+
+        # int() coercion stays local to this hook by decision (audit round,
+        # 2026-07-25): widening the shared common/config.py helpers has more
+        # blast radius than this small duplication costs.
+        for key, default_value in list(numbers.items()):
+            if key not in section:
+                continue
+            raw = section[key]
+            try:
+                value = int(raw)
+            except (TypeError, ValueError):
+                value = -1
+            if value < 0:
+                _warn(
+                    f"invalid spec_injection.{key} value: {raw!r}; "
+                    f"using default {default_value}"
+                )
+                continue
+            numbers[key] = value
+
+        if "tools" in section:
+            parsed_tools = _parse_tools(section["tools"])
+            if parsed_tools is None:
+                _warn(
+                    f"invalid spec_injection.tools value: {section['tools']!r}; "
+                    f"using default {list(DEFAULT_EDIT_TOOLS)}"
+                )
+            else:
+                tools = parsed_tools
+                unknown = [t for t in tools if t not in DEFAULT_EDIT_TOOLS]
+                if unknown:
+                    _warn(
+                        f"unknown spec_injection.tools entries {unknown} — "
+                        f"they will never match; known tools: "
+                        f"{list(DEFAULT_EDIT_TOOLS)}"
+                    )
+
+    return (
+        enabled,
+        numbers["max_spec_chars"],
+        numbers["max_total_chars"],
+        numbers["refresh_window_seconds"],
+        tools,
+    )
+
+
+# =============================================================================
+# Identity ladder
+# =============================================================================
+
+
+def _sanitize(raw: str) -> str:
+    """Map a session/agent id to a filename-safe, collision-free token.
+
+    A readable head (the first 80 characters, every character outside
+    ``[A-Za-z0-9_-]`` replaced one-for-one by ``-``) plus, whenever anything
+    was replaced or the id was longer than 80 characters, ``-`` and 8 hex of
+    sha256(raw). The suffix is what makes the mapping injective: without it,
+    "a/b" and "a:b" — or two ids sharing an 80-character prefix — would fold
+    onto one state file, and a collision that MISSES an injection is the
+    unacceptable failure. Output stays inside the GC name class.
+    """
+    raw = raw.strip()
+    head = raw[:80]
+    safe = re.sub(r"[^A-Za-z0-9_-]", "-", head)
+    if safe != head or len(raw) > 80:
+        digest = hashlib.sha256(raw.encode("utf-8")).hexdigest()[:8]
+        return f"{safe}-{digest}"
+    return safe
+
+
+def _shared_context_key(root: Path, payload: dict) -> str | None:
+    """Session/window key from the shared resolver every other hook uses.
+
+    ``common.active_task.resolve_context_key`` is the single source of truth
+    for session identity: payload keys in all casings (``session_id`` /
+    ``sessionId`` / ``sessionID``, conversation and transcript variants),
+    nested payload shapes, the explicit ``TRELLIS_CONTEXT_ID`` override,
+    per-platform env fallbacks, and Cursor shell tickets — plus the platform
+    fixes accumulated behind them. Payload identity is preferred over
+    environment context so two live sessions can never collapse onto one
+    exported env value (collision → missed injection is the unacceptable
+    direction); the environment pass still runs when the payload carries
+    nothing.
+    """
+    try:
+        _scripts_dir_on_path(root)
+        from common.active_task import resolve_context_key  # type: ignore[import-not-found]
+
+        key = resolve_context_key(payload, allow_environment_context=False)
+        if key:
+            return key
+        return resolve_context_key(payload)
+    except Exception:
+        return None
+
+
+def resolve_base_identity(root: Path, payload: dict) -> tuple[str, bool]:
+    """Return the base session identity for reset and refresh state.
+
+    When the shared resolver is unavailable (older installed scripts tree), a
+    minimal payload-only ladder keeps the hook working. ``stateless=True``
+    means no state IO is possible.
+    """
+    identity_payload = payload
+    if payload.get("hook_event_name") == "SessionStart":
+        # In this event `source` means startup/clear/compact, not platform.
+        # The shared resolver also accepts a generic `source` platform hint,
+        # so remove the lifecycle field to keep the same session identity as
+        # later PostToolUse events.
+        identity_payload = dict(payload)
+        identity_payload.pop("source", None)
+    key = _shared_context_key(root, identity_payload)
+
+    if not key:
+        # Minimal payload-only fallback for scripts trees that predate
+        # resolve_context_key. Mirrors its payload lookup order.
+        for k in ("session_id", "sessionId", "sessionID"):
+            value = payload.get(k)
+            if isinstance(value, str) and value.strip():
+                key = "s-" + value.strip()
+                break
+        if not key:
+            transcript = payload.get("transcript_path")
+            if isinstance(transcript, str) and transcript.strip():
+                digest = hashlib.sha256(
+                    transcript.strip().encode("utf-8")
+                ).hexdigest()
+                key = "t-" + digest[:16]
+
+    if not key:
+        return "", True
+
+    return _sanitize(key), False
+
+
+# =============================================================================
+# State (one append-only JSONL file per identity, locked, user-global)
+# =============================================================================
+
+
+def _state_base_dir() -> Path:
+    override = os.environ.get(STATE_ENV_DIR)
+    if override and override.strip():
+        return Path(override.strip())
+    return Path(os.path.expanduser(STATE_DEFAULT_DIR))
+
+
+def _project_id(root: Path) -> str:
+    return hashlib.sha256(os.path.realpath(str(root)).encode("utf-8")).hexdigest()[:16]
+
+
+def _maybe_gc(base_dir: Path) -> None:
+    """Prune conforming shards older than 48 h, at most once per hour.
+
+    Scope is exact-depth (``<base>/<project16>/<shard>.jsonl``) and name-gated;
+    foreign files and directories are never touched. Containment is enforced
+    against symlinks on both levels — a symlinked project dir or shard is
+    skipped outright, and every unlink candidate must still be under the
+    resolved base after realpath — so a planted link cannot walk this GC out
+    of its own tree. Best-effort, errors ignored.
+    """
+    try:
+        base_real = os.path.realpath(str(base_dir))
+        marker = base_dir / GC_MARKER
+        now = time.time()
+        try:
+            age = now - marker.stat().st_mtime
+        except OSError:
+            age = None
+        if age is not None and age < GC_INTERVAL_SECONDS:
+            return
+        try:
+            base_dir.mkdir(parents=True, exist_ok=True)
+            marker.touch()
+        except OSError:
+            return
+        try:
+            project_dirs = list(base_dir.iterdir())
+        except OSError:
+            return
+        for project_dir in project_dirs:
+            if not GC_PROJECT_DIR_RE.match(project_dir.name):
+                continue
+            try:
+                if project_dir.is_symlink() or not project_dir.is_dir():
+                    continue
+                shards = list(project_dir.iterdir())
+            except OSError:
+                continue
+            for shard in shards:
+                if not GC_SHARD_NAME_RE.match(shard.name):
+                    continue
+                try:
+                    if shard.is_symlink() or not shard.is_file():
+                        continue
+                    shard_real = os.path.realpath(str(shard))
+                    if not shard_real.startswith(base_real + os.sep):
+                        continue
+                    if now - shard.stat().st_mtime > STATE_MAX_AGE_SECONDS:
+                        shard.unlink()
+                except OSError:
+                    continue
+    except Exception:
+        pass
+
+
+def open_shard(shard_path: Path) -> int | None:
+    """Open (creating) the identity's shard for read+append.
+
+    Doubles as the writability probe: a failure here trips the circuit breaker
+    and the event runs stateless (ticket-only), which is bounded, instead of
+    re-emitting full specs on every event forever.
+    """
+    try:
+        shard_path.parent.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        _warn(f"state dir {shard_path.parent} unusable — running stateless")
+        return None
+    try:
+        return os.open(
+            str(shard_path),
+            os.O_RDWR | os.O_CREAT | os.O_APPEND,
+            0o644,
+        )
+    except OSError:
+        _warn(f"state shard {shard_path} unusable — running stateless")
+        return None
+
+
+def lock_shard(fd: int) -> None:
+    """Best-effort exclusive lock held across read→decide→append.
+
+    Closes the duplicate-injection race between concurrent hook processes on
+    POSIX. No fcntl (Windows) or an unsupported filesystem → no lock; the
+    worst case is a duplicate injection, never a lost one.
+    """
+    try:
+        import fcntl
+
+        fcntl.flock(fd, fcntl.LOCK_EX)
+    except Exception:
+        pass
+
+
+def unlock_shard(fd: int) -> None:
+    try:
+        import fcntl
+
+        fcntl.flock(fd, fcntl.LOCK_UN)
+    except Exception:
+        pass
+
+
+def load_state(
+    fd: int,
+    state_version: int,
+) -> tuple[dict[str, dict], str | None] | None:
+    """Read the shard through the already-open fd; newest record per spec wins
+    (``ts`` decides, and on an exact tie the later line in the file does —
+    appends are ordered, and two records one float apart must not resolve to
+    the older one). The latest reset marker is returned separately. Malformed
+    lines and foreign schema versions are skipped silently; read failures
+    return None so the caller uses stateless ticket mode."""
+    result: dict[str, dict] = {}
+    latest_reset: str | None = None
+    try:
+        os.lseek(fd, 0, os.SEEK_SET)
+        chunks: list[bytes] = []
+        while True:
+            chunk = os.read(fd, 1 << 20)
+            if not chunk:
+                break
+            chunks.append(chunk)
+    except OSError:
+        return None
+
+    text = b"".join(chunks).decode("utf-8", errors="replace")
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            record = json.loads(line)
+        except (json.JSONDecodeError, ValueError):
+            continue
+        if not isinstance(record, dict):
+            continue
+        if record.get("v") != state_version:
+            continue
+        spec = record.get("spec")
+        reset = record.get("reset")
+        if not isinstance(spec, str):
+            if isinstance(reset, str) and reset:
+                latest_reset = reset
+            continue
+        ts = record.get("ts")
+        if not isinstance(ts, (int, float)):
+            continue
+        previous = result.get(spec)
+        if previous is None or ts >= previous.get("ts", float("-inf")):
+            result[spec] = record
+    return result, latest_reset
+
+
+def append_records(fd: int, records: list[dict]) -> bool:
+    """Append records as JSONL (O_APPEND) and report whether all bytes landed."""
+    if not records:
+        return True
+    try:
+        blob = "".join(json.dumps(r, ensure_ascii=False) + "\n" for r in records)
+        encoded = blob.encode("utf-8")
+        if os.write(fd, encoded) != len(encoded):
+            _warn("could not write complete state shard — state may be incomplete")
+            return False
+        return True
+    except OSError:
+        _warn("could not write state shard — state may be incomplete")
+        return False
+
+
+# =============================================================================
+# Entry
+# =============================================================================
+
+
+def main() -> int:
+    if os.environ.get("TRELLIS_HOOKS") == "0" or os.environ.get("TRELLIS_DISABLE_HOOKS") == "1":
+        return 0
+
+    try:
+        input_data = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError, UnicodeDecodeError):
+        return 0
+    if not isinstance(input_data, dict):
+        return 0
+
+    cwd = input_data.get("cwd") or os.getcwd()
+    root = find_trellis_root(Path(cwd))
+    if root is None:
+        return 0
+    # Bail out before any spec scan when the project has no spec directory.
+    if not (root / DIR_WORKFLOW / DIR_SPEC).is_dir():
+        return 0
+
+    (
+        enabled,
+        max_spec_chars,
+        max_total_chars,
+        win_seconds,
+        tools,
+    ) = get_spec_injection_settings(root)
+    if not enabled:
+        return 0
+
+    _scripts_dir_on_path(root)
+    try:
+        from common.spec_inject import STATE_VERSION  # type: ignore[import-not-found]
+    except Exception:
+        return 0
+
+    if input_data.get("hook_event_name") == "SessionStart":
+        if input_data.get("source") not in ("clear", "compact"):
+            return 0
+        base_identity, stateless = resolve_base_identity(root, input_data)
+        if stateless:
+            _warn("SessionStart reset has no stable session identity")
+            return 0
+        base_dir = _state_base_dir()
+        _maybe_gc(base_dir)
+        reset_path = base_dir / _project_id(root) / f"{base_identity}.jsonl"
+        reset_fd = open_shard(reset_path)
+        if reset_fd is None:
+            return 0
+        try:
+            lock_shard(reset_fd)
+            append_records(
+                reset_fd,
+                [{"v": STATE_VERSION, "reset": uuid.uuid4().hex, "ts": time.time()}],
+            )
+        finally:
+            unlock_shard(reset_fd)
+            try:
+                os.close(reset_fd)
+            except OSError:
+                pass
+        return 0
+
+    event_name = input_data.get("hook_event_name")
+    tool_name = input_data.get("tool_name", "") or input_data.get("toolName", "")
+    if not isinstance(tool_name, str) or not tool_name:
+        return 0
+    is_pre_tool_use = event_name == "PreToolUse"
+    is_patch_tool = event_name == "PreToolUse" and tool_name == "apply_patch"
+    logical_tool = "Edit" if is_patch_tool else tool_name
+    # An empty `tools` list is the documented "disable every trigger" switch.
+    if not tools or logical_tool not in tools:
+        return 0
+
+    # snake_case is Claude Code's shape; camelCase keeps parity with the
+    # sibling hooks that already accept both (other platforms emit toolInput).
+    tool_input = input_data.get("tool_input")
+    if not isinstance(tool_input, dict):
+        tool_input = input_data.get("toolInput")
+    if not isinstance(tool_input, dict):
+        return 0
+    try:
+        from common.spec_match import (  # type: ignore[import-not-found]
+            match_specs_for_file,
+            normalize_repo_relative,
+        )
+        from common.spec_inject import (  # type: ignore[import-not-found]
+            assemble_payload,
+        )
+    except Exception:
+        return 0  # matching/decision engine unavailable — degrade to nothing
+
+    if is_patch_tool:
+        command = tool_input.get("command")
+        if not isinstance(command, str):
+            return 0
+        raw_paths = _patch_paths(command)
+    else:
+        file_path = tool_input.get("file_path")
+        if not isinstance(file_path, str) or not file_path.strip():
+            return 0
+        raw_paths = [file_path.strip()]
+
+    file_paths: list[str] = []
+    for raw_path in raw_paths:
+        normalized = normalize_repo_relative(root, raw_path)
+        if normalized is not None and normalized not in file_paths:
+            file_paths.append(normalized)
+    if not file_paths:
+        return 0
+
+    matches = []
+    match_files: dict[str, str] = {}
+    for file_path in file_paths:
+        for match in match_specs_for_file(root, file_path):
+            if match.rel_path in match_files:
+                continue
+            matches.append(match)
+            match_files[match.rel_path] = file_path
+    if not matches:
+        return 0
+
+    base_identity, stateless = resolve_base_identity(root, input_data)
+    identity = base_identity
+    agent = _agent_id(input_data)
+    if agent:
+        identity += "+a-" + _sanitize(agent)
+
+    state_records: dict[str, dict] = {}
+    clock = {"reset": None, "ts": time.time()}
+    fd: int | None = None
+
+    if not stateless:
+        base_dir = _state_base_dir()
+        _maybe_gc(base_dir)
+        project_dir = base_dir / _project_id(root)
+        base_fd = open_shard(project_dir / f"{base_identity}.jsonl")
+        if base_fd is None:
+            # Circuit breaker: unwritable state → ticket-only for this event.
+            stateless = True
+        else:
+            lock_shard(base_fd)
+            base_snapshot = load_state(base_fd, STATE_VERSION)
+            if base_snapshot is None:
+                stateless = True
+                unlock_shard(base_fd)
+                os.close(base_fd)
+            else:
+                base_records, reset_id = base_snapshot
+                if identity == base_identity:
+                    fd = base_fd
+                    state_records = base_records
+                else:
+                    unlock_shard(base_fd)
+                    os.close(base_fd)
+                    fd = open_shard(project_dir / f"{identity}.jsonl")
+                    if fd is None:
+                        stateless = True
+                    else:
+                        lock_shard(fd)
+                        snapshot = load_state(fd, STATE_VERSION)
+                        if snapshot is None:
+                            stateless = True
+                            unlock_shard(fd)
+                            os.close(fd)
+                            fd = None
+                        else:
+                            state_records, _ = snapshot
+
+                if not stateless:
+                    clock = {
+                        "reset": reset_id,
+                        "ts": time.time(),
+                    }
+
+    edited_rel = match_files[matches[0].rel_path]
+    records_persisted = True
+    try:
+        payload, records = assemble_payload(
+            edited_rel,
+            matches,
+            stateless,
+            state_records,
+            clock,
+            max_spec_chars,
+            max_total_chars,
+            win_seconds,
+            match_files=match_files,
+        )
+        if fd is not None and records:
+            records_persisted = append_records(fd, records)
+    finally:
+        if fd is not None:
+            unlock_shard(fd)
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+
+    if not payload:
+        return 0
+
+    hook_specific_output = {
+        "hookEventName": "PreToolUse" if is_pre_tool_use else "PostToolUse",
+        "additionalContext": payload,
+    }
+    if (
+        is_pre_tool_use
+        and records_persisted
+        and any(record.get("mode") == "full" for record in records)
+    ):
+        hook_specific_output.update(
+            {
+                "permissionDecision": "deny",
+                "permissionDecisionReason": (
+                    "Trellis injected governing specs. Review them, then retry "
+                    "this tool call."
+                ),
+            }
+        )
+    output = {"hookSpecificOutput": hook_specific_output}
+    print(json.dumps(output, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception:
+        # Hook failures must never break the tool result or the session.
+        sys.exit(0)

.codex/hooks/inject-subagent-context.py

@@ -215,11 +215,12 @@ def truncate_utf8(data: bytes, cap: int) -> bytes:
             seq_len = 4
         else:
             seq_len = 1
-        # Drop the lead byte too if its full sequence didn't fit.
+        # Cut before the lead byte when its full sequence didn't fit;
+        # otherwise the trailing sequence is complete — keep it whole.
         if (i - 1) + seq_len > len(truncated):
-            i -= 1
+            return truncated[: i - 1]
 
-    return truncated[:i]
+    return truncated
 
 
 class _Budget:
@@ -877,8 +878,15 @@ def _handle_codex_subagent_start(input_data: dict) -> None:
     if not subagent_type or not parent_session_id:
         return
 
-    cwd = _string_value(input_data.get("cwd")) or os.getcwd()
+    # Payload cwd first, then our own — some hosts (CodeBuddy IDE 4.10.4)
-    repo_root = find_repo_root(cwd)
+    # report "/" for every hook event. See inject-workflow-state.py.
+    repo_root = None
+    for candidate in (_string_value(input_data.get("cwd")), os.getcwd()):
+        if not candidate:
+            continue
+        repo_root = find_repo_root(candidate)
+        if repo_root:
+            break
     if not repo_root:
         return
 

.codex/hooks/inject-workflow-state.py

@@ -10,19 +10,24 @@ The emitted ``hookEventName`` field is platform-aware: most hosts expect
 CodeBuddy / Droid / Codex / Copilot wiring), but Gemini CLI 0.40.x renamed
 its per-turn event to ``BeforeAgent`` and its schema validator rejects the
 legacy name. ``_detect_platform`` picks the right value at runtime.
-Breadcrumb text is pulled exclusively from workflow.md
+Breadcrumb text is pulled exclusively from the resolved workflow file's
-[workflow-state:STATUS] tag blocks — workflow.md is the single source of
+[workflow-state:STATUS] tag blocks — the active task may select a
-truth. There are no fallback dicts in this script: when workflow.md is
+per-task variant (`.trellis/workflows/<id>.md` via task.json `workflow`),
+otherwise personal, team, and global defaults are resolved in order.
+There are no fallback dicts in this script: when the resolved workflow is
 missing or a tag is absent, the breadcrumb degrades to a generic
 "Refer to workflow.md for current step." line so users see (and fix)
 the broken state instead of the hook silently masking it.
 
-Shared across all hook-capable platforms (Claude, Cursor, Codex, Qoder,
+Which platforms register this hook is decided by SHARED_HOOKS_BY_PLATFORM
-CodeBuddy, Droid, Gemini, Copilot, Kiro). Kiro wires this via the CLI
+in templates/shared-hooks/index.ts — currently Claude, Codex, Gemini,
+Qoder, Copilot, CodeBuddy, Droid, Kiro, Trae and ZCode. That table is the
+source of truth; each listed platform's collect<Platform>Templates() pulls
+this file into its template map through collectSharedHooks(), and a single
+writer puts that map on disk at init time. Kiro wires this via the CLI
 custom agent's ``hooks.userPromptSubmit`` and the IDE ``.kiro.hook``
 ``promptSubmit`` event; its output branch emits a plain-text breadcrumb
-(Kiro adds hook stdout directly to the conversation context). Written to
+(Kiro adds hook stdout directly to the conversation context).
-each platform's hooks directory via writeSharedHooks() at init time.
 
 Silent exit 0 cases (no output):
   - No .trellis/ directory found (not a Trellis project)
@@ -95,11 +100,16 @@ def find_trellis_root(start: Path) -> Optional[Path]:
 def _detect_platform(input_data: dict) -> str | None:
     if isinstance(input_data.get("cursor_version"), str):
         return "cursor"
+    # CLAUDE_PROJECT_DIR is a compatibility alias that several hosts set
+    # alongside their own variable — CodeBuddy, ZCode and Trae all do. It must
+    # therefore be checked LAST, or every one of them is detected as claude and
+    # the context key becomes `claude_<their-session-id>`. That key does not
+    # match the session file `task.py start` wrote under the host's real name,
+    # so every turn reports no_task while the pointer exists on disk.
+    # Observed on CodeBuddy IDE 4.10.4: session file `codebuddy_ae54840e….json`
+    # alongside marker `update-check-claude_ae54840e….marker`, same id.
     env_map = {
-        # ZCode may set both ZCODE_PROJECT_DIR and CLAUDE_PROJECT_DIR; check
-        # ZCODE first so ZCode sessions aren't misdetected as claude.
         "ZCODE_PROJECT_DIR": "zcode",
-        "CLAUDE_PROJECT_DIR": "claude",
         "CURSOR_PROJECT_DIR": "cursor",
         "CODEBUDDY_PROJECT_DIR": "codebuddy",
         "FACTORY_PROJECT_DIR": "droid",
@@ -108,6 +118,8 @@ def _detect_platform(input_data: dict) -> str | None:
         "KIRO_PROJECT_DIR": "kiro",
         "COPILOT_PROJECT_DIR": "copilot",
         "TRAE_PROJECT_DIR": "trae",
+        # Last: the shared alias, only meaningful once no vendor key matched.
+        "CLAUDE_PROJECT_DIR": "claude",
     }
     for env_name, platform in env_map.items():
         if os.environ.get(env_name):
@@ -183,16 +195,40 @@ _TAG_RE = re.compile(
     re.DOTALL,
 )
 
-def load_breadcrumbs(root: Path) -> dict[str, str]:
+def _resolve_workflow_md(root: Path, input_data: dict) -> Path:
-    """Parse workflow.md for [workflow-state:STATUS] blocks.
+    """Resolve the active task's workflow file, falling back to the global one.
 
-    Returns {status: body_text}. workflow.md is the single source of
+    The per-task resolution rule lives in common.workflow_selection inside
+    .trellis/scripts. Older installed projects may not ship that module, and
+    hooks must never crash the session — ANY failure (import error, old
+    scripts tree, resolver bug) falls back to the global workflow.md.
+    """
+    try:
+        scripts_dir = root / ".trellis" / "scripts"
+        if str(scripts_dir) not in sys.path:
+            sys.path.insert(0, str(scripts_dir))
+        from common.workflow_selection import resolve_workflow_md  # type: ignore[import-not-found]
+
+        return resolve_workflow_md(
+            root, input_data, platform=_detect_platform(input_data)
+        )
+    except Exception:
+        return root / ".trellis" / "workflow.md"
+
+
+def load_breadcrumbs(root: Path, input_data: dict) -> dict[str, str]:
+    """Parse the resolved workflow file for [workflow-state:STATUS] blocks.
+
+    Returns {status: body_text}. The workflow file is the single source of
     truth — there are no fallback dicts in this script. Missing tags
-    (or a missing/unreadable workflow.md) fall back to a generic line
+    (or a missing/unreadable workflow file) fall back to a generic line
     in build_breadcrumb so users see the broken state and fix
     workflow.md, rather than the hook silently masking the issue.
+    The active task's per-task workflow selection (task.json `workflow`
+    field) is honored via _resolve_workflow_md; without a selection this
+    reads the global .trellis/workflow.md exactly as before.
     """
-    workflow = root / ".trellis" / "workflow.md"
+    workflow = _resolve_workflow_md(root, input_data)
     if not workflow.is_file():
         return {}
     try:
@@ -411,7 +447,7 @@ def main() -> int:
     if prompt_has_skip_keyword(data.get("prompt", ""), _resolve_skip_keyword(config)):
         return 0  # user opted out of the per-turn breadcrumb for this turn
 
-    templates = load_breadcrumbs(root)
+    templates = load_breadcrumbs(root, data)
     platform = _detect_platform(data)
     task = get_active_task(root, data)
     if task is None:

.codex/hooks/session-start.py

@@ -452,6 +452,25 @@ def _strip_breadcrumb_tag_blocks(content: str) -> str:
     return re.sub(r"\n{3,}", "\n\n", stripped).strip()
 
 
+def _resolve_workflow_md(root: Path, input_data: dict) -> Path:
+    """Resolve the active task's workflow file, falling back to the global one.
+
+    The per-task resolution rule lives in common.workflow_selection inside
+    .trellis/scripts. Older installed projects may not ship that module, and
+    hooks must never crash the session — ANY failure (import error, old
+    scripts tree, resolver bug) falls back to the global workflow.md.
+    """
+    try:
+        scripts_dir = root / ".trellis" / "scripts"
+        if str(scripts_dir) not in sys.path:
+            sys.path.insert(0, str(scripts_dir))
+        from common.workflow_selection import resolve_workflow_md  # type: ignore[import-not-found]
+
+        return resolve_workflow_md(root, input_data, platform="codex")
+    except Exception:
+        return root / ".trellis" / "workflow.md"
+
+
 def _build_workflow_toc(workflow_path: Path) -> str:
     """Inject only the compact Phase Index summary for SessionStart."""
     content = read_file(workflow_path)
@@ -505,7 +524,7 @@ Trellis compact SessionStart context. Use it to orient the session; load details
     output.write("\n</current-state>\n\n")
 
     output.write("<trellis-workflow>\n")
-    output.write(_build_workflow_toc(trellis_dir / "workflow.md"))
+    output.write(_build_workflow_toc(_resolve_workflow_md(project_dir, hook_input)))
     output.write("\n</trellis-workflow>\n\n")
 
     output.write("<guidelines>\n")

.gitea/workflows/deploy-production.yaml

@@ -8,8 +8,8 @@ on:
 
 jobs:
   deploy:
-    runs-on: ubuntu-latest
+    runs-on: tencent-prod
-    timeout-minutes: 30
+    timeout-minutes: 60
 
     env:
       COMPOSE_PROJECT_NAME: zhixing-system

.pi/extensions/trellis/index.ts

@@ -772,10 +772,11 @@ function truncateUtf8(buf: Buffer, cap: number): Buffer {
     if ((lead & 0xe0) === 0xc0) seqLen = 2;
     else if ((lead & 0xf0) === 0xe0) seqLen = 3;
     else if ((lead & 0xf8) === 0xf0) seqLen = 4;
-    // Drop the lead byte too if its full sequence didn't fit.
+    // Cut before the lead byte when its full sequence didn't fit;
-    if (i - 1 + seqLen > cap) i--;
+    // otherwise the trailing sequence is complete — keep it whole.
+    if (i - 1 + seqLen > cap) return buf.subarray(0, i - 1);
   }
-  return buf.subarray(0, i);
+  return buf.subarray(0, cap);
 }
 
 function stripInlineComment(value: string): string {
@@ -1069,10 +1070,66 @@ function readTaskDir(root: string, key: string | null): string | null {
 }
 
 // ── Workflow State Breadcrumb ─────────────────────────────────────────
+const WORKFLOW_ID_RE = /^[A-Za-z0-9_-]+$/;
+const DEFAULT_WORKFLOW_RE =
+  /^default_workflow:\s*(['"]?)([A-Za-z0-9_-]+)\1\s*(?:#.*)?$/m;
+
+function workflowVariant(root: string, workflowId: string): string {
+  if (!WORKFLOW_ID_RE.test(workflowId)) return "";
+  const path = join(root, ".trellis", "workflows", `${workflowId}.md`);
+  return exists(path) ? path : "";
+}
+
+function developerWorkflowId(root: string): string {
+  for (const line of readText(join(root, ".trellis", ".developer")).split(
+    /\r?\n/,
+  )) {
+    if (line.startsWith("workflow="))
+      return line.slice("workflow=".length).trim();
+  }
+  return "";
+}
+
+function configDefaultWorkflowId(root: string): string {
+  return (
+    readText(join(root, ".trellis", "config.yaml")).match(
+      DEFAULT_WORKFLOW_RE,
+    )?.[2] ?? ""
+  );
+}
+
+/** Mirrors common/workflow_selection.py without spawning another Python
+ * process on every Pi turn. Invalid or missing selections fall through. */
+function resolveWorkflowMd(root: string, key: string | null): string {
+  const taskDir = readTaskDir(root, key);
+  let workflowId = "";
+  if (taskDir) {
+    try {
+      const task = JSON.parse(
+        readText(join(taskDir, "task.json")),
+      ) as JsonObject;
+      workflowId = typeof task.workflow === "string" ? task.workflow : "";
+    } catch {}
+  }
+  if (workflowId) {
+    const pinned = workflowVariant(root, workflowId);
+    if (pinned) return pinned;
+    console.error(
+      `Warning: active task selects workflow ${JSON.stringify(workflowId)} but .trellis/workflows/ has no matching file; using default workflow resolution`,
+    );
+  }
+
+  const personal = workflowVariant(root, developerWorkflowId(root));
+  if (personal) return personal;
+  const team = workflowVariant(root, configDefaultWorkflowId(root));
+  if (team) return team;
+  return join(root, ".trellis", "workflow.md");
+}
+
 const WF_RE =
   /\[workflow-state:([A-Za-z0-9_-]+)\]\s*\n([\s\S]*?)\n\s*\[\/workflow-state:\1\]/g;
 function workflowBreadcrumb(root: string, key: string | null): string {
-  const wf = readText(join(root, ".trellis", "workflow.md"));
+  const wf = readText(resolveWorkflowMd(root, key));
   if (!wf) return "";
   const templates: Record<string, string> = {};
   for (const m of wf.matchAll(WF_RE)) {

.trellis/.template-hashes.json

@@ -24,7 +24,7 @@
     ".agents/skills/trellis-meta/references/customize-local/change-task-lifecycle.md": "60ff9efb93604b87a461a4af30322d76750402a51e40f31531a7ff88d309996d",
     ".agents/skills/trellis-meta/references/customize-local/change-workflow.md": "43fa780a2ca580de121b10893d49b99f978873deebbf45008c466e5ac6651519",
     ".agents/skills/trellis-meta/references/customize-local/overview.md": "ce8f09e9f93ce9a48500763fb3a4db2b3908a5fbf4f985ab71dacebb404cf8f4",
-    ".agents/skills/trellis-meta/references/local-architecture/bundled-skills.md": "7a8d1a5dcc8d1140c4c6bd19d02949364cdd01801bd0825a975a308cf85b8f37",
+    ".agents/skills/trellis-meta/references/local-architecture/bundled-skills.md": "aa6a0bf83060205ee4ea621c467fb900a7db06b4476a4ad472cc4e248c887389",
     ".agents/skills/trellis-meta/references/local-architecture/context-injection.md": "8497289bf333b3aa456f317039d1239b7ece79254aa0eb62cfc647714c866084",
     ".agents/skills/trellis-meta/references/local-architecture/generated-files.md": "7eb2d452eddb4f4226f7578c2ec6d5ee0434ed172ba4c36107cc8bdff7554dc6",
     ".agents/skills/trellis-meta/references/local-architecture/multi-agent-channel.md": "56e5070474aeca872e2d70c46feea5aaafecd3d3ec052c3f7b1877358dca62e9",
@@ -34,7 +34,7 @@
     ".agents/skills/trellis-meta/references/local-architecture/workflow.md": "cfcdc6e4468a5d9c816e929fcca01640cd41cfdaaa4824118b40a8e460c927b6",
     ".agents/skills/trellis-meta/references/local-architecture/workspace-memory.md": "e6427b46aba744563c2444b30df4043cd856561b7709ec2dece26095416421fd",
     ".agents/skills/trellis-meta/references/platform-files/agents.md": "9f41349b78f7ae64698a38490a317882561f3805b26a79bda587a13d03fda245",
-    ".agents/skills/trellis-meta/references/platform-files/hooks-and-settings.md": "154af08f7ee8afe7a704968ec0b9fc21e905b7cfb03871c9dbafcdd6cc654319",
+    ".agents/skills/trellis-meta/references/platform-files/hooks-and-settings.md": "cb7c1c7dd976004e4981181ab9462f8eedc4e9c014721419bd666d6608f4dd72",
     ".agents/skills/trellis-meta/references/platform-files/overview.md": "1aec9087ccedd56a213af877b5db474131aa4b4789b6ac0e8da73b058aa43bd4",
     ".agents/skills/trellis-meta/references/platform-files/platform-map.md": "9e476e500f10b2a1a05278dd700837deb731a77e3f3993e90f8102528a9bdcca",
     ".agents/skills/trellis-meta/references/platform-files/skills-and-commands.md": "e39831d860bd27a04e7757f7bd941ab83b3c5b11ad4460cec03975b655f26cc3",
@@ -50,10 +50,10 @@
     ".codex/agents/trellis-check.toml": "79070c63fa404fc53061cca5194bf66db839132b67a57b9c8d6a295037ba7308",
     ".codex/agents/trellis-implement.toml": "388fb8f39797e0ee6cf4db447c859c79b4ac15f531f7e1e3c68c1d1d71a1c188",
     ".codex/agents/trellis-research.toml": "4435ce73197ba1d29d40359a3279b6423f7e4f559a449f934c016808090066c4",
-    ".codex/hooks/session-start.py": "14de3be1cf6eb9c9feba348d8998b407f3837d6c0756b74210c9200543440677",
+    ".codex/hooks/session-start.py": "91fbbd30ac974c3cd2b4db152aa38ac176a9c7e3d062cbaa1acacf07152b2592",
-    ".codex/hooks/inject-subagent-context.py": "abffa237eb53f87ae6ffa434063b46b03d58a36a84cdb8fe88bfc5f243aab609",
+    ".codex/hooks/inject-subagent-context.py": "db413933ff30e1503f37f1d292fb421b1ced3f39f1890351a6621e499ec16b2c",
-    ".codex/hooks/inject-workflow-state.py": "9ce43910ac39cbb0e4d1783fbde931761eb04536c7f82661a96d95ea72c14bde",
+    ".codex/hooks/inject-workflow-state.py": "cda5888c29671035e7d2e033a0fcc631a9428a0543fb2dd071285b30c6ca4e23",
-    ".codex/hooks.json": "85a58ba7cdf1e19e7f75ddcc64e5680180c487ca266a74bd5005f31abeee2e02",
+    ".codex/hooks.json": "c16c9af7f6010bf4fabb64fd4bd497201d34583b96c665ea1d5739eed48b3fb5",
     ".codex/config.toml": "9f2d20e28f0bc9c886312eca3ad3bba41533ef4615aaaafe25e98152302267bb",
     ".pi/prompts/trellis-start.md": "28af1eb6645d8b517cf705277d8405370b712926e6b01667d6698564002c6a9d",
     ".pi/prompts/trellis-continue.md": "12c2f0288ff67af3368c0b577a50027a11a25fec1d32ed34282a4dc84be08f1c",
@@ -61,40 +61,44 @@
     ".pi/agents/trellis-check.md": "1dbfedd3403f201fbfdbae8d810afba0a1f812b97f0f8e308908db7eaceea496",
     ".pi/agents/trellis-implement.md": "9bb1f70d09b7104a671ef9a0ba072b4500d45b8556a253126a003e2b1e7281a2",
     ".pi/agents/trellis-research.md": "ef77555f4c2c4ade36f1c23a076b6f4bb9d180ff24a2f00d7cdc2f8fd5af0b0a",
-    ".pi/extensions/trellis/index.ts": "b4bfd740d517462f943aaff920dd39371d3e6bdc3823dfa8c2752314c57eaf9b",
+    ".pi/extensions/trellis/index.ts": "770290e675fabfe0dd0889771876607927d36cb9ef68586552e6e2d56ca345fc",
     ".pi/settings.json": "b68f37c04a7007d2b52d5a87326e3786edbc903bfa518358830dd85727c13d7c",
     "AGENTS.md": "6cacfe99748b435d0660c2463c697bc323d53798aecf3492283ca8eac1b29682",
     ".trellis/agents/check.md": "edb4f57361407249a53bf5998ebf91c40d2b969e826a2c5e1b4e813a08bcb175",
     ".trellis/agents/implement.md": "66e25ad046c94869442834bc3cdfbd5a9a7412d3ff54561d64d2886552c27e87",
-    ".trellis/config.yaml": "a966e6d374e9e6ff283cf761ccd99631323ee1754856cef51ad154ca0afb9dfa",
+    ".trellis/config.yaml": "eaba56c36fb07483fcbc96d74c4da0ab33b9739fb9ff10ea4cc1e1cd32bf23b2",
     ".trellis/scripts/__init__.py": "1242be5b972094c2e141aecbe81a4efd478f6534e3d5e28306374e6a18fcf46c",
     ".trellis/scripts/add_session.py": "876dad478edf70db59acccaae9cb4db646a155681f730bd99af48de72ddc9881",
     ".trellis/scripts/common/__init__.py": "3d5e9347141f0296319a5beb29d69ae714c5a474b9078caeb3edd7c5f6562e22",
-    ".trellis/scripts/common/active_task.py": "31271e3b69b5a5eca958d8ce25f61fe852eb6e48d32c150471da8e7272fd6119",
+    ".trellis/scripts/common/active_task.py": "28a81f8828538fb70a15c88edd90eda9d685adbde8862f67f630bce5b27d9832",
     ".trellis/scripts/common/cli_adapter.py": "5d6bd9d6f5c631e7e792db7dd343351317f9643bc87b73a9a98abd51cefb4307",
-    ".trellis/scripts/common/config.py": "8d2e5f8ccfcd5f622cd2af002aa761f3d3ffcc653182fefb2268afd102e77bca",
+    ".trellis/scripts/common/config.py": "43a22c4e88a06d6316d1bcd4730731bdecc22ae782e9f217b25ea53aa85cd416",
     ".trellis/scripts/common/developer.py": "f5f833123abe68890171b4da825a324216d24913f6b5ad9245afc556424ffd7b",
     ".trellis/scripts/common/git.py": "6fc5845d0104dd506ebd8b366a24cb4b1e3d8777e4e6acc12ea15c9d8e2662f2",
-    ".trellis/scripts/common/git_context.py": "fa30ced454f1a91ffc9f8b2abeb32225e3447cbdc90bad783797374eba07265d",
+    ".trellis/scripts/common/git_context.py": "be0c68d4b566319484cf95a3ca6d6dee18e00f040cecadea6a98f10dc445f967",
     ".trellis/scripts/common/io.py": "75648caae03d5b1107d7aeccaa785d133b25762266e54a520d90ca8c76b43bdb",
     ".trellis/scripts/common/log.py": "471df6895cfac80f995edebbf9974f6b7440634b7a688f28b8331c868bc0f3cf",
     ".trellis/scripts/common/packages_context.py": "efe158d7c99c2268851d0216fbb08de22836e418a8dbeb73575b8cc249eed7b7",
-    ".trellis/scripts/common/paths.py": "05898ef136cc7c4d861b05fbf2b16d53ddd3e6f311a231d4fcfcb81bde7c45ee",
+    ".trellis/scripts/common/paths.py": "5f66eb073c296a8a920048c1c53d8236783ccb998c8c25a68a540534d30abd02",
     ".trellis/scripts/common/safe_commit.py": "baa5c82324eb62154374ec63394ecdc8609bb37d93892e3bcb88f452bb7d6446",
-    ".trellis/scripts/common/session_context.py": "4ed3e13b2878ba367e9f2e2cd709b396f806152902df2cd1cd1478317d069017",
+    ".trellis/scripts/common/session_context.py": "3379ef1766e4e5ca77cbb7c040dbba3883fcca2548580299e3b38dbf22f4f7d5",
-    ".trellis/scripts/common/task_context.py": "4ea260a022f4122361eb0d9dd9200a9324aeafbdb20cadd2848bea1649938f1d",
+    ".trellis/scripts/common/task_context.py": "be5fa407f99c2400075194dbaa8b6ec996ce8aac2122d191bb9cb11e479a9476",
     ".trellis/scripts/common/task_queue.py": "0be61f713462b1fe4574927c82fc4704e678afe72dcb9813543aedf2f9e9e0c5",
-    ".trellis/scripts/common/task_store.py": "e3c2fbf8b79b591e39fc3c9f4e2f3ee0c840c8201c94a16709ec743fa45037f6",
+    ".trellis/scripts/common/task_store.py": "793b9e7863fade04b0d84c7668bacb4229c435f0fcdba008bd333421ec3e17b3",
     ".trellis/scripts/common/task_utils.py": "90c0a6d50bad502c3f01cb24c1ccfeb0eece5e2c69efaff8d65eb827fba43871",
     ".trellis/scripts/common/tasks.py": "4436a8b0b53c270a35989e26d9dbd92669408c6562d88c02083a404562da85fe",
     ".trellis/scripts/common/trellis_config.py": "e282e897183e3ec2f4e6e56349431946e5f98c1c31d3eca4de7fc44e1383a7bf",
     ".trellis/scripts/common/types.py": "9962081cc2608fb9d1deb32c6880e336f62cdca6b338e7ae813304701e155ee9",
-    ".trellis/scripts/common/workflow_phase.py": "79ee522de20246acf1e2c222e8ad180ad25aaec7fec98214a93d9e81b350d9a8",
+    ".trellis/scripts/common/workflow_phase.py": "c3d00011a4d8c3d958ec57cea50b97f4170dce7c28381ad3915dae0870167d6e",
     ".trellis/scripts/get_context.py": "ca5bf9e90bdb1d75d3de182b95f820f9d108ab28793d29097b24fd71315adcf5",
     ".trellis/scripts/get_developer.py": "84c27076323c3e0f2c9c8ed16e8aa865e225d902a187c37e20ee1a46e7142d8f",
     ".trellis/scripts/hooks/linear_sync.py": "e09cc4ce4699aada908808718698f33f705a3edf55c4dcf8f777ad892f80ca79",
     ".trellis/scripts/init_developer.py": "f9e6c0d882406e81c8cd6b1c5abb204b0befc0069ff89cf650cd536a80f8c60e",
-    ".trellis/scripts/task.py": "e0ffed9f14994069f0c992141e3ec168524be5af32e3681e6ea30ba0a5da4bc4",
+    ".trellis/scripts/task.py": "7790d9510311d55ed1f66c71b9ce0bafc8871f1b675c1251dcf6a1f4e823d2b3",
-    ".trellis/workflow.md": "e2c5ab7004ff83a5a804b50df81746aa1d558dd4480463287622605f86a82a76"
+    ".trellis/workflow.md": "e2c5ab7004ff83a5a804b50df81746aa1d558dd4480463287622605f86a82a76",
+    ".trellis/scripts/common/workflow_selection.py": "b136d6ae41aac95f4d5f425b641b62b7002f7cff2d26aa44b056cef9a2242753",
+    ".trellis/scripts/common/spec_match.py": "baf3b17b15c279475f99699ac6e039bc68285d5dbfbda28f279aa8346cb0c59a",
+    ".trellis/scripts/common/spec_inject.py": "9987d213eed3d2ec1b2c16adcad8b10a21d3b68dcce838f85c42d83c56e69e0b",
+    ".codex/hooks/inject-spec-context.py": "4df3945be18163afe066ec3061d8b95a687f676e3a80dbf0aada4dec8c339f90"
   }
 }

.trellis/.version

@@ -1 +1 @@
-0.6.12
+0.7.0-beta.3

.trellis/config.yaml

@@ -76,6 +76,21 @@ max_journal_lines: 2000
 # Default package used when --package is not specified.
 # default_package: frontend
 
+#-------------------------------------------------------------------------------
+# Default workflow
+#-------------------------------------------------------------------------------
+# Team-shared default workflow for tasks that do not pin one. The id names a
+# variant file in `.trellis/workflows/<id>.md` (populate it with
+# `trellis workflow --save <id>`). This value is committed, so the whole team
+# shares the same default. A per-developer override lives in the gitignored
+# `.developer` file as a `workflow=<id>` line and takes precedence over this.
+#
+# Resolution precedence: per-task (task.json `workflow`) > personal
+# (`.developer` `workflow=`) > this `default_workflow` > global
+# `.trellis/workflow.md`.
+#
+# default_workflow: native
+
 #-------------------------------------------------------------------------------
 # Channel worker OOM guard
 #-------------------------------------------------------------------------------
@@ -145,6 +160,38 @@ channel:
 #   max_artifact_bytes: 65536    # per task artifact (prd.md / design.md / implement.md)
 #   max_total_bytes: 131072      # whole injected payload; overflow degrades to index lines
 
+#-------------------------------------------------------------------------------
+# Path-scoped spec injection
+#-------------------------------------------------------------------------------
+# When the agent touches a file (Read/Edit/Write/MultiEdit), spec .md files
+# under .trellis/spec/ whose frontmatter `paths:` globs match the touched path
+# are surfaced into the session right then. The first time a spec matches it is
+# injected in full; while its content is unchanged and the refresh window has
+# not elapsed it stays silent; once the window elapses a short `<spec-ticket>`
+# reminder is emitted to counter recency decay. Editing the spec itself — or a
+# SessionStart after /clear or /compact — re-injects the full text.
+# Oversized specs are truncated with a notice; once the per-event payload cap
+# is reached, remaining full bodies degrade to index lines (path + description)
+# instead of being inlined.
+#
+# Character values: the ceiling this budget respects is Claude Code's
+# documented 10,000-CHARACTER additionalContext limit, so the caps count
+# characters too (byte caps made CJK specs pay 3x for the same text).
+# `0` disables the corresponding limit.
+# The refresh window uses wall-clock seconds. `0` disables time-based reminders;
+# SessionStart resets after /clear or /compact still force a full re-injection.
+#
+# spec_injection:
+#   enabled: true                 # false disables injection entirely
+#   max_spec_chars: 9400          # per matched spec file
+#   max_total_chars: 9500         # whole per-event payload; overflow degrades to index lines
+#   refresh_window_seconds: 2700  # touches past this interval re-emit a ticket
+#   tools:                        # tool events that trigger injection
+#     - Read
+#     - Edit
+#     - Write
+#     - MultiEdit
+
 #-------------------------------------------------------------------------------
 # Per-turn prompt injection
 #-------------------------------------------------------------------------------

.trellis/scripts/common/active_task.py

@@ -23,8 +23,15 @@ DIR_WORKFLOW = ".trellis"
 DIR_TASKS = "tasks"
 DIR_RUNTIME = ".runtime"
 DIR_SESSIONS = "sessions"
-DIR_CURSOR_SHELL = "cursor-shell"
+DIR_SHELL_TICKETS = "shell-tickets"
-CURSOR_SHELL_TICKET_TTL_SECONDS = 30
+# Pre-0.6.13 name, when the bridge was Cursor-only. Still read so a session that
+# was mid-command across an upgrade does not silently degrade; never written.
+# Tickets are 30-second ephemera, so the old directory ages out by itself —
+# there is nothing to migrate, only a glob on a directory that is normally
+# absent. The alternative (ignore it) would land its one lost command on the
+# platform that works today.
+DIR_LEGACY_CURSOR_SHELL_TICKETS = "cursor-shell"
+SHELL_TICKET_TTL_SECONDS = 30
 TASK_SESSION_COMMANDS = {"start", "current", "finish"}
 
 _SESSION_KEYS = ("session_id", "sessionId", "sessionID")
@@ -50,35 +57,75 @@ _KNOWN_PLATFORMS = {
     "snow",
 }
 
+# Every name below records how it was checked. Do NOT add a name by analogy
+# with a neighbour: a 2026-08-05 audit of all 21 platforms found 12 of the 21
+# declared names had never existed anywhere — they were pattern-guessed from a
+# `<PLATFORM>_SESSION_ID` shape no vendor agreed to, and the uniformity was the
+# only "evidence" behind them. A platform with no verified name belongs in no
+# table; it resolves through TRELLIS_CONTEXT_ID or its hook/plugin bridge.
 _ENV_SESSION_KEYS: tuple[tuple[str, tuple[str, ...]], ...] = (
-    ("claude", ("CLAUDE_SESSION_ID", "CLAUDE_CODE_SESSION_ID")),
+    # REAL, undocumented (verified 2026-08-05 in a live Claude Code 2.1.221 bash
-    ("codex", ("CODEX_SESSION_ID", "CODEX_THREAD_ID")),
+    # child; absent from code.claude.com/docs/en/env-vars). CLAUDE_SESSION_ID
-    ("cursor", ("CURSOR_SESSION_ID",)),
+    # was removed here — verified absent from that same live environment.
-    ("opencode", ("OPENCODE_SESSION_ID", "OPENCODE_SESSIONID", "OPENCODE_RUN_ID")),
+    ("claude", ("CLAUDE_CODE_SESSION_ID",)),
+    # REAL, undocumented (verified 2026-08-05: injected by codex-cli 0.146.0
+    # into shell children, absent from the parent env; openai/codex#19937).
+    # CODEX_SESSION_ID was removed — absent from a live `codex exec` env.
+    ("codex", ("CODEX_THREAD_ID",)),
+    # REAL but HOOK-SCOPE ONLY (verified 2026-08-05): set by Gemini's
+    # hookRunner.ts. Its shell tool builds the child env in
+    # shellExecutionService.ts and adds only GEMINI_CLI/TERM/PAGER/GIT_PAGER, so
+    # this never reaches a bash child — it resolves only inside a hook process.
     ("gemini", ("GEMINI_SESSION_ID",)),
-    ("droid", ("FACTORY_SESSION_ID", "DROID_SESSION_ID")),
+    # REAL but HOOK-SCOPE ONLY (verified 2026-08-05): docs.qoder.com/zh/
+    # extensions/hooks documents it as injected during hook execution by the
+    # Qoder *IDE plugin*. Absent from the Qoder CLI hook docs and from Lingma.
     ("qoder", ("QODER_SESSION_ID",)),
-    ("codebuddy", ("CODEBUDDY_SESSION_ID",)),
+    # UNVERIFIED (2026-08-05): absent from kiro.dev/docs/hooks/, but Dynatrace
+    # dtctl, oh-my-agent and gastown all key agent detection on it and one notes
+    # it is "set in both interactive and --no-interactive". Kept because that is
+    # absence of evidence, not evidence of absence. To settle: run
+    # `env | grep KIRO` from a Kiro shell-tool call on a machine with Kiro.
     ("kiro", ("KIRO_SESSION_ID",)),
+    # UNVERIFIED (2026-08-05): absent from docs.github.com/en/copilot/reference/
+    # hooks-reference and from the CLI programmatic reference. To settle: run
+    # `copilot help environment` (the authoritative list per those docs) — not
+    # runnable here, the CLI is not installed and copilot-cli ships no source.
     ("copilot", ("COPILOT_SESSION_ID", "COPILOT_SESSIONID")),
-    ("pi", ("PI_SESSION_ID", "PI_SESSIONID")),
+    # REASONED, UNVERIFIED (2026-08-05): ZCode is closed-source and not
-    ("trae", ("TRAE_SESSION_ID",)),
+    # installable here. It mirrors Claude's naming elsewhere (CLAUDE_PLUGIN_ROOT
-    # ZCode reuses CLAUDE_SESSION_ID (it does not document a ZCODE_SESSION_ID).
+    # / CLAUDE_PLUGIN_DATA compat aliases are in its docs), and the previously
-    # Platform-scoped lookup (_iter_env_keys filters by platform name), so this
+    # declared CLAUDE_SESSION_ID does not exist on Claude Code either — so the
-    # only fires when the resolver already detected "zcode" — no collision with
+    # name ZCode would actually reuse is CLAUDE_CODE_SESSION_ID. Try that first,
+    # keep the historical name as a fallback: if neither exists nothing changes.
+    # Platform-scoped lookup (_iter_env_keys filters by platform name), so the
+    # entry only fires once the resolver detected "zcode" — no collision with
     # the claude entry above.
-    ("zcode", ("CLAUDE_SESSION_ID",)),
+    ("zcode", ("CLAUDE_CODE_SESSION_ID", "CLAUDE_SESSION_ID")),
-    # Snow CLI exports SNOW_SESSION_ID into hook/terminal/sub-agent children.
+    # REAL by vendor design (verified 2026-08-05): Snow's sessionIdentityEnv.ts
-    # TRELLIS_CONTEXT_ID remains the preferred override when present.
+    # exports SNOW_SESSION_ID into hook/terminal/sub-agent children and names
+    # Trellis in its source header. TRELLIS_CONTEXT_ID stays the preferred
+    # override — Snow sets that too.
     ("snow", ("SNOW_SESSION_ID",)),
 )
 _ENV_CONVERSATION_KEYS: tuple[tuple[str, tuple[str, ...]], ...] = (
+    # REAL in cursor-agent (CLI), undocumented (verified 2026-08-05: the value
+    # matches ~/.cursor/chats/<ws>/<id>). The Cursor *IDE* is unverified — a
+    # 2026-05 forum request for it drew no staff reply. The invented
+    # CURSOR_SESSION_ID was removed from the session table: empty in a live
+    # cursor-agent shell. Cursor's other path is the shell ticket below
+    # (_lookup_shell_ticket_context_key), which is not Cursor-specific.
     ("cursor", ("CURSOR_CONVERSATION_ID", "CURSOR_CONVERSATIONID")),
 )
 _ENV_TRANSCRIPT_KEYS: tuple[tuple[str, tuple[str, ...]], ...] = (
-    ("claude", ("CLAUDE_TRANSCRIPT_PATH",)),
+    # REAL but HOOK-SCOPE ONLY (verified 2026-08-05): documented for Cursor hook
-    ("codex", ("CODEX_TRANSCRIPT_PATH",)),
+    # scripts; empty in the agent's own shell env.
     ("cursor", ("CURSOR_TRANSCRIPT_PATH",)),
+    # UNVERIFIED — never researched. The 2026-08-05 audit covered the session
+    # table only, so do not infer these are real *or* fake from that work
+    # (CLAUDE_/CODEX_TRANSCRIPT_PATH were removed because those two *were*
+    # checked: absent from docs and from live envs). To settle each: run
+    # `env | grep _TRANSCRIPT_PATH` inside a hook and inside a shell-tool call.
     ("gemini", ("GEMINI_TRANSCRIPT_PATH",)),
     ("droid", ("FACTORY_TRANSCRIPT_PATH", "DROID_TRANSCRIPT_PATH")),
     ("qoder", ("QODER_TRANSCRIPT_PATH",)),
@@ -90,11 +137,15 @@ _ENV_PLATFORM_ALIASES = {
     "factory-ai": "droid",
     "github-copilot": "copilot",
 }
-# ZCode intentionally reuses CLAUDE_SESSION_ID. Hooks know the host is ZCode,
+# ZCode intentionally reuses Claude's session env var name. Hooks know the host
-# while later shell commands see only the shared env name and resolve it through
+# is ZCode, while later shell commands see only the shared env name and resolve
-# the Claude entry. Canonicalize both paths to one runtime filename.
+# it through the claude entry. Canonicalize both paths to one runtime filename.
 _CONTEXT_KEY_PLATFORM_ALIASES = {
     "zcode": "claude",
+    # Factory Droid's config directory is `.factory/`, so a hook that names its
+    # platform after the directory it was installed in reports "factory". Its
+    # sibling hooks report "droid". One runtime filename either way.
+    "factory": "droid",
 }
 
 
@@ -222,6 +273,12 @@ def _iter_env_keys(
     env_keys: tuple[tuple[str, tuple[str, ...]], ...],
     platform_name: str | None,
 ) -> tuple[tuple[str, tuple[str, ...]], ...]:
+    """Narrow an env-key table to one platform, or return all of it.
+
+    A platform with no entry yields an empty tuple, and the caller's `for` loop
+    simply does not run. That is the normal case, not an error: platforms with
+    no verified env var name are deliberately absent from these tables.
+    """
     if not platform_name:
         return env_keys
     matched = tuple((name, keys) for name, keys in env_keys if name == platform_name)
@@ -275,8 +332,12 @@ def _find_repo_root_from_cwd() -> Path | None:
         current = current.parent
 
 
-def _cursor_shell_ticket_dir(repo_root: Path) -> Path:
+def _shell_ticket_dirs(repo_root: Path) -> tuple[Path, ...]:
-    return repo_root / DIR_WORKFLOW / DIR_RUNTIME / DIR_CURSOR_SHELL
+    runtime_dir = repo_root / DIR_WORKFLOW / DIR_RUNTIME
+    return (
+        runtime_dir / DIR_SHELL_TICKETS,
+        runtime_dir / DIR_LEGACY_CURSOR_SHELL_TICKETS,
+    )
 
 
 def _remove_file(path: Path) -> bool:
@@ -334,7 +395,7 @@ def _ticket_is_fresh(ticket: dict[str, Any], ticket_path: Path, now: float) -> b
 
     created_at = ticket.get("created_at_epoch")
     if isinstance(created_at, (int, float)):
-        if now - created_at <= CURSOR_SHELL_TICKET_TTL_SECONDS:
+        if now - created_at <= SHELL_TICKET_TTL_SECONDS:
             return True
         _remove_file(ticket_path)
         return False
@@ -352,13 +413,18 @@ def _ticket_cwd_matches_repo(ticket: dict[str, Any], repo_root: Path) -> bool:
     return True
 
 
-def _matching_cursor_ticket_context_key(
+def _matching_ticket_context_key(
     ticket_path: Path,
     repo_root: Path,
     now: float,
 ) -> str | None:
+    """Accept a ticket on its merits, never on which platform wrote it.
+
+    The `platform` field a ticket carries is debugging metadata; gating on it
+    was what kept this bridge invisible to every platform but Cursor.
+    """
     ticket = _read_json(ticket_path)
-    if ticket is None or ticket.get("platform") != "cursor":
+    if ticket is None:
         return None
     if not _ticket_is_fresh(ticket, ticket_path, now):
         return None
@@ -369,27 +435,28 @@ def _matching_cursor_ticket_context_key(
     return _string_value(ticket.get("context_key"))
 
 
-def _lookup_cursor_shell_ticket_context_key() -> str | None:
+def _lookup_shell_ticket_context_key() -> str | None:
-    """Resolve Cursor conversation identity from a short-lived shell ticket.
+    """Resolve session identity from a short-lived shell ticket.
 
-    Cursor exposes `conversation_id` to `beforeShellExecution`, but does not
+    No researched platform exports its session id into a shell child, but every
-    export it into the shell command environment. The Cursor hook writes a
+    hook-capable one hands that id to a hook. So the hook that runs just before
-    short-lived ticket just before `task.py` runs. We accept a ticket only when
+    a shell command writes a ticket, and this reads it back. A ticket counts
-    the current `task.py` subcommand matches and exactly one fresh context key
+    only when it is fresh, was written for this repo, and matches the `task.py`
-    matches, which avoids cross-window pointer contamination.
+    subcommand now running — and only when exactly one fresh context key
+    matches. Two concurrent windows therefore both degrade rather than one
+    inheriting the other's pointer.
     """
     repo_root = _find_repo_root_from_cwd()
     if repo_root is None:
         return None
 
-    ticket_dir = _cursor_shell_ticket_dir(repo_root)
-    if not ticket_dir.is_dir():
-        return None
-
     now = time.time()
     candidates: set[str] = set()
+    for ticket_dir in _shell_ticket_dirs(repo_root):
+        if not ticket_dir.is_dir():
+            continue
         for ticket_path in ticket_dir.glob("*.json"):
-        context_key = _matching_cursor_ticket_context_key(ticket_path, repo_root, now)
+            context_key = _matching_ticket_context_key(ticket_path, repo_root, now)
             if context_key:
                 candidates.add(context_key)
 
@@ -435,8 +502,10 @@ def resolve_context_key(
         if env_context_key:
             return env_context_key
 
-    if allow_environment_context and platform_name in (None, "session", "cursor"):
+    # Last in the chain on purpose: a platform that genuinely exports identity
-        return _lookup_cursor_shell_ticket_context_key()
+    # into the shell outranks a ticket, and no platform name gates the lookup.
+    if allow_environment_context:
+        return _lookup_shell_ticket_context_key()
     return None
 
 

.trellis/scripts/common/config.py

@@ -281,6 +281,24 @@ def get_codex_dispatch_mode(repo_root: Path | None = None) -> str:
     return "inline"
 
 
+def get_default_workflow(repo_root: Path | None = None) -> str | None:
+    """Return the team-shared default workflow id from config.yaml.
+
+    Reads the top-level ``default_workflow`` key — a slug naming a variant in
+    ``.trellis/workflows/<id>.md``. Returns None when unset or blank. This is
+    the git-tracked, team-shared default; a per-developer override lives in the
+    gitignored ``.developer`` file (``workflow=<id>``, see
+    ``paths.get_developer_workflow``) and outranks it. Fail-open: a missing or
+    non-string value simply means "no team default" — no warning (this is read
+    on every turn by hooks and must not add per-turn noise).
+    """
+    config = _load_config(repo_root)
+    raw = config.get("default_workflow")
+    if not isinstance(raw, str):
+        return None
+    return raw.strip() or None
+
+
 DEFAULT_CONTEXT_INJECTION_MAX_FILE_BYTES = 32768
 DEFAULT_CONTEXT_INJECTION_MAX_ARTIFACT_BYTES = 65536
 DEFAULT_CONTEXT_INJECTION_MAX_TOTAL_BYTES = 131072

.trellis/scripts/common/git_context.py

@@ -27,6 +27,8 @@ from .packages_context import (
     get_context_packages_text,
     get_context_packages_json,
 )
+from .paths import get_repo_root
+from .spec_match import match_specs_for_file
 from .trellis_config import read_trellis_config
 from .workflow_phase import (
     filter_platform,
@@ -57,9 +59,9 @@ def main() -> None:
     parser.add_argument(
         "--mode",
         "-m",
-        choices=["default", "record", "packages", "phase"],
+        choices=["default", "record", "packages", "phase", "spec"],
         default="default",
-        help="Output mode: default (full context), record (for record-session), packages (package info only), phase (workflow step extraction)",
+        help="Output mode: default (full context), record (for record-session), packages (package info only), phase (workflow step extraction), spec (specs governing a file)",
     )
     parser.add_argument(
         "--step",
@@ -69,6 +71,10 @@ def main() -> None:
         "--platform",
         help="Platform name for --mode phase, e.g. cursor, claude-code. Filters platform-tagged blocks.",
     )
+    parser.add_argument(
+        "--file",
+        help="File path (absolute or repo-relative) for --mode spec. Lists spec files whose frontmatter paths match it.",
+    )
 
     args = parser.parse_args()
 
@@ -95,6 +101,32 @@ def main() -> None:
             )
             content = filter_platform(content, effective)
         print(content, end="")
+    elif args.mode == "spec":
+        if not args.file:
+            parser.error("--file is required with --mode spec")
+        matches = match_specs_for_file(get_repo_root(), args.file)
+        if args.json:
+            print(
+                json.dumps(
+                    {
+                        "file": args.file,
+                        "matches": [
+                            {
+                                "path": match.rel_path,
+                                "description": match.description,
+                            }
+                            for match in matches
+                        ],
+                    },
+                    indent=2,
+                    ensure_ascii=False,
+                )
+            )
+        elif matches:
+            for match in matches:
+                print(f"{match.rel_path} — {match.description or '(no description)'}")
+        else:
+            print(f"No spec files declare paths matching {args.file}.")
     else:
         if args.json:
             output_json()

.trellis/scripts/common/paths.py

@@ -94,6 +94,34 @@ def get_developer(repo_root: Path | None = None) -> str | None:
     return None
 
 
+def get_developer_workflow(repo_root: Path | None = None) -> str | None:
+    """Get the personal workflow override from the .developer file.
+
+    Reads an optional ``workflow=<id>`` line from the gitignored ``.developer``
+    file — the per-developer, git-excluded override that outranks the
+    team-shared ``default_workflow`` in config.yaml. Returns None when the file
+    or the line is absent/blank. Never raises. Additive to ``get_developer``:
+    the ``name=`` reader ignores this line and vice versa.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    dev_file = repo_root / DIR_WORKFLOW / FILE_DEVELOPER
+
+    if not dev_file.is_file():
+        return None
+
+    try:
+        content = dev_file.read_text(encoding="utf-8")
+        for line in content.splitlines():
+            if line.startswith("workflow="):
+                return line.split("=", 1)[1].strip() or None
+    except (OSError, IOError):
+        pass
+
+    return None
+
+
 def check_developer(repo_root: Path | None = None) -> bool:
     """Check if developer is initialized.
 

.trellis/scripts/common/session_context.py

@@ -9,6 +9,7 @@ Provides:
     get_context_text_record   - Text for record mode
     output_json               - Print JSON
     output_text               - Print text
+    get_update_hint           - Once-per-session "update available" line
 """
 
 from __future__ import annotations
@@ -417,7 +418,15 @@ def _compare_versions(left: str, right: str) -> int | None:
     return _compare_prerelease(left_prerelease, right_prerelease)
 
 
-def _update_marker_path(repo_root: Path) -> Path:
+def _update_marker_path(repo_root: Path, context_key: str | None = None) -> Path:
+    """Path of the once-per-session marker that throttles the update check.
+
+    `context_key` lets a caller that already resolved session identity pass it
+    in — the SessionStart hook reads the session id from hook stdin, which is
+    more reliable than this function's environment-only fallback chain. Shell
+    entry points leave it None and keep the previous behavior.
+    """
+    if not context_key:
         context_key = resolve_context_key()
     if not context_key:
         terminal_key = os.environ.get("TERM_SESSION_ID", "").strip()
@@ -433,8 +442,11 @@ def _update_marker_path(repo_root: Path) -> Path:
     )
 
 
-def _mark_update_check_attempted(repo_root: Path) -> bool:
+def _mark_update_check_attempted(
-    marker_path = _update_marker_path(repo_root)
+    repo_root: Path,
+    context_key: str | None = None,
+) -> bool:
+    marker_path = _update_marker_path(repo_root, context_key)
     if marker_path.exists():
         return False
     try:
@@ -445,8 +457,14 @@ def _mark_update_check_attempted(repo_root: Path) -> bool:
     return True
 
 
-def _get_update_hint(repo_root: Path) -> str | None:
+def get_update_hint(repo_root: Path, context_key: str | None = None) -> str | None:
-    marker_path = _update_marker_path(repo_root)
+    """Return the "update available" line for this session, at most once.
+
+    Public because the SessionStart hook imports it: the text-mode CLI path
+    (`get_context.py`) used to be the only caller, so hook-driven platforms —
+    Claude Code included — never saw the reminder at all.
+    """
+    marker_path = _update_marker_path(repo_root, context_key)
     if marker_path.exists():
         return None
 
@@ -458,7 +476,7 @@ def _get_update_hint(repo_root: Path) -> str | None:
     if not latest_version:
         return None
 
-    _mark_update_check_attempted(repo_root)
+    _mark_update_check_attempted(repo_root, context_key)
     comparison = _compare_versions(current_version, latest_version)
     if comparison is None or comparison >= 0:
         return None
@@ -867,7 +885,7 @@ def output_text(repo_root: Path | None = None) -> None:
     """
     if repo_root is None:
         repo_root = get_repo_root()
-    update_hint = _get_update_hint(repo_root)
+    update_hint = get_update_hint(repo_root)
     if update_hint:
         print(update_hint)
         print("")

.trellis/scripts/common/spec_inject.py

@@ -0,0 +1,439 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Decision logic for path-scoped spec injection (ticket-refresh model).
+
+Pure logic only: the per-spec decision engine, block rendering and budgeted
+payload assembly. Importing this module has no side effects; every piece of IO
+orchestration (stdin, config, identity, state files, locking, GC) lives in the
+platform hook that calls it. Unit tests import this module directly.
+
+Clock
+    The periodic refresh window uses epoch seconds. Context resets are
+    explicit lifecycle events: the hook records an opaque reset identifier,
+    and a mismatch with the last emission re-teaches the spec in full.
+
+Budget
+    All caps are in characters, because the platform's ``additionalContext``
+    ceiling is 10,000 *characters* (counting bytes made CJK specs pay 3x).
+    Truncation slices code points, which can never split a multi-byte
+    sequence. The per-event cap is enforced on the assembled payload string —
+    wrappers, ``\\n\\n`` separators, index block and tickets all counted — so
+    nothing is ever appended unchecked.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import sys
+from typing import Any, Sequence
+
+from .spec_match import SpecMatch
+
+# Bound on the size of a spec file we are willing to read and hash. A spec
+# larger than this degrades to an index line (warned) — an inlined body that
+# big could never fit the budget anyway, and the read+hash would be unbounded.
+MAX_SPEC_SOURCE_BYTES = 10 * 1024 * 1024
+
+# Upper bound on the room reserved for named index lines while FULL blocks are
+# still being packed. Beyond it the reserve falls back to the summary line
+# alone: a big fan-out must not starve the specs that can still be taught.
+INDEX_RESERVE_MAX_CHARS = 900
+
+# State record schema version. Records with any other version are ignored
+# (safe direction: an ignored record re-injects rather than stays silent).
+STATE_VERSION = 2
+
+def _warn(message: str) -> None:
+    print(f"[WARN] spec_inject: {message}", file=sys.stderr)
+
+
+# =============================================================================
+# Clock
+# =============================================================================
+
+
+def within_window(
+    clock: dict[str, Any],
+    last: dict[str, Any],
+    win_seconds: int,
+) -> bool:
+    """True when the last emission is still inside the refresh window (→ stay
+    silent).
+
+    A window of ``0`` means never refresh (infinite window → always True).
+    Missing timestamps or a negative delta are past-window (False → refresh),
+    the safe side of the misfire asymmetry.
+    """
+    cur_ts = clock.get("ts")
+    last_ts = last.get("ts")
+    if isinstance(cur_ts, (int, float)) and isinstance(last_ts, (int, float)):
+        if win_seconds == 0:
+            return True
+        delta = cur_ts - last_ts
+        return 0 <= delta < win_seconds
+
+    return False
+
+
+def decide(
+    stateless: bool,
+    last: dict[str, Any] | None,
+    sha256_hex: str,
+    clock: dict[str, Any],
+    win_seconds: int,
+) -> str:
+    """Return one of ``"full"`` | ``"ticket"`` | ``"silent"`` for a spec.
+
+    Order is contractual: statelessness first (bounded cost, no state to
+    consult), then first sight, content change, context reset, the refresh
+    window, and finally completeness. A ticket says "you were shown this spec",
+    which is a lie when the recorded FULL was truncated, so an incomplete
+    record is re-taught in full instead.
+    """
+    if stateless:
+        return "ticket"
+    if last is None:
+        return "full"
+    if last.get("sha256") != sha256_hex:
+        return "full"
+    if clock.get("reset") != last.get("reset"):
+        return "full"
+
+    if within_window(clock, last, win_seconds):
+        return "silent"
+
+    # "complete" is optional and absent means a whole body was shown.
+    if last.get("complete") is False:
+        return "full"
+    return "ticket"
+
+
+# =============================================================================
+# Rendering
+# =============================================================================
+
+
+def truncate_chars(text: str, cap: int) -> str:
+    """Slice ``text`` to at most ``cap`` code points. ``cap <= 0`` = no limit."""
+    if cap <= 0 or len(text) <= cap:
+        return text
+    return text[:cap]
+
+
+def truncation_notice(rel_path: str, cap: int) -> str:
+    return (
+        f"\n[Trellis: truncated at {cap} characters — "
+        f"read {rel_path} for the full content]"
+    )
+
+
+def render_full(edited_rel: str, spec_rel: str, sha12: str, body: str) -> str:
+    return (
+        f'<spec-context file="{edited_rel}" spec="{spec_rel}" sha256="{sha12}">\n'
+        f"{body}\n"
+        f"</spec-context>"
+    )
+
+
+def render_ticket(
+    edited_rel: str,
+    spec_rel: str,
+    sha12: str,
+    stateless: bool,
+) -> str:
+    """Render a ticket block.
+
+    ``stateless=True`` covers both the no-identity and circuit-breaker paths:
+    there is no record of a prior emission, so the wording must not claim one.
+    """
+    if stateless:
+        body = (
+            "This spec governs the file you just touched. If you have not read it in\n"
+            f"this session, Read {spec_rel} before continuing."
+        )
+    else:
+        body = (
+            "You were shown this spec earlier in this session and its content is unchanged.\n"
+            "It still governs edits to matching files. If you no longer remember it, Read\n"
+            f"{spec_rel} before continuing."
+        )
+    return (
+        f'<spec-ticket file="{edited_rel}" spec="{spec_rel}" sha256="{sha12}">\n'
+        f"{body}\n"
+        f"</spec-ticket>"
+    )
+
+
+def _index_block(lines: Sequence[str]) -> str:
+    return "<spec-index>\n" + "\n".join(lines) + "\n</spec-index>"
+
+
+# =============================================================================
+# State records
+# =============================================================================
+
+
+def make_record(
+    rel_path: str,
+    sha256_hex: str,
+    mode: str,
+    clock: dict[str, Any],
+    complete: bool = True,
+) -> dict[str, Any]:
+    """Build a state record. ``complete=False`` marks a FULL whose body was
+    truncated below the whole spec — an absent flag means whole."""
+    record: dict[str, Any] = {
+        "v": STATE_VERSION,
+        "spec": rel_path,
+        "sha256": sha256_hex,
+        "mode": mode,
+        "ts": clock.get("ts"),
+    }
+    if isinstance(clock.get("reset"), str):
+        record["reset"] = clock["reset"]
+    if not complete:
+        record["complete"] = False
+    return record
+
+
+# =============================================================================
+# Payload assembly
+# =============================================================================
+
+
+def _derive_fitting_full(
+    edited_rel: str,
+    spec_rel: str,
+    sha12: str,
+    text: str,
+    max_spec_chars: int,
+    fits,
+) -> tuple[str, bool] | None:
+    """Largest truncated FULL block that fits the remaining total budget.
+
+    Binary search over the body cap: the rendered block's length is monotone
+    non-decreasing in the cap, so the largest cap whose block still ``fits``
+    is found in ~log2(len(text)) renders (this also absorbs the digit-length
+    wobble of the notice text, which a closed-form estimate cannot).
+
+    The search ceiling is ``max_spec_chars`` when set and the whole body when
+    it is ``0`` (unlimited) — with a ceiling of 1, as an unguarded
+    ``max(1, 0)`` would give, nothing but a one-character spec could ever be
+    derived. Returns ``(block, complete)`` — ``complete`` is True only when
+    the winning cap covered the whole body — or None when no non-empty prefix
+    fits (the caller degrades to an index line).
+    """
+    def candidate_for(cap: int) -> str:
+        body = truncate_chars(text, cap)
+        if len(body) < len(text):
+            body += truncation_notice(spec_rel, cap)
+        return render_full(edited_rel, spec_rel, sha12, body)
+
+    ceiling = len(text) if max_spec_chars <= 0 else min(max_spec_chars, len(text))
+    lo, hi = 1, max(1, ceiling)
+    best: tuple[str, bool] | None = None
+    while lo <= hi:
+        mid = (lo + hi) // 2
+        candidate = candidate_for(mid)
+        if fits(candidate):
+            best = (candidate, mid >= len(text))
+            lo = mid + 1
+        else:
+            hi = mid - 1
+    return best
+
+
+def _index_line(match: SpecMatch) -> str:
+    return f"- {match.rel_path} — {match.description or 'no description'}"
+
+
+def assemble_payload(
+    edited_rel: str,
+    matches: Sequence[SpecMatch],
+    stateless: bool,
+    state_records: dict[str, dict[str, Any]],
+    clock: dict[str, Any],
+    max_spec_chars: int,
+    max_total_chars: int,
+    win_seconds: int,
+    match_files: dict[str, str] | None = None,
+) -> tuple[str, list[dict[str, Any]]]:
+    """Assemble the additionalContext payload from the matched specs.
+
+    Returns ``(payload, records)`` where ``records`` are the state lines to
+    append for the emissions that actually made it into the payload (silent
+    hits and budget-dropped emissions record nothing — they stay eligible).
+
+    Every candidate block is measured against the *assembled* payload string
+    (``"\\n\\n".join(...)``), so the per-event character ceiling holds for the
+    exact string that is emitted.
+
+    ``match_files`` maps a governing spec to the first matching file in a
+    multi-file tool call. Single-file callers omit it and retain the original
+    ``edited_rel`` behavior.
+    """
+    blocks: list[str] = []
+
+    def file_for(match: SpecMatch) -> str:
+        return (match_files or {}).get(match.rel_path, edited_rel)
+
+    def fits(candidate: str, reserve: int = 0) -> bool:
+        """Does ``candidate`` fit the per-event ceiling, keeping ``reserve``
+        characters free for what still has to be appended after it?"""
+        if max_total_chars <= 0:
+            return True
+        return len("\n\n".join([*blocks, candidate])) + reserve <= max_total_chars
+
+    # Reserve while candidates are still pending: the index lines those
+    # candidates would actually need (true strings, not estimates) plus the
+    # summary line — so a derived-cap FULL cannot eat the budget and starve
+    # the specs behind it (measured: 10-spec fan-out at max_total_chars 3000
+    # emitted one 3000-char FULL and dropped the other nine silently). The
+    # named part is only guaranteed within INDEX_RESERVE_MAX_CHARS; beyond
+    # that the reserve falls back to the summary line alone.
+    _all_index_lines = [_index_line(m) for m in matches]
+    _summary_upper = (
+        f"- (+{len(matches)} more governing specs over budget — run "
+        f"python3 ./.trellis/scripts/get_context.py --mode spec "
+        f"--file {edited_rel} to list them)"
+    )
+    _summary_reserve = len("\n\n" + _index_block([_summary_upper]))
+
+    def reserve_for(pending: Sequence[str]) -> int:
+        if not pending:
+            return 0  # Nothing can follow this block — nothing to reserve.
+        named = len("\n\n" + _index_block([*pending, _summary_upper]))
+        if named > INDEX_RESERVE_MAX_CHARS:
+            return _summary_reserve
+        return named
+
+    index_lines: list[str] = []
+    ticket_pending: list[tuple[str, str, str]] = []  # (file, spec, sha256)
+    records: list[dict[str, Any]] = []
+
+    for match_idx, match in enumerate(matches):
+        try:
+            size = match.spec_path.stat().st_size
+        except OSError:
+            size = 0
+        if size > MAX_SPEC_SOURCE_BYTES:
+            # Too big to read+hash, let alone inline: name it and move on.
+            _warn(
+                f"{match.rel_path} is {size} bytes (over "
+                f"{MAX_SPEC_SOURCE_BYTES}) — degraded to an index line"
+            )
+            index_lines.append(_index_line(match))
+            continue
+
+        try:
+            data = match.spec_path.read_bytes()
+        except OSError:
+            _warn(f"cannot read {match.rel_path} — skipped")
+            continue
+
+        sha256_hex = hashlib.sha256(data).hexdigest()
+        sha12 = sha256_hex[:12]
+        last = None if stateless else state_records.get(match.rel_path)
+        decision = decide(stateless, last, sha256_hex, clock, win_seconds)
+
+        if decision == "silent":
+            continue
+
+        if decision == "ticket":
+            # Deferred: tickets are counted against the budget last.
+            ticket_pending.append((file_for(match), match.rel_path, sha256_hex))
+            continue
+
+        pending = [*index_lines, *_all_index_lines[match_idx + 1 :]]
+        reserve = reserve_for(pending)
+        _fits = (lambda c: fits(c, reserve))
+
+        text = data.decode("utf-8", errors="replace")
+        body = truncate_chars(text, max_spec_chars)
+        complete = len(body) >= len(text)
+        if not complete:
+            body += truncation_notice(match.rel_path, max_spec_chars)
+        matching_file = file_for(match)
+        block = render_full(matching_file, match.rel_path, sha12, body)
+        if not _fits(block):
+            # Contract amendment 1: before degrading, truncate FURTHER to the
+            # largest body prefix that fits the remaining total budget
+            # (wrapper + notice counted). Without this, the frozen defaults
+            # made the truncation path unreachable (body cap + notice +
+            # wrapper > total cap) and long specs fell straight to an index
+            # line — the rejected index-only mode by another route.
+            derived = _derive_fitting_full(
+                matching_file,
+                match.rel_path,
+                sha12,
+                text,
+                max_spec_chars,
+                _fits,
+            )
+            if derived is not None:
+                derived_block, derived_complete = derived
+                blocks.append(derived_block)
+                records.append(
+                    make_record(
+                        match.rel_path, sha256_hex, "full", clock, derived_complete
+                    )
+                )
+                continue
+            # No usable prefix fits — degrade to an index line, never drop
+            # silently. Not recorded: stays eligible for a later event.
+            index_lines.append(_index_line(match))
+            continue
+        blocks.append(block)
+        records.append(
+            make_record(match.rel_path, sha256_hex, "full", clock, complete)
+        )
+
+    if index_lines:
+        # The index block is budget-bounded too: lines that do not fit collapse
+        # into one summary line (count + how to list them via pull mode) so the
+        # ceiling is honored without silently dropping a governing spec.
+        chosen: list[str] = []
+        dropped = 0
+        for line in index_lines:
+            if fits(_index_block([*chosen, line])):
+                chosen.append(line)
+            else:
+                dropped += 1
+        if dropped:
+            # Contract amendment 3: the summary must actually be reachable.
+            # Greedy packing rarely leaves a summary-sized gap, so pop chosen
+            # lines (re-counting them as dropped) until the summary fits —
+            # only an absurdly small total budget can drop it entirely.
+            while True:
+                noun = "spec" if dropped == 1 else "specs"
+                summary = (
+                    f"- (+{dropped} more governing {noun} over budget — run "
+                    f"python3 ./.trellis/scripts/get_context.py --mode spec "
+                    f"--file {edited_rel} to list them)"
+                )
+                if fits(_index_block([*chosen, summary])):
+                    chosen.append(summary)
+                    break
+                if not chosen:
+                    _warn(
+                        f"spec index summary for {edited_rel} dropped — "
+                        f"per-event budget exhausted"
+                    )
+                    break
+                chosen.pop()
+                dropped += 1
+        if chosen:
+            blocks.append(_index_block(chosen))
+
+    for matching_file, spec_rel, sha256_hex in ticket_pending:
+        ticket = render_ticket(
+            matching_file, spec_rel, sha256_hex[:12], stateless
+        )
+        if not fits(ticket):
+            _warn(f"ticket for {spec_rel} dropped — per-event budget exhausted")
+            continue
+        blocks.append(ticket)
+        records.append(make_record(spec_rel, sha256_hex, "ticket", clock))
+
+    return "\n\n".join(blocks), records

.trellis/scripts/common/spec_match.py

@@ -0,0 +1,395 @@
+#!/usr/bin/env python3
+"""
+Path-scoped spec matching for on-demand spec injection.
+
+Spec files under `.trellis/spec/**/*.md` MAY start with a YAML-like
+frontmatter block declaring which repo paths they govern:
+
+    ---
+    name: commands-workflow
+    description: workflow command conventions
+    paths:
+      - packages/cli/src/commands/workflow.ts
+      - packages/cli/src/utils/workflow-resolver.ts
+    ---
+
+The parser is hand-rolled (house pattern, modeled on
+``trellis_config.parse_simple_yaml`` — no YAML dependency) and reads only a
+bounded head of each file (16 KiB / 200 lines, whichever ends first). Only
+files whose first line is exactly ``---`` are considered. ``name:`` /
+``description:`` single-line strings are recognized (description is reused in
+index lines). ``paths:`` accepts both a block list (``- <glob>`` items) and a
+flow sequence (``paths: [a, b]``).
+
+The parser is deliberately tolerant — a spec is prose that happens to carry a
+routing hint, not a config file. Unknown keys, unrecognized line shapes and
+stray ``- item`` lines are ignored; block scalars (``key: >`` / ``key: |``)
+consume their more-indented continuation lines, so a SKILL.md-style
+``description: >`` paragraph does not disqualify the file. An opening ``---``
+with no recognized key before the closing marker is not frontmatter at all
+(a Markdown horizontal rule opening the prose) and is ignored silently. Two
+things are errors, and both warn + skip the whole file rather than route on a
+half-read block: a malformed ``paths:`` (a scalar where a list belongs — that
+key is the one thing the rest of the pipeline depends on), and a frontmatter
+block that is still open when the head bound is reached.
+
+Glob grammar (repo-relative, POSIX separators):
+
+- ``*``  matches within a single path segment (never crosses ``/``)
+- ``?``  matches exactly one character within a segment
+- ``**`` as a whole segment matches zero or more segments
+- a trailing ``/`` is sugar for ``/**``
+- ``**`` embedded in a segment with other characters degrades to ``*``
+
+Validation rejects only what is unsafe or meaningless: empty globs, a leading
+``/`` (globs are repo-relative), ``..`` segments, backslashes (POSIX
+separators only) and control characters. Everything else is legal — real
+repositories carry ``@scope`` packages, ``[slug]`` routes, ``(marketing)``
+groups and non-ASCII directories, and the translation escapes literals
+character by character. An invalid glob is skipped with a stderr warning; the
+rest of the file's globs still apply.
+
+Translation examples (glob → matches / non-matches):
+
+    packages/cli/src/commands/update.ts
+        matches only that exact file
+    packages/cli/src/commands/*.ts
+        matches packages/cli/src/commands/update.ts
+        not     packages/cli/src/commands/channel/spawn.ts
+    packages/cli/src/templates/**
+        matches packages/cli/src/templates/trellis/index.ts (any depth)
+        not     packages/cli/src/templates (the directory itself)
+    packages/**/index.ts
+        matches packages/index.ts and packages/cli/src/index.ts
+    src/util?.py
+        matches src/utils.py, not src/util.py or src/utilXY.py
+    packages/cli/
+        same as packages/cli/**
+
+Provides:
+    SpecMatch               - frozen match record (spec_path, rel_path, description)
+    match_specs_for_file    - map an edited file to the specs that govern it
+    normalize_repo_relative - the canonical repo-relative path normalization
+    parse_spec_frontmatter  - parse the optional frontmatter head block
+    glob_to_regex           - deterministic glob → compiled regex translation
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import unicodedata
+from dataclasses import dataclass
+from pathlib import Path
+
+from .paths import DIR_SPEC, DIR_WORKFLOW
+from .trellis_config import _strip_inline_comment, _unquote
+
+# Bounded head-read limits for frontmatter scanning (design contract).
+HEAD_MAX_BYTES = 16384
+HEAD_MAX_LINES = 200
+
+# Recognized frontmatter keys. An opening `---` block that declares none of
+# them is prose under a horizontal rule, not frontmatter.
+_KNOWN_KEYS = ("paths", "name", "description")
+
+_GLOB_CONTROL_RE = re.compile(r"[\x00-\x1f\x7f]")
+_KEY_RE = re.compile(r"^([A-Za-z_][A-Za-z0-9_-]*):(.*)$")
+# YAML block-scalar introducers; the value lives in the indented lines below.
+_BLOCK_SCALARS = ("|", ">", "|-", ">-", "|+", ">+")
+
+# macOS and Windows filesystems are case-insensitive: the very same file can
+# be handed to us in a case the glob author never wrote. Match case-insensitively
+# there — over-injecting a spec is the safe side of the asymmetry.
+_CASE_INSENSITIVE_FS = sys.platform == "darwin" or sys.platform.startswith("win")
+_GLOB_FLAGS = re.IGNORECASE if _CASE_INSENSITIVE_FS else 0
+
+
+@dataclass(frozen=True)
+class SpecFrontmatter:
+    """Parsed frontmatter head. ``paths`` is None when the key is absent."""
+
+    paths: tuple[str, ...] | None
+    name: str | None
+    description: str | None
+
+
+@dataclass(frozen=True)
+class SpecMatch:
+    spec_path: Path
+    """Absolute path to the spec file."""
+    rel_path: str
+    """Repo-relative POSIX path, for display."""
+    description: str | None
+    """Frontmatter ``description:`` value, if declared."""
+
+
+def _warn(message: str) -> None:
+    print(f"[WARN] spec_match: {message}", file=sys.stderr)
+
+
+def _parse_flow_sequence(value: str) -> list[str]:
+    """Split a YAML flow sequence body (``[a, b]``) into unquoted items.
+
+    Commas separate; each item is trimmed and unquoted. Empty items (a
+    trailing comma, ``[]``) collapse away.
+    """
+    inner = value[1:-1]
+    items = (_unquote(part.strip()).strip() for part in inner.split(","))
+    return [item for item in items if item]
+
+
+def _read_head(path: Path) -> str:
+    """Read at most HEAD_MAX_BYTES from the file, decoded as UTF-8."""
+    with open(path, "rb") as f:
+        data = f.read(HEAD_MAX_BYTES)
+    return data.decode("utf-8", errors="replace")
+
+
+def parse_spec_frontmatter(head_text: str) -> SpecFrontmatter | None:
+    """Parse the optional frontmatter block from a spec file's head.
+
+    Returns None when the file has no frontmatter: either the first line is not
+    ``---``, or the block declares no recognized key before its closing marker
+    (a horizontal rule opening a prose file — silent, not an error).
+
+    Raises ValueError on a malformed ``paths:`` key (a scalar where a list
+    belongs) and on a block that is still open when the head bound
+    (HEAD_MAX_LINES / HEAD_MAX_BYTES) is reached — routing on a half-read
+    frontmatter would be worse than skipping the file loudly. Every other line
+    shape is tolerated and ignored.
+    """
+    lines = head_text.splitlines()[:HEAD_MAX_LINES]
+    if not lines:
+        return None
+    first = lines[0].lstrip("\ufeff")  # tolerate a UTF-8 BOM
+    if first != "---":
+        return None
+
+    paths: list[str] | None = None
+    name: str | None = None
+    description: str | None = None
+    pending_key: str | None = None
+    block_indent: int | None = None
+    saw_known_key = False
+    closed = False
+
+    for line in lines[1:]:
+        stripped = line.strip()
+        indent = len(line) - len(line.lstrip())
+
+        if block_indent is not None:
+            # Inside a block scalar: everything more indented (and blank lines)
+            # is its value. A dedent ends the block; that line still counts.
+            if not stripped or indent > block_indent:
+                continue
+            block_indent = None
+
+        if stripped == "---":
+            closed = True
+            break
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        if stripped == "-" or stripped.startswith("- "):
+            if pending_key == "paths" and paths is not None:
+                item = _unquote(_strip_inline_comment(stripped[1:].strip()).strip())
+                paths.append(item)
+            # List items outside `paths:` are tolerated and ignored.
+            continue
+
+        key_match = _KEY_RE.match(stripped)
+        if key_match is None:
+            continue  # Unrecognized line shape — tolerated and ignored.
+
+        key = key_match.group(1)
+        saw_known_key = saw_known_key or key in _KNOWN_KEYS
+        raw_value = key_match.group(2).strip()
+        if raw_value in _BLOCK_SCALARS:
+            if key == "paths":
+                raise ValueError("'paths' must be a list of globs")
+            pending_key = None
+            block_indent = indent
+            continue
+
+        value = _unquote(_strip_inline_comment(raw_value).strip())
+        if value:
+            pending_key = None
+            if key == "paths":
+                if not (value.startswith("[") and value.endswith("]")):
+                    raise ValueError("'paths' must be a list of globs")
+                paths = _parse_flow_sequence(value)
+            elif key == "name":
+                name = value
+            elif key == "description":
+                description = value
+            # Unknown scalar keys are tolerated and ignored.
+        else:
+            pending_key = key
+            if key == "paths":
+                paths = []
+
+    if not saw_known_key:
+        # An opening `---` with no recognized key is a horizontal rule, not a
+        # frontmatter block. Silent by design: prose files are not malformed.
+        return None
+    if not closed:
+        raise ValueError(
+            f"frontmatter block never closed within the head bound "
+            f"({HEAD_MAX_BYTES} bytes / {HEAD_MAX_LINES} lines)"
+        )
+
+    return SpecFrontmatter(
+        paths=tuple(paths) if paths is not None else None,
+        name=name,
+        description=description,
+    )
+
+
+def validate_glob(glob: str) -> str | None:
+    """Return an error message for an invalid glob, or None when valid.
+
+    Deny-list, not allow-list: only what is unsafe or meaningless is rejected
+    (see module docstring). Everything else — ``@scope``, ``[slug]``,
+    ``(marketing)``, non-ASCII directory names — is a legal path in a real
+    repository and translates fine.
+    """
+    if not glob:
+        return "empty glob"
+    if glob.startswith("/"):
+        return "absolute paths are not allowed (globs are repo-relative)"
+    if ".." in glob.split("/"):
+        return "'..' segments are not allowed"
+    if "\\" in glob:
+        return "backslashes are not allowed (globs use POSIX '/' separators)"
+    if _GLOB_CONTROL_RE.search(glob):
+        return "contains control characters"
+    return None
+
+
+def glob_to_regex(glob: str) -> re.Pattern[str]:
+    """Translate a validated glob to a compiled full-match regex.
+
+    Deterministic, segment-based translation (see module docstring for the
+    grammar and examples): ``**`` as a whole segment spans zero or more
+    segments; ``*`` becomes ``[^/]*``; ``?`` becomes ``[^/]``; everything
+    else is escaped literally. A trailing ``/`` is expanded to ``/**`` first.
+    On case-insensitive filesystems (macOS, Windows) the pattern compiles with
+    ``re.IGNORECASE`` — see ``_CASE_INSENSITIVE_FS``.
+    """
+    if glob.endswith("/"):
+        glob += "**"
+    segments = glob.split("/")
+    parts: list[str] = []
+    for i, seg in enumerate(segments):
+        is_last = i == len(segments) - 1
+        if seg == "**":
+            # Last: consume the rest of the path (at least the separator
+            # boundary is already emitted by the previous segment). Not last:
+            # zero or more whole segments including their separators.
+            parts.append(".*" if is_last else r"(?:[^/]+/)*")
+            continue
+        piece = "".join(
+            "[^/]*" if ch == "*" else "[^/]" if ch == "?" else re.escape(ch)
+            for ch in seg
+        )
+        parts.append(piece if is_last else piece + "/")
+    return re.compile("^" + "".join(parts) + "$", _GLOB_FLAGS)
+
+
+def normalize_repo_relative(repo_root: Path, file_path: str | Path) -> str | None:
+    """Canonical repo-relative POSIX path — the one normalization in the
+    pipeline, used both for matching and for display.
+
+    Root and file are fully resolved (``strict=False``, so a file that no
+    longer exists still normalizes): symlinked repo roots, macOS's
+    ``/tmp`` → ``/private/tmp`` and ``..`` segments cannot make one file look
+    like two different paths. The result is NFC-normalized (macOS hands out
+    NFD filenames). Relative inputs are taken as repo-relative. Returns None
+    when the file resolves outside the repo.
+    """
+    try:
+        root = Path(repo_root).resolve(strict=False)
+        candidate = Path(file_path)
+        if not candidate.is_absolute():
+            text = str(file_path).replace("\\", "/")
+            while text.startswith("./"):
+                text = text[2:]
+            if not text:
+                return None
+            candidate = root / text
+        rel = candidate.resolve(strict=False).relative_to(root).as_posix()
+    except (OSError, ValueError):
+        return None
+    return unicodedata.normalize("NFC", rel)
+
+
+def match_specs_for_file(repo_root: Path, file_path: str | Path) -> list[SpecMatch]:
+    """Return specs whose frontmatter ``paths:`` globs match file_path.
+
+    ``file_path`` may be absolute or repo-relative. More specific matching
+    globs are returned first; ``rel_path`` is the deterministic tie-break.
+    Scans ``.trellis/spec/**/*.md`` with bounded head-reads only. Never raises;
+    unreadable or malformed spec files are skipped with a stderr warning.
+    """
+    try:
+        repo_root = Path(repo_root).resolve()
+        spec_dir = repo_root / DIR_WORKFLOW / DIR_SPEC
+        if not spec_dir.is_dir():
+            return []
+        rel = normalize_repo_relative(repo_root, file_path)
+        if rel is None:
+            return []
+
+        matches: list[SpecMatch] = []
+        specificity: dict[str, tuple[int, int, int, int]] = {}
+        for spec_file in spec_dir.rglob("*.md"):
+            spec_rel = spec_file.relative_to(repo_root).as_posix()
+            try:
+                head = _read_head(spec_file)
+            except OSError as exc:
+                _warn(f"cannot read {spec_rel}: {exc}")
+                continue
+            try:
+                frontmatter = parse_spec_frontmatter(head)
+            except ValueError as exc:
+                _warn(f"malformed frontmatter in {spec_rel}: {exc}")
+                continue
+            if frontmatter is None or not frontmatter.paths:
+                continue
+            for glob in frontmatter.paths:
+                error = validate_glob(glob)
+                if error is not None:
+                    _warn(f"invalid glob {glob!r} in {spec_rel}: {error}")
+                    continue
+                if glob_to_regex(glob).match(rel):
+                    scored_glob = glob + "**" if glob.endswith("/") else glob
+                    wildcard_count = scored_glob.count("*") + scored_glob.count("?")
+                    segments = scored_glob.split("/")
+                    literal_segments = sum(
+                        "*" not in segment and "?" not in segment
+                        for segment in segments
+                    )
+                    specificity[spec_rel] = (
+                        0 if wildcard_count == 0 else 1,
+                        -literal_segments,
+                        wildcard_count,
+                        -(len(scored_glob) - wildcard_count),
+                    )
+                    matches.append(
+                        SpecMatch(
+                            spec_path=spec_file,
+                            rel_path=spec_rel,
+                            description=frontmatter.description,
+                        )
+                    )
+                    break
+
+        # Payload assembly spends its budget in this order. Exact and narrowly
+        # scoped matches must therefore outrank broad tree globs; alphabetic
+        # order is only a deterministic tie-break.
+        matches.sort(key=lambda m: (*specificity[m.rel_path], m.rel_path))
+        return matches
+    except Exception as exc:  # Never raise — callers are hooks/context tools.
+        _warn(f"spec scan failed: {exc}")
+        return []

.trellis/scripts/common/task_context.py

@@ -25,7 +25,7 @@ from .config import get_context_injection_limits
 from .git import branch_exists_locally
 from .io import read_json
 from .log import Colors, colored
-from .paths import FILE_TASK_JSON, get_repo_root
+from .paths import DIR_ARCHIVE, DIR_TASKS, DIR_WORKFLOW, FILE_TASK_JSON, get_repo_root
 from .task_utils import resolve_task_dir
 
 # Extensions that look like code rather than spec/research docs. Entries with
@@ -170,6 +170,59 @@ def _is_exempt_from_code_file_warning(file_path: str, task_rel: str) -> bool:
     return False
 
 
+def _resolve_context_entry_path(
+    file_path: str, repo_root: Path, task_dir: Path | None
+) -> Path | None:
+    """Resolve a JSONL entry, binding archived self-references to the archive copy.
+
+    Exact historical self-references are remapped only for archived tasks.
+    ``None`` means the remapped path traversed or resolved outside that archive.
+    """
+    repo_path = repo_root / file_path
+    if task_dir is None:
+        return repo_path
+
+    try:
+        task_parts = task_dir.resolve().relative_to(repo_root.resolve()).parts
+    except ValueError:
+        return repo_path
+
+    archive_prefix = (DIR_WORKFLOW, DIR_TASKS, DIR_ARCHIVE)
+    if len(task_parts) != 5 or task_parts[:3] != archive_prefix:
+        return repo_path
+
+    year_month = task_parts[3]
+    if (
+        len(year_month) != 7
+        or year_month[4] != "-"
+        or not year_month[:4].isdigit()
+        or not year_month[5:].isdigit()
+    ):
+        return repo_path
+
+    historical_root = f"{DIR_WORKFLOW}/{DIR_TASKS}/{task_dir.name}"
+    posix_path = file_path.replace("\\", "/")
+    if posix_path == historical_root:
+        relative_parts: tuple[str, ...] = ()
+    elif posix_path.startswith(f"{historical_root}/"):
+        relative_path = posix_path[len(historical_root) + 1 :]
+        if relative_path.endswith("/"):
+            relative_path = relative_path[:-1]
+        relative_parts = tuple(relative_path.split("/")) if relative_path else ()
+        if any(part in ("", ".", "..") for part in relative_parts):
+            return None
+    else:
+        return repo_path
+
+    try:
+        archive_root = task_dir.resolve()
+        resolved_path = task_dir.joinpath(*relative_parts).resolve()
+        resolved_path.relative_to(archive_root)
+    except (OSError, RuntimeError, ValueError):
+        return None
+    return resolved_path
+
+
 def _validate_jsonl(jsonl_file: Path, repo_root: Path, task_dir: Path | None = None) -> int:
     """Validate a single JSONL file.
 
@@ -220,14 +273,14 @@ def _validate_jsonl(jsonl_file: Path, repo_root: Path, task_dir: Path | None = N
             continue
 
         real_entries += 1
-        full_path = repo_root / file_path
+        full_path = _resolve_context_entry_path(file_path, repo_root, task_dir)
         if entry_type == "directory":
-            if not full_path.is_dir():
+            if full_path is None or not full_path.is_dir():
                 print(f"  {colored(f'{file_name}:{line_num}: Directory not found: {file_path}', Colors.RED)}")
                 errors += 1
             continue
 
-        if not full_path.is_file():
+        if full_path is None or not full_path.is_file():
             print(f"  {colored(f'{file_name}:{line_num}: File not found: {file_path}', Colors.RED)}")
             errors += 1
             continue

.trellis/scripts/common/task_store.py

@@ -56,6 +56,7 @@ from .task_utils import (
     resolve_task_dir,
     run_task_hooks,
 )
+from .workflow_selection import DIR_WORKFLOWS, WORKFLOW_ID_RE
 
 
 # =============================================================================
@@ -254,6 +255,31 @@ def cmd_create(args: argparse.Namespace) -> int:
         # Inferred: default_package → None (no task.json yet for create)
         package = resolve_package(repo_root=repo_root)
 
+    # Validate --workflow (CLI source: fail-fast on invalid id; a missing
+    # library file only warns — it may be saved later via `trellis workflow --save`)
+    workflow_id: str | None = getattr(args, "workflow", None)
+    if workflow_id:
+        if not WORKFLOW_ID_RE.match(workflow_id):
+            print(
+                colored(
+                    f"Error: invalid workflow id '{workflow_id}' (allowed: letters, digits, '-', '_')",
+                    Colors.RED,
+                ),
+                file=sys.stderr,
+            )
+            return 1
+        workflow_md = repo_root / DIR_WORKFLOW / DIR_WORKFLOWS / f"{workflow_id}.md"
+        if not workflow_md.is_file():
+            print(
+                colored(
+                    f"Warning: {DIR_WORKFLOW}/{DIR_WORKFLOWS}/{workflow_id}.md does not exist yet; "
+                    "default workflow resolution is used until it is saved "
+                    "(trellis workflow --save).",
+                    Colors.YELLOW,
+                ),
+                file=sys.stderr,
+            )
+
     # Default assignee to current developer
     assignee = args.assignee
     if not assignee:
@@ -385,6 +411,10 @@ def cmd_create(args: argparse.Namespace) -> int:
         "notes": "",
         "meta": meta,
     }
+    # Optional per-task workflow selection: key present only when opted in,
+    # so tasks without a selection keep today's task.json shape byte-for-byte.
+    if workflow_id:
+        task_data["workflow"] = workflow_id
 
     write_json(task_json_path, task_data)
 

.trellis/scripts/common/workflow_phase.py

@@ -22,11 +22,12 @@ from __future__ import annotations
 
 import re
 
-from .paths import DIR_WORKFLOW, get_repo_root
+from . import workflow_selection
+from .paths import get_repo_root
 
 
 def _workflow_md_path():
-    return get_repo_root() / DIR_WORKFLOW / "workflow.md"
+    return workflow_selection.resolve_workflow_md(get_repo_root())
 
 # Match a line that *is* a platform marker: "[A, B, C]" or "[/A, B, C]"
 _MARKER_RE = re.compile(r"^\[(/?)([A-Za-z][^\[\]]*)\]\s*$")

.trellis/scripts/common/workflow_selection.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""
+Per-task workflow selection.
+
+Resolves which workflow markdown file consumers should read. A task may pin
+a workflow variant by storing `"workflow": "<id>"` in its task.json; the
+variant body lives at `.trellis/workflows/<id>.md` (user-managed library).
+
+Resolution precedence (single source of truth for all consumers), highest
+to lowest — each layer resolves an id to `.trellis/workflows/<id>.md` and
+falls through when unset, invalid, or pointing at a missing file:
+    1. Per-task pin  - active task's task.json `workflow` (session-bound,
+       explicit; a bad id or missing file warns once on stderr, then falls
+       through rather than aborting).
+    2. Personal      - `.developer` `workflow=<id>` (gitignored, per-developer;
+       outranks the team default). Silent on miss.
+    3. Team default  - config.yaml `default_workflow` (git-tracked, shared).
+       Silent on miss.
+    4. Global        - `.trellis/workflow.md`.
+With neither a per-task pin nor the personal/team keys set, this is identical
+to reading the global `.trellis/workflow.md`. Never raises.
+
+Provides:
+    workflow_md_for_task - Full precedence for an already-resolved task dir
+    resolve_workflow_md  - Session-aware wrapper via the active task resolver
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+from .paths import DIR_WORKFLOW, FILE_TASK_JSON
+
+# Workflow variant library directory under .trellis/ (plural on purpose:
+# `.trellis/workflow/` is reserved by the YAML-manifest migration).
+DIR_WORKFLOWS = "workflows"
+
+# Workflow ids must be plain slugs; anything else (path separators, dots)
+# is rejected so a task.json value can never escape .trellis/workflows/.
+WORKFLOW_ID_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+def _global_workflow_md(repo_root: Path) -> Path:
+    return repo_root / DIR_WORKFLOW / "workflow.md"
+
+
+def _library_variant(repo_root: Path, workflow_id: str | None) -> Path | None:
+    """Map a workflow id to its library file if valid and present, else None.
+
+    Shared by every layer (per-task pin, personal, team). An id with path
+    separators/dots/blanks, or one whose `.trellis/workflows/<id>.md` file does
+    not exist, returns None so the caller falls through. Never raises.
+    """
+    if not isinstance(workflow_id, str) or not workflow_id:
+        return None
+    if not WORKFLOW_ID_RE.match(workflow_id):
+        return None
+    variant = repo_root / DIR_WORKFLOW / DIR_WORKFLOWS / f"{workflow_id}.md"
+    return variant if variant.is_file() else None
+
+
+def _developer_workflow_id(repo_root: Path) -> str | None:
+    """Personal override id from the gitignored .developer file (fail-open)."""
+    try:
+        from .paths import get_developer_workflow
+
+        return get_developer_workflow(repo_root)
+    except Exception:
+        return None
+
+
+def _config_default_id(repo_root: Path) -> str | None:
+    """Team-shared default id from config.yaml `default_workflow` (fail-open)."""
+    try:
+        from .config import get_default_workflow
+
+        return get_default_workflow(repo_root)
+    except Exception:
+        return None
+
+
+def _default_workflow_md(repo_root: Path) -> Path:
+    """Resolve the non-per-task default: personal -> team -> global.
+
+    Personal (`.developer` `workflow=`) outranks the team-shared
+    (config.yaml `default_workflow`) layer; both fall through to the global
+    `.trellis/workflow.md` when unset, invalid, or naming a missing file. These
+    layers are silent on miss (they are defaults, not an explicit per-task
+    choice — a per-turn warning would be noise).
+    """
+    for get_id in (_developer_workflow_id, _config_default_id):
+        variant = _library_variant(repo_root, get_id(repo_root))
+        if variant is not None:
+            return variant
+    return _global_workflow_md(repo_root)
+
+
+def _task_pin_variant(repo_root: Path, task_dir: Path | None) -> Path | None:
+    """Return the per-task pinned variant path, or None to fall through.
+
+    Emits a stderr warning on an invalid id or a missing variant file (an
+    explicit per-task choice that cannot be honored), then returns None so
+    resolution continues with the personal/team defaults. Never raises.
+    """
+    if task_dir is None:
+        return None
+
+    try:
+        raw = json.loads((task_dir / FILE_TASK_JSON).read_text(encoding="utf-8"))
+        if not isinstance(raw, dict):
+            return None
+
+        workflow_id = raw.get("workflow")
+        if not isinstance(workflow_id, str) or not workflow_id:
+            return None
+
+        if not WORKFLOW_ID_RE.match(workflow_id):
+            print(
+                f"Warning: task '{task_dir.name}' has invalid workflow id "
+                f"{workflow_id!r}; using default workflow resolution",
+                file=sys.stderr,
+            )
+            return None
+
+        variant = _library_variant(repo_root, workflow_id)
+        if variant is not None:
+            return variant
+
+        print(
+            f"Warning: task '{task_dir.name}' selects workflow '{workflow_id}' but "
+            f"{DIR_WORKFLOW}/{DIR_WORKFLOWS}/{workflow_id}.md is missing; "
+            f"using default workflow resolution",
+            file=sys.stderr,
+        )
+        return None
+    except Exception:
+        return None
+
+
+def workflow_md_for_task(repo_root: Path, task_dir: Path | None) -> Path:
+    """Return the workflow.md path for an already-resolved task dir (or None).
+
+    Applies the full precedence documented in the module docstring:
+    per-task pin -> personal (.developer) -> team (config.yaml) -> global.
+    Never raises; any failure falls through toward the global workflow path.
+    """
+    pin = _task_pin_variant(repo_root, task_dir)
+    if pin is not None:
+        return pin
+    return _default_workflow_md(repo_root)
+
+
+def resolve_workflow_md(
+    repo_root: Path,
+    input_data: dict | None = None,
+    platform: str | None = None,
+) -> Path:
+    """Resolve the session-aware active task, then apply the resolution rule.
+
+    ``input_data`` is the raw hook payload (session/conversation identity);
+    CLI callers may omit it — the active-task resolver then falls back to
+    environment context. Never raises; any failure resolves to the global
+    `.trellis/workflow.md`.
+    """
+    try:
+        from .active_task import resolve_active_task, resolve_task_ref
+
+        active = resolve_active_task(repo_root, input_data, platform)
+        task_dir: Path | None = None
+        if active.task_path:
+            task_dir = resolve_task_ref(active.task_path, repo_root)
+        return workflow_md_for_task(repo_root, task_dir)
+    except Exception:
+        return _global_workflow_md(repo_root)

.trellis/scripts/task.py

@@ -11,6 +11,7 @@ Usage:
     python3 task.py start <dir>                 # Set active task
     python3 task.py current [--source] [--json] # Show active task
     python3 task.py finish                      # Clear active task
+    python3 task.py workflow <id>|--clear       # Set/clear per-task workflow selection
     python3 task.py set-branch <dir> <branch>   # Set git branch
     python3 task.py set-base-branch <dir> <branch>  # Set PR target branch
     python3 task.py set-scope <dir> <scope>     # Set scope for PR title
@@ -47,6 +48,7 @@ from common.active_task import (
 from common.io import read_json, write_json
 from common.task_utils import resolve_task_dir, run_task_hooks
 from common.tasks import iter_active_tasks, children_progress
+from common.workflow_selection import WORKFLOW_ID_RE, workflow_md_for_task
 
 # Import command handlers from split modules (also re-exports for plan.py compatibility)
 from common.task_store import (
@@ -204,6 +206,72 @@ def cmd_current(args: argparse.Namespace) -> int:
     return 1
 
 
+# =============================================================================
+# Command: workflow
+# =============================================================================
+
+def cmd_workflow(args: argparse.Namespace) -> int:
+    """Set or clear the workflow selection on the current session's active task."""
+    repo_root = get_repo_root()
+
+    if args.clear and args.id:
+        print(colored("Error: pass either <id> or --clear, not both", Colors.RED))
+        return 1
+    if not args.clear and not args.id:
+        print(colored("Error: workflow id required (or --clear)", Colors.RED))
+        print("Usage: python3 task.py workflow <id> | --clear")
+        return 1
+
+    active = resolve_active_task(repo_root)
+    if not active.task_path:
+        print(colored("Error: No current task set", Colors.RED))
+        print("Hint: run task.py start <dir> first")
+        return 1
+
+    task_dir = repo_root / active.task_path
+    task_json_path = task_dir / FILE_TASK_JSON
+    if not task_json_path.is_file():
+        print(colored(f"Error: task.json not found at {task_dir}", Colors.RED))
+        return 1
+
+    data = read_json(task_json_path)
+    if not data:
+        print(colored(f"Error: failed to read {task_json_path}", Colors.RED))
+        return 1
+
+    if args.clear:
+        if data.pop("workflow", None) is None:
+            print(colored("No workflow selection set on this task", Colors.YELLOW))
+        else:
+            if not write_json(task_json_path, data):
+                print(colored("Error: failed to update task.json", Colors.RED))
+                return 1
+            print(colored("✓ Workflow selection cleared", Colors.GREEN))
+    else:
+        workflow_id = args.id
+        if not WORKFLOW_ID_RE.match(workflow_id):
+            print(colored(
+                f"Error: invalid workflow id '{workflow_id}' (allowed: letters, digits, '-', '_')",
+                Colors.RED,
+            ))
+            return 1
+        data["workflow"] = workflow_id
+        if not write_json(task_json_path, data):
+            print(colored("Error: failed to update task.json", Colors.RED))
+            return 1
+        print(colored(f"✓ Workflow set to: {workflow_id}", Colors.GREEN))
+
+    # workflow_md_for_task warns on stderr itself when the selected variant
+    # file is missing (it can be saved later via `trellis workflow --save`).
+    effective = workflow_md_for_task(repo_root, task_dir)
+    try:
+        effective_display = effective.relative_to(repo_root).as_posix()
+    except ValueError:
+        effective_display = str(effective)
+    print(f"Effective workflow: {effective_display}")
+    return 0
+
+
 # =============================================================================
 # Command: list
 # =============================================================================
@@ -382,12 +450,15 @@ Usage:
   python3 task.py create <title> --package <pkg>     Create task for a specific package
   python3 task.py create <title> --parent <dir>      Create task as child of parent
   python3 task.py create <title> --no-start          Create without making it active in this session
+  python3 task.py create <title> --workflow <id>     Create task pinned to a workflow variant
   python3 task.py add-context <dir> <jsonl> <path> [reason]  Add entry to jsonl
   python3 task.py validate <dir>                     Validate jsonl files
   python3 task.py list-context <dir>                 List jsonl entries
   python3 task.py start <dir>                        Set active task
   python3 task.py current [--source]                 Show active task
   python3 task.py finish                             Clear active task
+  python3 task.py workflow <id>                      Select workflow variant for active task
+  python3 task.py workflow --clear                   Clear selection (use default resolution)
   python3 task.py set-branch <dir> <branch>          Set git branch
   python3 task.py set-base-branch <dir> <branch>     Set PR target branch
   python3 task.py set-scope <dir> <scope>            Set scope for PR title
@@ -490,6 +561,10 @@ def main() -> int:
         action="store_true",
         help="Create the task without making it active in this session",
     )
+    p_create.add_argument(
+        "--workflow",
+        help="Workflow variant id for this task (.trellis/workflows/<id>.md)",
+    )
 
     # add-context
     p_add = subparsers.add_parser("add-context", help="Add context entry")
@@ -520,6 +595,12 @@ def main() -> int:
     # finish
     subparsers.add_parser("finish", help="Clear active task")
 
+    # workflow
+    p_workflow = subparsers.add_parser("workflow", help="Set/clear per-task workflow selection")
+    p_workflow.add_argument("id", nargs="?", help="Workflow id (.trellis/workflows/<id>.md)")
+    p_workflow.add_argument("--clear", action="store_true",
+                            help="Remove the workflow selection (use default resolution)")
+
     # set-branch
     p_branch = subparsers.add_parser("set-branch", help="Set git branch")
     p_branch.add_argument("dir", help="Task directory")
@@ -580,6 +661,7 @@ def main() -> int:
         "start": cmd_start,
         "current": cmd_current,
         "finish": cmd_finish,
+        "workflow": cmd_workflow,
         "set-branch": cmd_set_branch,
         "set-base-branch": cmd_set_base_branch,
         "set-scope": cmd_set_scope,

.trellis/tasks/archive/2026-09/09-01-optimize-stock-list-radar/task.json

@@ -3,7 +3,7 @@
   "name": "optimize-stock-list-radar",
   "title": "优化选股列表与资金雷达看板布局",
   "description": "",
-  "status": "in_progress",
+  "status": "completed",
   "dev_type": null,
   "scope": null,
   "package": null,
@@ -11,7 +11,7 @@
   "creator": "codex",
   "assignee": "codex",
   "createdAt": "2026-09-01",
-  "completedAt": null,
+  "completedAt": "2026-09-25",
   "branch": null,
   "base_branch": "main",
   "worktree_path": null,

.trellis/tasks/archive/2026-09/09-04-add-gold-brick-strategy/task.json

@@ -3,7 +3,7 @@
   "name": "add-gold-brick-strategy",
   "title": "新增金砖共振选股策略",
   "description": "按收盘后、qfq、沪深非ST口径新增金砖共振策略，复用B1指标并增加可复制诊断日志。",
-  "status": "in_progress",
+  "status": "completed",
   "dev_type": null,
   "scope": null,
   "package": null,
@@ -11,7 +11,7 @@
   "creator": "yuxuanhui",
   "assignee": "yuxuanhui",
   "createdAt": "2026-09-04",
-  "completedAt": null,
+  "completedAt": "2026-09-25",
   "branch": null,
   "base_branch": "main",
   "worktree_path": null,

.trellis/tasks/archive/2026-09/09-05-selection-layout-sector-filter/task.json

@@ -3,7 +3,7 @@
   "name": "selection-layout-sector-filter",
   "title": "选股页面迭代：布局重构与板块筛选",
   "description": "",
-  "status": "planning",
+  "status": "completed",
   "dev_type": null,
   "scope": null,
   "package": null,
@@ -11,7 +11,7 @@
   "creator": "yuxuanhui",
   "assignee": "yuxuanhui",
   "createdAt": "2026-09-05",
-  "completedAt": null,
+  "completedAt": "2026-09-25",
   "branch": null,
   "base_branch": "main",
   "worktree_path": null,

.trellis/tasks/archive/2026-09/09-06-capital-radar-daily-detail/task.json

@@ -3,7 +3,7 @@
   "name": "capital-radar-daily-detail",
   "title": "资金雷达：单日榜单与板块详情",
   "description": "",
-  "status": "in_progress",
+  "status": "completed",
   "dev_type": null,
   "scope": null,
   "package": null,
@@ -11,7 +11,7 @@
   "creator": "yuxuanhui",
   "assignee": "yuxuanhui",
   "createdAt": "2026-09-06",
-  "completedAt": null,
+  "completedAt": "2026-09-25",
   "branch": null,
   "base_branch": "main",
   "worktree_path": null,

.trellis/tasks/archive/2026-09/09-07-api-performance-diagnosis/check.jsonl

@@ -0,0 +1,3 @@
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "后端必要检查与测试形状"}
+{"file": ".trellis/spec/backend/http-api-contracts.md", "reason": "HTTP 兼容性"}
+{"file": ".trellis/tasks/09-07-api-performance-diagnosis/design.md", "reason": "已批准设计与性能证据"}

.trellis/tasks/archive/2026-09/09-07-api-performance-diagnosis/design.md

@@ -0,0 +1,44 @@
+# 性能诊断与建议设计（已批准实施）
+
+## 证据与边界
+2026-09-07，低频公网 GET：示例 detail 四次 3.045 / 3.059 / 3.074 / 3.442 秒，200，10750 字节；显式绕过本机代理复测 3.312557 秒，TLS 完成 0.443439 秒，首字节 3.312484 秒。直连 healthz 0.810132 秒、dates 0.815043 秒、ratio 榜单 2.570251 秒。默认网络路径 history 1.834179 秒、2020-01-01 无数据 detail 0.746555 秒。请求成功验证示例为 SPD概念，成员 14 个。
+
+这些是客户端端到端耗时，不是服务端或 SQL 独立耗时；样本不足以推断 P95、并发容量或全站所有接口。生产代码版本、CPU/IO/锁等待及 SQL 执行计划未验证。
+
+## 当前调用链
+- presentation/http.py:355 -> ReadRadarDetails.detail -> history -> history_data。
+- application/details.py:145 的 history_data 加载最多 30 个发布日的全部排名；为了取得 calendar，调用 snapshots 加载整个批次全部原始输入。
+- application/details.py:294 的 detail 再次调用 snapshots，并在 Python 中重建股票基础信息、全体成员关系、行情和资金索引，再计算相似板块。
+- infrastructure/postgres.py:194 的 load_publication_sources 按 publication_id 连接来源表和快照表，SELECT 包括完整 JSONB payload，没有 source_group 或证券过滤；:1112 还把每个 payload 行复制为 dict。
+- application/details.py:182 的 ranking_extras 具有相同的重复读取模式；read.py:285 在 amount/ratio 榜单调用它。
+- presentation/http.py:258 已按进程缓存仓储；postgres.py:48 默认连接池上限 4。当前部署 Dockerfile:48 没有显式指定 worker 数量，但生产环境覆盖与并发压力未知，不能据此确诊排队。
+
+本地使用 tests/unit/sector_radar/test_read.py 的内存仓储夹具，仅代理计数真实应用层调用，不改产品代码：detail 为 get_successful_publication=1, load_history_publications=1, load_publication_rankings=1, load_publication_sources=2；普通金额榜单另有 load_rankings=1。此实验确认调用次数，不测量生产 SQL 成本。
+
+## 已批准的优化次序
+1. 取得服务端分段计时与只读查询计划，分别测连接池等待、SQL 执行与取数、JSON 转换、Python 组装；先对最重的快照读取确认行数和字节数。
+2. 日历只读取 calendar 来源；同一请求避免重复读取同一发布输入，先减少明显多余工作。
+3. 详情优先读取既有 publication 归属的事实和聚合投影；成员及股票只取所需范围，相似板块考虑在发布阶段预计算。旧批次投影缺失必须保持当前缺失语义，不能换用全局最新成员或直接读 Tushare。
+4. 历史请求保留同类同版本的真实排名池大小、名次、百分位和缺失状态，SQL 只返回所需板块结果与分组统计，避免每次构造全量排名对象并重复扫描。
+5. 仅在查询计划显示需要时提出索引；当前 publication/source/ranking 已有主键及索引，不能笼统归因为缺索引。
+6. 优化冷请求后，依据重复访问与并发数据决定是否加入有界进程缓存或 Redis。
+
+## Redis 取舍与一致性
+Redis 可缓存最终响应/紧凑投影，适合读多写少的已发布收盘数据，尤其多进程/多实例需要共享结果时。它不是当前诊断的必要前提；只安装服务并不加速，必须接入读取、写入和失效逻辑，未命中仍走原查询。
+
+缓存键至少含响应 schema 版本、请求参数、当前 publication_id；含历史曲线的响应还依赖此前各日选中的 publication_id/source_version/metric_version，历史补录或重建也必须改变键或触发失效，不能仅使用目标日期或当前批次 ID。缓存只保存成功且版本明确的投影，设置容量上限、TTL、并发回填保护和故障回源。TTL 不替代明确的发布版本语义。
+
+官方资料：https://redis.io/docs/latest/develop/use-cases/cache-aside/ ，已经 Context7 与官方网页核验通用 cache-aside、TTL 和显式失效机制；当前项目未发现 Redis 依赖，未选择版本。
+
+## 兼容与回滚
+不改变 HTTP 字段、精度、历史缺失语义、最后有效发布规则。缓存层应可关闭回源；如后续需要新增投影或迁移，应先独立评审与授权。用户已批准本地实现与验证；线上发布由用户负责。
+
+## 本轮落实的读取设计
+- 新增 publication-scoped 原始行投影读取接口，明确 sources、trade_date、ts_codes 过滤，不伪造带原快照哈希的裁剪快照。保留 source_order 和快照内行顺序，保证重复键覆盖行为不变。
+- 历史只读 calendar；榜单额外只读指数；详情先读取指数/股票基础/成员用于当前上市池和重合率，再按目标日与成员读取 daily/moneyflow_dc/moneyflow。
+- 新增按所需板块读取历史排名的查询，完整排名池分组统计在过滤目标板块前完成；不存在板块也保留该池大小。应用层一次建立按板块、指标、版本的查找表，避免循环扫描。
+- 既有 stock_fact 非 available 会清除 net_amount 且没有 publication_id，旧字段也可能空，不能直接无损替代独立来源读数；本轮不迁移、不重建、不引入全局缓存。相似度在请求内基于必要成员集计算。
+- 性能目标用同一隔离 PostgreSQL 数据集前后对比与传输范围断言验证，实际公网改善由用户发布后验证。
+
+## 验证结论
+实现只改四个 sector_radar 后端文件，新增读取回归测试文件。无迁移、依赖、HTTP 字段或全局缓存改动。真实数据库结果、完整响应一致性及前后耗时记录在 research/performance.json。详情仍需要相似板块和上市过滤使用的完整成员/基础信息；不兼容来源版本的少量池统计仍在查询后丢弃，这两点保留为后续测量候选。

.trellis/tasks/archive/2026-09/09-07-api-performance-diagnosis/implement.jsonl

@@ -0,0 +1,3 @@
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "后端必要检查与测试形状"}
+{"file": ".trellis/spec/backend/http-api-contracts.md", "reason": "HTTP 兼容性"}
+{"file": ".trellis/tasks/09-07-api-performance-diagnosis/design.md", "reason": "已批准设计与性能证据"}

.trellis/tasks/archive/2026-09/09-07-api-performance-diagnosis/implement.md

@@ -0,0 +1,30 @@
+# 后续执行建议（已批准实施）
+
+## 当前已完成
+- [x] 公网低频请求复现与分段计时，包含显式直连对照。
+- [x] 检查路由、应用层、仓储、既有迁移和部署配置。
+- [x] 用现有内存仓储夹具追踪重复读取，未修改产品代码。
+- [x] Redis 取舍与发布/历史依赖失效边界分析。
+
+## 实施顺序
+1. 核对生产版本并收集脱敏的 server/request 分段耗时、池等待、查询行数与字节数；针对 SELECT 使用只读执行计划并设超时，不做生产压力测试。
+2. 审阅需修改文件全文并加载 backend 规格，明确最终性能目标；补齐真实 implement/check 上下文清单后再 task.py start。
+3. 优先修复完整快照重复读取和日历过量读取，增加能约束调用次数、过滤范围及历史一致性的回归测试。
+4. 根据实测再决定缩小排名结果、使用既有投影或新增预计算。每项范围变化都更新设计；不以增加连接数或 worker 数替代测量。
+5. 运行受影响测试、后端规定的 Ruff、Pyright 和 pytest；固定样本比较输出语义与耗时。在获批的环境验证冷/热请求与必要并发，不凭公网少量样本宣称 P95。
+6. 仅在确认缓存需求后评审 Redis；验证重建、历史补录、并发回填、容量淘汰和 Redis 不可用时回源。
+
+## 风险与授权
+用户已明确批准按方案实施本地优化和验证。隔离本地 PostgreSQL 用于查询正确性与对比，禁止连接生产执行写入或压测。用户随后明确要求提交到本地 develop；不推送、不部署、不更新共享规范。
+
+## 本轮实现与验证结果
+- [x] publication 行投影查询按 source_group、目标日、ts_code 过滤，source_order/ordinality 稳定，无原始快照重复取数。
+- [x] 历史排名在 SQL 中统计完整池后过滤板块；应用层索引查找；缺失板块、旧指标版本、不兼容来源版本、请求期间重建钉住均覆盖。
+- [x] 真实 PostgreSQL 隔离 schema 验证，旧版仅原始快照数据仍可读取独立缺失值；未排行和行业池不会污染概念池。
+- [x] 独立只读审查 /root/read_path_review 完成，无阻塞发现；主代理负责修改与执行验证。
+- [x] 本地同一数据集三端点各 5 次 before/after 比较，全量响应一致。详情中位 1.7107→0.4841s；history 0.8580→0.0262s；rankings 1.2415→0.0645s。详见 research/performance.json，不能作为生产 SLA。
+- [x] Ruff format/check 通过；受改文件 Pyright 验证；全仓 Pyright 14 个 selection 错误与修改前文件/行/内容逐项完全一致。
+- [x] 后端全套以 unit→HTTP→integration 顺序执行：226 passed / 1 failed。剩余市场数据集成测试在修改前复现 Connection.executemany AttributeError；不扩大修改范围。默认集成测试优先顺序另有既存 Alembic fileConfig 污染 caplog 的问题。
+- [ ] 用户自行发布后复测公网 detail/history/rankings；无 Redis、无迁移、不要求历史重跑。
+
+本地实现已完成。质量门禁存在明确的既有阻塞，未宣称全仓全绿；用户已授权将实现、回归测试和性能证据提交到本地 develop；任务待用户发布验证，暂不归档。

.trellis/tasks/archive/2026-09/09-07-api-performance-diagnosis/prd.md

@@ -0,0 +1,27 @@
+# 接口性能诊断与缓存方案评估
+
+## 目标
+解释用户观察到的多个接口约 3 秒延迟，以概念板块 BK1147.DC 在 2026-09-04 的详情接口为切入点，在不引入 Redis 的情况下优化冷请求读取与计算，供用户自行发布后评估效果。
+
+## 已确认事实
+- 用户已在诊断与方案回顾后明确批准按优化顺序开始实施，由用户自行发布；Redis 留待上线效果验证后评估。
+- 公网 GET 四次均返回 HTTP 200，总耗时 3.045–3.442 秒，响应体 10750 字节；主要等待发生在首字节之前。
+- 排查开始时本地 develop 分支工作区干净；生产是否与当前提交一致尚未确认。
+- 静态检查及本地调用追踪确认：详情与金额榜单每次调用两次 load_publication_sources；来源查询读取完整 payload（application/details.py:145、:182、:294；infrastructure/postgres.py:194）。
+
+## 范围与要求
+- 低频只读测量示例请求，分析本地路由、查询、连接管理与部署配置。
+- 区分观测事实、代码风险和待生产证据验证的假设。
+- 实施资金雷达详情、历史和榜单的最小充分读取优化；不修改外部系统。
+
+## 验收标准
+- 详情/榜单/历史不再加载完整发布快照，按需读取来源组、目标日与成员；历史只传输目标板块排名及完整池统计。
+- 保留全部 HTTP 字段、Decimal 精度、旧批次独立缺失值、历史发布选择与相似板块口径。
+- 通过真实 PostgreSQL 查询验证、语义回归测试和后端质量门禁，给出同一数据集的前后性能比较；不承诺未上线的公网秒数。
+- 记录可复现请求的分段耗时，避免把总耗时直接等同于 SQL 耗时。
+- 为关键判断提供代码位置或实测依据。
+- 说明 Redis 是否必要、适用条件及失效策略边界。
+- 明确未验证事项及下一步建议。
+
+## 不在范围内
+生产压测、部署、迁移、创建索引、接入 Redis、修改共享规范、推送远端。用户已另行授权提交本地 develop。

.trellis/tasks/archive/2026-09/09-07-api-performance-diagnosis/research/benchmark.py

@@ -0,0 +1,126 @@
+"""Task-local benchmark: isolated localhost PostgreSQL only; no production writes.
+
+Run from zhixing-server with DATABASE_URL pointing to a disposable test database.
+Set PYTHONPATH to the before/after source tree to compare the same persisted data.
+Use --seed once, then --run before.json / --run after.json (five reads per endpoint).
+"""
+import argparse
+import hashlib
+import json
+import os
+import runpy
+import statistics
+import time
+from dataclasses import replace
+from datetime import timedelta
+from decimal import Decimal
+from pathlib import Path
+from urllib.parse import urlsplit
+from unittest.mock import patch
+
+import psycopg
+from alembic import command
+from alembic.config import Config
+from zhixing_server.bootstrap.config import Settings, sqlalchemy_database_url
+from zhixing_server.modules.sector_radar.application.details import ReadRadarDetails
+from zhixing_server.modules.sector_radar.application.read import ReadSectorRadar, RadarQuery
+from zhixing_server.modules.sector_radar.domain.models import PublicationStatus, SectorType, MetricKind, MetricUnit
+from zhixing_server.modules.sector_radar.domain.metrics import AmountNetStrategy, RatioTurnoverStrategy, SwingEqualThreeToTenStrategy
+from zhixing_server.modules.sector_radar.domain.persistence import PublicationSourceGroup as Group, PublicationSourceRecord, RankingRecord
+from zhixing_server.modules.sector_radar.domain.ranking import rank_metric_observations
+from zhixing_server.modules.sector_radar.domain.source import build_source_snapshot
+from zhixing_server.modules.sector_radar.infrastructure.postgres import PostgresSectorRadarRepository
+from zhixing_server.modules.sector_radar.presentation.http import _detail_response, _history_response, _rankings_response
+
+parser = argparse.ArgumentParser()
+parser.add_argument('--seed', action='store_true')
+parser.add_argument('--run', type=Path)
+args = parser.parse_args()
+url = os.environ['DATABASE_URL']
+assert urlsplit(url).hostname in {'localhost', '127.0.0.1'}, 'disposable local database only'
+samples = runpy.run_path('tests/unit/sector_radar/test_detail_reads.py')
+target, now, code = samples['TARGET'], samples['NOW'], samples['CODE']
+repo = PostgresSectorRadarRepository(url)
+
+if args.seed:
+    config = Config('alembic.ini')
+    config.set_main_option('sqlalchemy.url', sqlalchemy_database_url(url).replace('%', '%%'))
+    config.config_file_name = None
+    with patch('zhixing_server.bootstrap.config.get_settings', return_value=Settings(database_url=url)):
+        command.upgrade(config, 'head')
+    samples['seed_detail'](repo)
+    current = repo.get_successful_publication(target)
+    template = repo.load_rankings(current.publication_id)[0].observation
+    stocks = [f'{i:06d}.SZ' for i in range(10, 3010)]
+    sectors = [f'PERF{i:04d}.DC' for i in range(500)]
+    def save(group, rows, order, day=target):
+        snapshot = build_source_snapshot(api_name=group.value, params={'batch': str(order)}, rows=rows,
+                                         target_trade_date=day, observed_at=now)
+        repo.save_source_snapshots((snapshot,))
+        repo.save_publication_sources((PublicationSourceRecord(current.publication_id, group, order, snapshot),))
+    save(Group.STOCK_BASICS, tuple({'ts_code': s, 'symbol': s[:6], 'name': s, 'exchange': 'SZSE',
+                                   'list_status': 'L', 'list_date': '20200101'} for s in stocks), 1)
+    save(Group.CONCEPT_INDICES, tuple({'ts_code': s, 'name': s, 'trade_date': str(target),
+                                      'pct_change': '1.1234'} for s in sectors), 1)
+    save(Group.MEMBERS, tuple({'ts_code': sector, 'con_code': stocks[(i*7+j)%len(stocks)],
+                              'name': stocks[(i*7+j)%len(stocks)], 'trade_date': str(target)}
+                              for i, sector in enumerate(sectors) for j in range(100)), 1)
+    for offset in range(10):
+        day = target-timedelta(days=offset)
+        for group in (Group.DAILY, Group.MONEYFLOW_DC, Group.MONEYFLOW):
+            rows = tuple({'ts_code': stock, 'trade_date': str(day), 'name': stock,
+                          'pct_chg': str(Decimal(i % 123)/100), 'amount': str(i*12),
+                          'net_amount': str(i-1500), 'net_mf_amount': str(i-500),
+                          'close': str(Decimal(i%1000)/10+1), 'vol': str(i*33)}
+                         for i, stock in enumerate(stocks))
+            save(group, rows, offset+1, day)
+    versions = ((MetricKind.AMOUNT, AmountNetStrategy.metric_version, MetricUnit.CNY_100M),
+                (MetricKind.RATIO, RatioTurnoverStrategy.metric_version, MetricUnit.RATIO),
+                (MetricKind.SWING, SwingEqualThreeToTenStrategy.metric_version, MetricUnit.RATIO))
+    for offset in range(30):
+        day = target-timedelta(days=offset)
+        if offset < 2:
+            publication = repo.get_successful_publication(day)
+        else:
+            running = replace(current, publication_id=f'bench-{offset}', target_trade_date=day,
+                              status=PublicationStatus.RUNNING, input_hash=None, finished_at=None)
+            repo.create_publication(running)
+            publication = replace(running, status=PublicationStatus.SUCCESS, input_hash='a'*64,
+                                  finished_at=now+timedelta(seconds=1))
+            repo.finish_publication(publication)
+        rankings = []
+        for kind, version, unit in versions:
+            observations = tuple(replace(template, trade_date=day, sector_code=sector, sector_name=sector,
+                                          metric_kind=kind, metric_version=version, unit=unit,
+                                          value=Decimal(i+1)) for i, sector in enumerate(sectors))
+            rankings.extend(RankingRecord(publication.publication_id, row)
+                            for row in rank_metric_observations(observations))
+        repo.save_rankings(rankings)
+    with psycopg.connect(url) as connection:
+        connection.execute('ANALYZE')
+        print('dataset', connection.execute('SELECT count(*), sum(row_count), sum(octet_length(payload::text)) FROM sector_radar_source_snapshot').fetchone(),
+              'rankings', connection.execute('SELECT count(*) FROM sector_radar_ranking').fetchone())
+
+if args.run:
+    repo.open()
+    reads = {
+        'detail': lambda: _detail_response(ReadRadarDetails(repo).detail(target, SectorType.CONCEPT, code)),
+        'history': lambda: _history_response(ReadRadarDetails(repo).history(target, SectorType.CONCEPT, code)),
+        'rankings': lambda: _rankings_response(ReadSectorRadar(repo).query(RadarQuery(trade_date=target, page_size=20))),
+    }
+    report = {}
+    for label, read in reads.items():
+        timings = []
+        responses = []
+        for _ in range(5):
+            start = time.perf_counter()
+            response = read().model_dump(mode='json')
+            timings.append(time.perf_counter()-start)
+            responses.append(response)
+        assert all(item == responses[0] for item in responses)
+        fingerprint = hashlib.sha256(json.dumps(responses[0], sort_keys=True).encode()).hexdigest()
+        report[label] = {'seconds': timings, 'median_seconds': statistics.median(timings),
+                         'response_sha256': fingerprint, 'response': responses[0]}
+        print(label, 'median', report[label]['median_seconds'], 'sha256', fingerprint, flush=True)
+    args.run.write_text(json.dumps(report, ensure_ascii=False, indent=2))
+repo.close()

.trellis/tasks/archive/2026-09/09-07-api-performance-diagnosis/research/performance.json

@@ -0,0 +1,100 @@
+{
+  "environment": "isolated local PostgreSQL 16-alpine, Python 3.12.11, psycopg 3.3.4; same data, sequential requests, warm database/connection pool, no application cache",
+  "baseline_commit": "e567e5f",
+  "dataset": {
+    "snapshot_count": 41,
+    "source_rows": 143521,
+    "source_json_bytes": 22785765,
+    "ranking_rows": 45003
+  },
+  "samples_per_endpoint": 5,
+  "measurements": {
+    "detail": {
+      "before_seconds": [
+        1.7919143750004878,
+        1.7288594170004217,
+        1.7106771250000747,
+        1.7057415830004174,
+        1.6912810410012753
+      ],
+      "after_seconds": [
+        0.6212627920012892,
+        0.4883682920008141,
+        0.44150824999996985,
+        0.43969708400072705,
+        0.4841277909999917
+      ],
+      "before_median_seconds": 1.7106771250000747,
+      "after_median_seconds": 0.4841277909999917,
+      "reduction_percent": 71.7,
+      "responses_identical": true,
+      "response_sha256": "d2d5693152e949767a2db8e807852fe6fd2cb6ec175664a5dab9f615cdda4467"
+    },
+    "history": {
+      "before_seconds": [
+        0.8467425830003776,
+        0.8580366249989311,
+        0.8756502500000352,
+        0.8701953330000833,
+        0.8388115420002578
+      ],
+      "after_seconds": [
+        0.026230833000226994,
+        0.024217250000219792,
+        0.025365250001414097,
+        0.028609290999156656,
+        0.026671499999793014
+      ],
+      "before_median_seconds": 0.8580366249989311,
+      "after_median_seconds": 0.026230833000226994,
+      "reduction_percent": 96.9,
+      "responses_identical": true,
+      "response_sha256": "edf098e1f124a6d5526d9f202b67c6e97986095a6cb18fad3d0d6ba07d10d387"
+    },
+    "rankings": {
+      "before_seconds": [
+        1.3065002089988411,
+        1.2318050410012802,
+        1.2226990420003858,
+        1.3149193330009439,
+        1.2414632910004002
+      ],
+      "after_seconds": [
+        0.06522883400066348,
+        0.06445087500105728,
+        0.06437025000013818,
+        0.06701250000151049,
+        0.06281666699942434
+      ],
+      "before_median_seconds": 1.2414632910004002,
+      "after_median_seconds": 0.06445087500105728,
+      "reduction_percent": 94.8,
+      "responses_identical": true,
+      "response_sha256": "dbe90217c0086e22a570990062e08583c44d72ca1b4cf87b39208b033ce12e62"
+    }
+  },
+  "query_plan_samples": [
+    {
+      "query": "source_rows",
+      "execution_ms": 31.641,
+      "planning_ms": 1.534,
+      "rows": 3
+    },
+    {
+      "query": "rank_history",
+      "execution_ms": 23.911,
+      "planning_ms": 0.664,
+      "rows": 90
+    }
+  ],
+  "validation": {
+    "pytest_passed": 226,
+    "pytest_failed_baseline": 1,
+    "baseline_failure": "test_market_data_repository_pool.py:65 Connection.executemany AttributeError, reproduced before edits",
+    "pyright_baseline_errors": 14,
+    "pyright_new_errors": 0,
+    "ruff": "passed",
+    "review_agent": "/root/read_path_review complete: no blocking SQL/data correctness findings",
+    "caveat": "Default integration-first ordering also disables caplog loggers through pre-existing Alembic fileConfig. Full tests were run unit/HTTP/integration order with both DB environment variables set; one baseline integration failure remained."
+  }
+}

.trellis/tasks/archive/2026-09/09-07-api-performance-diagnosis/task.json

@@ -0,0 +1,26 @@
+{
+  "id": "api-performance-diagnosis",
+  "name": "api-performance-diagnosis",
+  "title": "接口性能诊断与缓存方案评估",
+  "description": "优化资金雷达详情、历史与榜单读取；无 Redis、无迁移，待用户发布验证。",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "yuxuanhui",
+  "assignee": "yuxuanhui",
+  "createdAt": "2026-09-07",
+  "completedAt": "2026-09-25",
+  "branch": "develop",
+  "base_branch": "develop",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "用户已授权提交本地 develop。226 项测试通过；1 个既有集成测试失败和 14 个既有类型错误均在修改前复现。",
+  "meta": {}
+}

.trellis/tasks/archive/2026-09/09-21-onechart-score-reconstruction/check.jsonl

@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}

.trellis/tasks/archive/2026-09/09-21-onechart-score-reconstruction/design.md

@@ -0,0 +1,9 @@
+# 研究设计
+
+这是只读分析任务，不进入产品实现阶段。
+
+公开证据链：页面展示 → 实际引用脚本 → 实际请求的公开数据 → 评分与排名字段。数据库证据链：库表目录 → 字段及单位 → 重叠交易日原始值 → 候选公式复算 → 与公开评分比较。
+
+优先检验可解释的低自由度公式。分开检验资金比率、横截面排序/归一化、时间窗口聚合；用多日和不同板块类型验证，避免单点拟合。识别数据修订、单位换算、成分股聚合与板块原始数据的口径差异。
+
+数据库连接强制 default_transaction_read_only，设置查询超时。仅在本机保留任务所需数据；公开资料可以缓存供复核，凭据不落盘。报告不将无法唯一识别的参数写成确定结论。

.trellis/tasks/archive/2026-09/09-21-onechart-score-reconstruction/implement.jsonl

@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}

.trellis/tasks/archive/2026-09/09-21-onechart-score-reconstruction/implement.md

@@ -0,0 +1,9 @@
+# 分析步骤（无产品实现）
+
+- [x] 读取网站公开脚本和数据，记录字段、日期和来源。
+- [x] 只读确认数据库版本、数据表及覆盖范围。
+- [x] 建立日期、板块和单位映射，对比原始输入。
+- [x] 逐层验证单日评分和波段评分候选公式，记录误差。
+- [x] 核验关键结论，完成研究记录与用户答复。
+
+验证使用实际数据计算与证据核对；不运行与分析无关的产品测试。任务不包含代码实施、共享知识推广、提交和发布。

.trellis/tasks/archive/2026-09/09-21-onechart-score-reconstruction/prd.md

@@ -0,0 +1,25 @@
+# 还原 OneChart 波段与单日资金流评分
+
+## Goal
+
+分析 https://onechartlab.com/ 板块资金雷达的波段流入率、单日流入率及其加权评分，结合用户本机 PostgreSQL 数据给出可复核的公式证据、复算结果和不确定性。
+
+## Requirements
+
+- 区分原始资金比率、评分和排名，明确时间窗口、权重、标准化、排名池和缺失数据规则。
+- 优先读取网站实际公开的 HTML、脚本和数据；不将本项目独立指标策略视为该站点真实公式。
+- 数据库仅使用只读连接及有范围限制的 SELECT，先确认可用库、表、字段与日期。
+- 使用相同日期、板块标识和数据口径进行多样本验证，记录误差及候选公式可识别性。
+- 用户已同意创建任务并记录分析。只修改当前任务记录，不修改产品代码、数据库或共享规格，不提交或发布。
+- 凭据不写入任务记录、研究脚本、结果文件或报告；本机数据不传给外部服务。
+
+## Acceptance Criteria
+
+- [x] 列出评分相关公开字段及来源，说明公式是否直接公开。
+- [x] 给出单日与波段评分的可验证公式，或明确最有依据的候选公式和未解决参数。
+- [x] 用数据库与网站重叠样本核验，报告样本范围、误差和差异原因。
+- [x] 保存必要分析记录与可复算证据，最终回答清楚区分事实、推断和限制。
+
+## 结果
+
+公开原始字段可精确重现最近 12 日 9,492 条记录，两种评分最大绝对误差约 3.41e-13；数据库最新日原始快照试算平均误差为单日 0.9783 分、波段 1.9076 分，个别板块仍有较大输入差异。详见 `research/findings.md` 和 `research/database-validation.md`。本研究已完成，没有产品实施待批准。

.trellis/tasks/archive/2026-09/09-21-onechart-score-reconstruction/research/database-validation.json

@@ -0,0 +1,128 @@
+{
+  "normalized_aggregate": {
+    "joined_rows": 12654,
+    "joined_dates": 16,
+    "latest_rows": 791,
+    "Ratio": {
+      "checked_rows": 791,
+      "mean_absolute_error": 4.66428796165067,
+      "max_absolute_error": 129.76729492953035,
+      "same_one_decimal_display": 204,
+      "same_final_rank": 215
+    },
+    "Swing": {
+      "checked_rows": 791,
+      "mean_absolute_error": 4.803044287121097,
+      "max_absolute_error": 179.7496672672861,
+      "same_one_decimal_display": 96,
+      "same_final_rank": 199
+    },
+    "turnover_within_1_01_yuan": 294,
+    "weight_within_1e_10": 280,
+    "examples": [
+      {
+        "ts_code": "BK0581.DC",
+        "index_name": "智能电网 (概念)",
+        "ratio_db": 0.01288923245126,
+        "weight_db": 1.08086957077924,
+        "pred_Ratio_Score": 684.0285689472486,
+        "Ratio_Score": 789.4114202884311,
+        "pred_Swing_Score": 386.3978175732549,
+        "Swing_Score": 433.9148866486079
+      },
+      {
+        "ts_code": "BK0615.DC",
+        "index_name": "中药概念 (概念)",
+        "ratio_db": 0.080175906138025,
+        "weight_db": 1.041522634544339,
+        "pred_Ratio_Score": 1036.4911242325306,
+        "Ratio_Score": 1036.9806099966886,
+        "pred_Swing_Score": 825.1676911365778,
+        "Swing_Score": 823.0404356041679
+      },
+      {
+        "ts_code": "BK0653.DC",
+        "index_name": "养老概念 (概念)",
+        "ratio_db": 0.065820711061371,
+        "weight_db": 1.050692084122948,
+        "pred_Ratio_Score": 1038.0025661987577,
+        "Ratio_Score": 1035.4711369170884,
+        "pred_Swing_Score": 1005.0098195958633,
+        "Swing_Score": 1005.0161034783504
+      },
+      {
+        "ts_code": "BK1657.DC",
+        "index_name": "病原体防治 (概念)",
+        "ratio_db": 0.064807487656449,
+        "weight_db": 1.05614239070725,
+        "pred_Ratio_Score": 1040.8359792477243,
+        "Ratio_Score": 1038.383599887465,
+        "pred_Swing_Score": 829.0972873909569,
+        "Swing_Score": 830.4517488043484
+      }
+    ]
+  },
+  "raw_snapshot_reaggregation": {
+    "joined_rows": 8701,
+    "joined_dates": 11,
+    "latest_rows": 791,
+    "Ratio": {
+      "checked_rows": 791,
+      "mean_absolute_error": 0.9783318452555938,
+      "max_absolute_error": 105.32457821281037,
+      "same_one_decimal_display": 581,
+      "same_final_rank": 576
+    },
+    "Swing": {
+      "checked_rows": 791,
+      "mean_absolute_error": 1.9075528008117222,
+      "max_absolute_error": 150.16516952571226,
+      "same_one_decimal_display": 318,
+      "same_final_rank": 363
+    },
+    "turnover_within_1_01_yuan": 610,
+    "weight_within_1e_10": 496,
+    "examples": [
+      {
+        "ts_code": "BK0581.DC",
+        "index_name": "智能电网 (概念)",
+        "ratio_db": 0.012878069596386,
+        "weight_db": 1.080961651218729,
+        "pred_Ratio_Score": 684.0868420756208,
+        "Ratio_Score": 789.4114202884311,
+        "pred_Swing_Score": 387.73624445889186,
+        "Swing_Score": 433.9148866486079
+      },
+      {
+        "ts_code": "BK0615.DC",
+        "index_name": "中药概念 (概念)",
+        "ratio_db": 0.079794956978515,
+        "weight_db": 1.041976772408121,
+        "pred_Ratio_Score": 1036.9430681935887,
+        "Ratio_Score": 1036.9806099966886,
+        "pred_Swing_Score": 823.0106390759795,
+        "Swing_Score": 823.0404356041679
+      },
+      {
+        "ts_code": "BK0653.DC",
+        "index_name": "养老概念 (概念)",
+        "ratio_db": 0.065820711061371,
+        "weight_db": 1.050692084122948,
+        "pred_Ratio_Score": 1035.4646626139197,
+        "Ratio_Score": 1035.4711369170884,
+        "pred_Swing_Score": 1005.0098195958633,
+        "Swing_Score": 1005.0161034783504
+      },
+      {
+        "ts_code": "BK1657.DC",
+        "index_name": "病原体防治 (概念)",
+        "ratio_db": 0.064737394636734,
+        "weight_db": 1.05622244732493,
+        "pred_Ratio_Score": 1038.3636136745088,
+        "Ratio_Score": 1038.383599887465,
+        "pred_Swing_Score": 829.160133769571,
+        "Swing_Score": 830.4517488043484
+      }
+    ]
+  }
+}

.trellis/tasks/archive/2026-09/09-21-onechart-score-reconstruction/research/database-validation.md

@@ -0,0 +1,76 @@
+# PostgreSQL 独立核验
+
+## 查询与范围
+
+数据库：`zhixing-system`，PostgreSQL 18.4。本次通过用户授权的 SSH 隧道访问；连接参数强制 `default_transaction_read_only=on`、`statement_timeout=30000`、`lock_timeout=2000`，实测 `transaction_read_only=on`。只执行目录检查和 SELECT/CTE；没有数据库写入。凭据和私钥内容不保存在任务文件中。
+
+读取了以下数据：
+
+- `sector_radar_publication`：为每个交易日选取最近成功发布。
+- `sector_radar_daily_aggregate`：2026-08-28 至 2026-09-21，16 个有成功发布的交易日、16,000 行。9 月 7 日没有成功发布对应的汇总，因此未用别日汇总冒充。
+- `sector_radar_source_snapshot`：保存的原始 `dc_member`、`daily`、`moneyflow_dc`。对 2026-09-07 至 2026-09-21 的 11 日重新聚合，共 11,000 个板块日；SQL 保存在 `raw-reaggregation.sql`。
+- 小范围检查 `sector_radar_stock_fact` 状态，以及四个板块的当日成员快照。
+
+原始快照重聚合按日期和分区选择最近观测，成员使用逐板块分区，股票字段按日期/代码去重；`daily.amount × 1000` 与 `moneyflow_dc.net_amount × 10000` 统一为元。原始重聚合没有沿用产品的沪深 A 股过滤，目的仅是调查网站口径，未改变产品规则。
+
+股票名单、金额数据仅在本机处理，没有传给外部文档查询或其他服务。
+
+## 验证设计
+
+对齐网站实际的日期、板块代码与类型，使用数据库提供的净额与成交额独立计算 r、3/10 日均值及 5 日成交额权重。预测阶段不使用网站的比率、分数或最终排名。
+
+本次试算将数据库聚合成交额向下取整到元，再使用 `r = 净额/(成交额+100)`、`W = log10(1+MA5(成交额))/10`。这是与公开数值关系一致的候选输入口径，不能把该试算本身当作后端代码证据。
+
+计算百分位前特意限制到网站的板块池。数据库有概念 504、行业 496，共 1000 个板块；网站是概念 414、行业 377，共 791 个。即使原始金额相同，在不同 N 和不同成员的池中计算百分位也不能复刻网站分数。
+
+## 最新日结果
+
+2026-09-21 共 791 条对齐记录：
+
+| 数据输入 | 单日评分 MAE | 单日最大误差 | 单日一位小数一致 | 波段评分 MAE | 波段最大误差 | 波段一位小数一致 |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| 当前产品规范化汇总 | 4.6643 | 129.7673 | 204/791 | 4.8030 | 179.7497 | 96/791 |
+| 库中原始快照重新聚合 | 0.9783 | 105.3246 | 581/791 | 1.9076 | 150.1652 | 318/791 |
+
+原始快照重聚合后，610/791 个最新日成交额与从网站金额/比率反求的成交额相差不超过 1.01 元；496/791 个近五日成交额权重达到 `1e-10` 内一致。这为“近五日成交额取对数作为权重”提供了不依赖网站评分预测输入的数据库佐证。
+
+实际例子：
+
+| 板块 | 数据库单日复算 | 网站单日分数 | 数据库波段复算 | 网站波段分数 |
+| --- | ---: | ---: | ---: | ---: |
+| 中药概念 | 1036.9431 | 1036.9806 | 823.0106 | 823.0404 |
+| 养老概念 | 1035.4647 | 1035.4711 | 1005.0098 | 1005.0161 |
+| 病原体防治 | 1038.3636 | 1038.3836 | 829.1601 | 830.4517 |
+| 智能电网 | 684.0868 | 789.4114 | 387.7362 | 433.9149 |
+
+不能只报告平均误差而忽略个别大偏差；数据库原始快照尚未逐板块精确复刻网站输入。本次请求中的评分机制已完成数值还原，但输入采集、板块池和成员版本的完整复刻属于进一步工作。
+
+## 已确认的输入差异
+
+1. **股票范围不同。** 产品 `normalize.py:242` 起要求当前上市、沪深证券，排除北交所/B 股；`facts.py:72` 起只将 `AVAILABLE` 股票累加到板块金额。最新日事实中有 `lifecycle_invalid=435`、`suspended=12`、`available=5209`。改用原始快照后误差显著减少，但没有完全消失。
+2. **板块池不同。** 1000 与 791 的差异已在上述比较中控制；真正独立生产还需要明确网站选择这 791 个板块的规则。
+3. **公开成员表与数据库当日快照不同。** 按股票代码去除交易所后缀再比较：
+
+| 板块 | 库内成员 | 网站公开成员 | 交集 |
+| --- | ---: | ---: | ---: |
+| 智能电网 | 197 | 195 | 190 |
+| 中药概念 | 146 | 145 | 144 |
+| 碳交易 | 142 | 138 | 137 |
+| 超跌股 | 167 | 22 | 7 |
+
+智能电网库内独有 `002851/003043/301236/301669/605336/688187/920222`；网站公开表独有 `001388/002063/300140/600522/920375`。完整差集见 `member-differences.json`。网站这份 `CONSTITUENT_MAP` 不是按交易日分片的历史成员证据，不能据此认定所有历史评分都使用同一份名单；这里证明的是输入版本确实存在差异，不宣称它解释了每一分残差。
+
+4. **上游净额也不完全一致。** 即使成交额近似一致，个股资金流按万元提供的小数精度、板块级净额来源、成员与观测时点仍可能造成净额差异。网站页脚同时提及东财板块日线资金流；本数据库没有对应 `moneyflow_ind_dc` 快照，不能将两种来源强行视为逐值相同。
+5. **9 月 7 日原始资金流不完整。** 该日重聚合样本的资金流覆盖明显不足，不把它用于声称全部 11 日的评分准确度；最终 9 月 21 日的最近十日窗口从 9 月 8 日开始。
+
+第 1–3 项有直接目录、代码和数值证据；第 4 项中的具体上游精度与发布时间机制尚未取得网站构建端证据，因此保留为差异候选原因。
+
+## 保存与复现
+
+- `db-raw-inputs.json.gz`：原始快照重聚合结果。
+- `db-normalized-inputs.json.gz`：当前产品汇总，作为对照。
+- `db-source-metadata.json`：库版本、只读设置及各数据源覆盖范围。
+- `database_reproduce.py`：只读取固定文件，在对齐的排名池中独立计算。
+- `database-validation.json`：精确误差、显示与排名一致数量。
+
+运行 `database_reproduce.py` 不需要数据库凭据或在线连接。所有产物限于当前 Trellis 任务；未修改产品实现、共享规格或生产数据。

.trellis/tasks/archive/2026-09/09-21-onechart-score-reconstruction/research/database_reproduce.py

@@ -0,0 +1,72 @@
+"""使用已读取的 PostgreSQL 金额快照独立算分，无数据库连接和凭据。"""
+
+import gzip
+import json
+
+import numpy as np
+import pandas as pd
+
+from reproduce import ROOT
+
+
+def load(name: str) -> list[dict]:
+    return json.loads(gzip.decompress((ROOT / name).read_bytes()))["rows"]
+
+
+def compare(public: pd.DataFrame, rows: list[dict], normalized: bool) -> dict:
+    """对齐网站实际排名池；评分只使用库内净额和成交额构造。"""
+    source = pd.DataFrame(rows)
+    source["ts_code"] = source["sector_code"]
+    keys = ["trade_date", "ts_code"]
+    if normalized:
+        source["type"] = source["sector_type"].map({"concept": "概念板块", "industry": "行业板块"})
+        keys.append("type")
+    for field in ["net_amount_yuan", "turnover_yuan"]:
+        source[field] = pd.to_numeric(source[field])
+    frame = public.merge(source, on=keys, validate="one_to_one").sort_values(["ts_code", "trade_date"])
+    frame["amount_db"] = np.floor(frame["turnover_yuan"])
+    frame["ratio_db"] = frame["net_amount_yuan"] / (frame["amount_db"] + 100)
+    for field, windows in [("amount_db", [5]), ("ratio_db", [3, 10])]:
+        for window in windows:
+            frame[f"{field}{window}"] = frame.groupby("ts_code")[field].transform(
+                lambda values: values.rolling(window, min_periods=window).mean()
+            )
+    frame["weight_db"] = np.log10(frame["amount_db5"] + 1) / 10
+    groups = frame.groupby(["trade_date", "type"])
+    frame["pred_Ratio_Score"] = 1000 * groups["ratio_db"].rank(pct=True) * frame["weight_db"]
+    frame["pred_Swing_Score"] = (
+        500 * (groups["ratio_db3"].rank(pct=True) + groups["ratio_db10"].rank(pct=True))
+        * frame["weight_db"]
+    )
+    latest = frame[frame["trade_date"].eq("2026-09-21")].copy()
+    result = {"joined_rows": len(frame), "joined_dates": frame["trade_date"].nunique(), "latest_rows": len(latest)}
+    for metric in ["Ratio", "Swing"]:
+        expected, prediction = f"{metric}_Score", f"pred_{metric}_Score"
+        errors = (latest[prediction] - latest[expected]).abs()
+        ranks = latest.groupby("type")[prediction].rank(ascending=False)
+        result[metric] = {
+            "checked_rows": int(errors.notna().sum()), "mean_absolute_error": errors.mean(),
+            "max_absolute_error": errors.max(),
+            "same_one_decimal_display": int(latest[prediction].round(1).eq(latest[expected].round(1)).sum()),
+            "same_final_rank": int(ranks.eq(latest[f"{metric}_RankPos"]).sum()),
+        }
+    # 从网站两个原始字段得到的成交额仅用于末端验证，不参与库内评分预测。
+    target_turnover = latest["Amount_Raw_BN"] * 1e8 / latest["Ratio_Raw_Pct"] - 100
+    result["turnover_within_1_01_yuan"] = int(latest["turnover_yuan"].sub(target_turnover).abs().lt(1.01).sum())
+    website_weight = latest["Ratio_Score"] / (1000 * latest.groupby("type")["Ratio_Raw_Pct"].rank(pct=True))
+    result["weight_within_1e_10"] = int(latest["weight_db"].sub(website_weight).abs().lt(1e-10).sum())
+    examples = latest[latest["ts_code"].isin(["BK0615.DC", "BK0653.DC", "BK1657.DC", "BK0581.DC"])][[
+        "ts_code", "index_name", "ratio_db", "weight_db", "pred_Ratio_Score", "Ratio_Score", "pred_Swing_Score", "Swing_Score"
+    ]]
+    result["examples"] = json.loads(examples.to_json(orient="records", force_ascii=False, double_precision=15))
+    return result
+
+
+if __name__ == "__main__":
+    public = pd.DataFrame(load("public-inputs.json.gz"))
+    result = {
+        "normalized_aggregate": compare(public, load("db-normalized-inputs.json.gz"), True),
+        "raw_snapshot_reaggregation": compare(public, load("db-raw-inputs.json.gz"), False),
+    }
+    (ROOT / "database-validation.json").write_text(json.dumps(result, ensure_ascii=False, indent=2) + "\n")
+    print(json.dumps(result, ensure_ascii=False, indent=2))

.trellis/tasks/archive/2026-09/09-21-onechart-score-reconstruction/research/db-source-metadata.json

@@ -0,0 +1,55 @@
+{
+  "postgres_version": "18.4",
+  "transaction_read_only": "on",
+  "sources": [
+    {
+      "api_name": "daily",
+      "first_date": "2026-08-28",
+      "last_date": "2026-09-21",
+      "snapshot_count": 17,
+      "source_rows": 94336
+    },
+    {
+      "api_name": "dc_index",
+      "first_date": "2026-08-28",
+      "last_date": "2026-09-21",
+      "snapshot_count": 34,
+      "source_rows": 17000
+    },
+    {
+      "api_name": "dc_member",
+      "first_date": "2026-08-28",
+      "last_date": "2026-09-21",
+      "snapshot_count": 17105,
+      "source_rows": 1678901
+    },
+    {
+      "api_name": "moneyflow",
+      "first_date": "2026-09-07",
+      "last_date": "2026-09-21",
+      "snapshot_count": 11,
+      "source_rows": 61054
+    },
+    {
+      "api_name": "moneyflow_dc",
+      "first_date": "2026-08-28",
+      "last_date": "2026-09-21",
+      "snapshot_count": 102,
+      "source_rows": 101285
+    },
+    {
+      "api_name": "suspend_d",
+      "first_date": "2026-08-28",
+      "last_date": "2026-09-21",
+      "snapshot_count": 17,
+      "source_rows": 193
+    },
+    {
+      "api_name": "trade_cal",
+      "first_date": "2026-08-28",
+      "last_date": "2026-09-21",
+      "snapshot_count": 17,
+      "source_rows": 787
+    }
+  ]
+}

.trellis/tasks/archive/2026-09/09-21-onechart-score-reconstruction/research/findings.md

@@ -0,0 +1,137 @@
+# OneChart 波段与单日加权评分还原
+
+研究日期：2026-09-21。这是一次只读算法研究，不包含产品修改或数据库写入。
+
+## 结论与证据等级
+
+已找到一组低自由度、可直接执行的公式，使用网站公开的原始流入率和净额，精确重现 2026-09-04 至 2026-09-21 共 12 个交易日、9,492 条记录的单日评分、波段评分及最终排名。两个评分最大绝对误差均为 `3.410605131648481e-13`，即浮点运算误差。
+
+这是**对观测数据的数值还原**，不是取得网站后端源码。不能据此保证所有历史版本、未来版本及无观测的边界情况都采用相同实现。旧研究未识别出权重的结论不再适用于本次验证区间，但本任务没有修改旧报告或共享规格。
+
+## 公式
+
+对每个板块及日期，定义：
+
+- `r = Ratio_Raw_Pct`，以小数表示的当日流入率，页面显示时乘 100。
+- `F = Amount_Raw_BN × 100000000`，主力净流入金额，单位元。虽然字段包含 `BN`，网站实际展示单位是亿元。
+- `MA_n(x)`：按板块、日期排序后最近 n 条有效观测的简单均值，包含当日；不擅自补齐公开历史中的缺失记录。稳定验证区间每天都公开了 791 个板块，但部分窗口的前置历史仍有日期缺失。
+- `P_t(x)`：**同日、同板块类型**的升序排名百分位，`rank(x)/N`，取值从 `1/N` 到 1；概念和行业各自排名。该排名由原始指标计算，不使用网站最终 `*_RankPct` 作为输入。
+
+### 单日评分
+
+```text
+Ratio_Score = 1000 × P_t(r) × W
+```
+
+### 波段评分
+
+```text
+R3  = MA_3(r)
+R10 = MA_10(r)
+Swing_Score = 1000 × [0.5 × P_t(R3) + 0.5 × P_t(R10)] × W
+```
+
+关键是**先分别求 3 日、10 日流入率均值的横截面排名，再各乘 50%**。如果改成先把两个均值合成波段流入率，再对合成值排名，就会得到不同评分；2026-09-21 该错误方法平均偏差约 62.54 分。
+
+### 页面显示的波段流入率与波段净额
+
+```text
+Swing_Ratio_Val  = 0.5 × MA_3(r) + 0.5 × MA_10(r)
+Swing_Amount_Val = 0.5 × MA_3(Amount_Raw_BN)
+                 + 0.5 × MA_10(Amount_Raw_BN)
+```
+
+所以页面所称“3–10 日多周期协同加权”，在验证数据中可具体化为 **3 日与 10 日两个窗口，各占 50%**。没有证据表明必须引入 4、5、6、7、8、9 日窗口。该波段流入率展开到每日后，最近 3 日每一天占 `13/60 ≈ 21.6667%`，再往前 7 日每一天占 5%；最近三日合计占 65%。这种每日线性展开仅适用于原始波段流入率，不能直接替代带横截面排名的波段评分。
+
+### 成交额权重 W
+
+从公开字段可以精确验证的表达式是：
+
+```text
+V_proxy = F / r
+W = log10(MA_5(V_proxy) - 99) / 10
+```
+
+若定义与网站计算口径对应的成交额 `A = V_proxy - 100`（元），则等价于：
+
+```text
+W = log10(1 + MA_5(A)) / 10
+r = F / (A + 100)
+```
+
+`-99` 由公开数据中的金额/比率关系定位，在 791 个最新日样本中，反求的 5 日成交额与 `MA_5(F/r)` 的差均为约 99 元；使用该修正后，评分误差降至机器精度。单凭公开字段，不能证明后端源码里真的写了“分母加 100 元”，也不能断言这是防零分母常量而不是单位换算产生的等价结果；原始金额、成员和取整口径还需结合数据库核对。
+
+经济含义是用成交活跃程度调节排名得分，采用对数使规模差异的影响较温和。近 5 日平均成交额为 1 亿、10 亿、100 亿、1000 亿元时，W 约为 0.8、0.9、1.0、1.1。因而评分可以超过 1000；它不是限定在 0–1000 的百分制，也不是收益概率。
+
+作为交叉校验，JSON 中虽然未用于单日净额榜默认排序的 `Amount_Score` 也满足：
+
+```text
+Amount_Score = 1000 × P_t(Amount_Raw_BN) × W
+```
+
+## 最新日计算例子
+
+2026-09-21，概念池 N=414，病原体防治（BK1657.DC）：
+
+| 项目 | 数值 |
+| --- | ---: |
+| 单日流入率 | 6.47373795% |
+| 单日流入率原始百分位 | 407/414 = 0.9830917874 |
+| 3 日均值的百分位 | 376/414 = 0.9082125604 |
+| 10 日均值的百分位 | 275/414 = 0.6642512077 |
+| 近 5 日成交额权重 W | 约 1.056243 |
+| 单日评分 | 1038.383599887465 |
+| 波段评分 | 830.4517488043484 |
+| 网站最终单日/波段排名 | 1 / 47 |
+
+```text
+单日 = 1000 × (407/414) × W = 1038.3836 → 页面 1038.4
+波段 = 1000 × [(376/414 + 275/414)/2] × W = 830.4517 → 页面 830.5
+```
+
+它的单日原始流入率并非全池最高，成交额权重加成后，单日综合评分可以排到第一。完整的三板块样例保存在 `worked-examples.json`。
+
+## 验证范围与限制
+
+公开数据总计 23,613 行、30 个交易日，覆盖 2026-08-11 至 2026-09-21。最新日 791 个板块：概念 414、行业 377。
+
+| 验证对象 | 稳定区间样本 | 最大绝对误差 |
+| --- | ---: | ---: |
+| Ratio_Score | 9,492 | 3.41e-13 |
+| Swing_Score | 9,492 | 3.41e-13 |
+| Swing_Ratio_Val | 9,492 | 2.78e-17 |
+| Swing_Amount_Val（亿元） | 9,492 | 5.68e-14 |
+| Amount_Score（交叉校验） | 9,492 | 4.55e-13 |
+
+最终排名按分数降序完全吻合；`RankPct = 100 × (N - RankPos + 1) / N`。金额榜的最终排名依据是原始净额，不是 Amount_Score。
+
+复算过程中仅使用日期、板块代码、类型、原始单日流入率和净额；评分、最终排名只在最后比较时读取。因此没有用答案反过来构造预测输入。主会话执行了 `reproduce.py`；独立代理 `/root/score_formula_audit` 已完成同样输入边界下的核验，结果一致。公开前端取证由 `/root/onechart_public_evidence` 完成。
+
+不能把上述准确度推广到整份 30 日历史：
+
+- 最早 4/9 个观测缺少足够的 5/10 日前置历史，分别无法计算成交额权重/波段窗口。
+- 单日评分在 2026-08-17 至 08-26 有差异，最大约 6.680462 分；8 月 27 日起可计算样本吻合。
+- 波段评分在 2026-08-24 至 09-03 有差异，最大约 261.703574 分。8 月 27 日公开板块只有 707 条，部分后续窗口的输入不全；早期还存在板块集合或数据修订差异，尚未逐项确认原因。
+- 稳定验证区间没有原始比率或分数并列，不能确定后端的并列排名规则。脚本选用 `average` 仅作为明确的复算约定。
+- 全量没有 `r=0`，不能由本样本识别零净流入、零成交额、极低流动性和无历史板块的所有边界策略。
+
+## 公开实现证据
+
+- [首页](https://onechartlab.com/) 只读取 `${activeTab}_Score`，提示“后端特征算法算出的综合加权值”；本次缓存 `index.html:800–805`。前端没有公开评分构造函数。
+- 首页 `index.html:1032` 说明“3-10 个交易日多周期协同加权”；具体 50%/50% 来自数值检验，而非这句话本身。
+- 首页 `index.html:1253–1257` 按板块类型过滤；`1292–1314` 指定 Swing/Ratio 默认按各自分数排序，并用最终 RankPct 切前后 10%。
+- [radar_manifest.json](https://onechartlab.com/radar_manifest.json) 列出日期分片；已保存本次 manifest。
+- [完整公开 JSON](https://onechartlab.com/radar_data_latest.json) 和 [2026-09-21 分片](https://onechartlab.com/radar_data/dates/2026-09-21.22531a461a8b.json) 给出数值证据。`public-inputs.json.gz` 保存了所需字段和原始文件 SHA-256，避免未来网站更新导致样本改变。
+- [Tushare daily](https://tushare.pro/document/2?doc_id=27) 的 amount 单位为千元；[moneyflow_dc](https://tushare.pro/document/2?doc_id=349) 的 net_amount 单位为万元。数据库重聚合分别乘 1000 和 10000 后统一成元。
+
+## 复现
+
+在仓库根目录运行：
+
+```bash
+zhixing-server/.venv/bin/python .trellis/tasks/archive/2026-09/09-21-onechart-score-reconstruction/research/reproduce.py
+```
+
+脚本读取固定样本，不需要网络或数据库凭据，输出 `public-validation.json`。本次使用 Python 3.12.11、pandas 3.0.5、NumPy 2.5.1。
+
+数据库的独立核对另见本目录 `database-validation.md`；研究 SQL 和结果均与生产代码隔离。

.trellis/tasks/archive/2026-09/09-21-onechart-score-reconstruction/research/member-differences.json

@@ -0,0 +1,246 @@
+[
+  {
+    "code": "BK0581.DC",
+    "name": "智能电网",
+    "db_count": 197,
+    "site_count": 195,
+    "intersection_count": 190,
+    "db_only": [
+      "002851",
+      "003043",
+      "301236",
+      "301669",
+      "605336",
+      "688187",
+      "920222"
+    ],
+    "site_only": [
+      "001388",
+      "002063",
+      "300140",
+      "600522",
+      "920375"
+    ],
+    "observed_at": "2026-09-21 10:40:57.972405+00:00"
+  },
+  {
+    "code": "BK0615.DC",
+    "name": "中药概念",
+    "db_count": 146,
+    "site_count": 145,
+    "intersection_count": 144,
+    "db_only": [
+      "000626",
+      "920367"
+    ],
+    "site_only": [
+      "300391"
+    ],
+    "observed_at": "2026-09-21 10:41:08.518051+00:00"
+  },
+  {
+    "code": "BK0966.DC",
+    "name": "碳交易",
+    "db_count": 142,
+    "site_count": 138,
+    "intersection_count": 137,
+    "db_only": [
+      "000875",
+      "002734",
+      "600389",
+      "601678",
+      "603612"
+    ],
+    "site_only": [
+      "600028"
+    ],
+    "observed_at": "2026-09-21 10:43:25.392556+00:00"
+  },
+  {
+    "code": "BK1671.DC",
+    "name": "超跌股",
+    "db_count": 167,
+    "site_count": 22,
+    "intersection_count": 7,
+    "db_only": [
+      "000002",
+      "000010",
+      "000016",
+      "000639",
+      "000677",
+      "002104",
+      "002217",
+      "002227",
+      "002368",
+      "002514",
+      "002542",
+      "002547",
+      "002657",
+      "002691",
+      "002731",
+      "002869",
+      "002891",
+      "300045",
+      "300068",
+      "300100",
+      "300245",
+      "300255",
+      "300290",
+      "300352",
+      "300396",
+      "300430",
+      "300465",
+      "300484",
+      "300492",
+      "300530",
+      "300539",
+      "300584",
+      "300652",
+      "300663",
+      "300682",
+      "300703",
+      "300723",
+      "300779",
+      "300844",
+      "300879",
+      "300896",
+      "300918",
+      "300940",
+      "300995",
+      "301000",
+      "301052",
+      "301076",
+      "301139",
+      "301325",
+      "301498",
+      "301590",
+      "301601",
+      "301622",
+      "301632",
+      "600053",
+      "600180",
+      "600325",
+      "600363",
+      "600418",
+      "600491",
+      "600530",
+      "600702",
+      "600745",
+      "601127",
+      "601865",
+      "601929",
+      "603008",
+      "603189",
+      "603200",
+      "603300",
+      "603359",
+      "603370",
+      "603382",
+      "603392",
+      "603567",
+      "603630",
+      "603718",
+      "603767",
+      "603815",
+      "603848",
+      "605499",
+      "688013",
+      "688066",
+      "688068",
+      "688089",
+      "688121",
+      "688166",
+      "688189",
+      "688201",
+      "688303",
+      "688408",
+      "688496",
+      "688499",
+      "688500",
+      "688567",
+      "688573",
+      "688577",
+      "688588",
+      "688631",
+      "688639",
+      "688648",
+      "688658",
+      "688775",
+      "920001",
+      "920005",
+      "920007",
+      "920056",
+      "920061",
+      "920075",
+      "920090",
+      "920101",
+      "920106",
+      "920108",
+      "920112",
+      "920145",
+      "920146",
+      "920184",
+      "920237",
+      "920239",
+      "920247",
+      "920252",
+      "920263",
+      "920271",
+      "920273",
+      "920274",
+      "920346",
+      "920351",
+      "920375",
+      "920392",
+      "920395",
+      "920414",
+      "920429",
+      "920454",
+      "920469",
+      "920505",
+      "920508",
+      "920522",
+      "920523",
+      "920533",
+      "920578",
+      "920579",
+      "920627",
+      "920634",
+      "920689",
+      "920693",
+      "920719",
+      "920720",
+      "920770",
+      "920781",
+      "920807",
+      "920896",
+      "920906",
+      "920914",
+      "920925",
+      "920926",
+      "920932",
+      "920942",
+      "920982",
+      "920985",
+      "920992"
+    ],
+    "site_only": [
+      "000004",
+      "000056",
+      "000638",
+      "002630",
+      "300081",
+      "300344",
+      "300561",
+      "600355",
+      "600599",
+      "600696",
+      "603369",
+      "605199",
+      "688287",
+      "920130",
+      "920305"
+    ],
+    "observed_at": "2026-09-21 10:50:20.423741+00:00"
+  }
+]

.trellis/tasks/archive/2026-09/09-21-onechart-score-reconstruction/research/public-validation.json

@@ -0,0 +1,116 @@
+{
+  "rows": 23613,
+  "dates": 30,
+  "windows": {
+    "all_available": {
+      "rows": 23613,
+      "dates": 30,
+      "Ratio_Score": {
+        "checked_rows": 20449,
+        "mean_absolute_error": 0.18366711208184938,
+        "max_absolute_error": 6.680461750893414,
+        "errors_above_1e-8": 1651
+      },
+      "Swing_Score": {
+        "checked_rows": 16494,
+        "mean_absolute_error": 0.5097113919412869,
+        "max_absolute_error": 261.7035740929656,
+        "errors_above_1e-8": 3199
+      },
+      "Amount_Score": {
+        "checked_rows": 20449,
+        "mean_absolute_error": 0.1882733317113178,
+        "max_absolute_error": 7.649258428013809,
+        "errors_above_1e-8": 1651
+      },
+      "Swing_Ratio_Val": {
+        "checked_rows": 16494,
+        "mean_absolute_error": 6.7217831480409905e-06,
+        "max_absolute_error": 0.012044989384502386,
+        "errors_above_1e-8": 28
+      },
+      "Swing_Amount_Val": {
+        "checked_rows": 16494,
+        "mean_absolute_error": 0.008108515254276354,
+        "max_absolute_error": 24.526995094,
+        "errors_above_1e-8": 28
+      }
+    },
+    "2026-09-04_to_2026-09-21": {
+      "rows": 9492,
+      "dates": 12,
+      "Ratio_Score": {
+        "checked_rows": 9492,
+        "mean_absolute_error": 3.2767252412841164e-14,
+        "max_absolute_error": 3.410605131648481e-13,
+        "errors_above_1e-8": 0
+      },
+      "Swing_Score": {
+        "checked_rows": 9492,
+        "mean_absolute_error": 3.441106555949961e-14,
+        "max_absolute_error": 3.410605131648481e-13,
+        "errors_above_1e-8": 0
+      },
+      "Amount_Score": {
+        "checked_rows": 9492,
+        "mean_absolute_error": 3.245420975553957e-14,
+        "max_absolute_error": 4.547473508864641e-13,
+        "errors_above_1e-8": 0
+      },
+      "Swing_Ratio_Val": {
+        "checked_rows": 9492,
+        "mean_absolute_error": 4.942276978457954e-18,
+        "max_absolute_error": 2.7755575615628914e-17,
+        "errors_above_1e-8": 0
+      },
+      "Swing_Amount_Val": {
+        "checked_rows": 9492,
+        "mean_absolute_error": 2.053051893003829e-15,
+        "max_absolute_error": 5.684341886080802e-14,
+        "errors_above_1e-8": 0
+      },
+      "Ratio_ranking": {
+        "rank_position_mismatches": 0,
+        "rank_percentile_max_error": 1.4210854715202004e-14
+      },
+      "Swing_ranking": {
+        "rank_position_mismatches": 0,
+        "rank_percentile_max_error": 1.4210854715202004e-14
+      }
+    },
+    "2026-09-14_to_2026-09-21": {
+      "rows": 4746,
+      "dates": 6,
+      "Ratio_Score": {
+        "checked_rows": 4746,
+        "mean_absolute_error": 3.302167267444722e-14,
+        "max_absolute_error": 3.410605131648481e-13,
+        "errors_above_1e-8": 0
+      },
+      "Swing_Score": {
+        "checked_rows": 4746,
+        "mean_absolute_error": 3.4959814225990485e-14,
+        "max_absolute_error": 3.410605131648481e-13,
+        "errors_above_1e-8": 0
+      },
+      "Amount_Score": {
+        "checked_rows": 4746,
+        "mean_absolute_error": 3.260761983972608e-14,
+        "max_absolute_error": 4.547473508864641e-13,
+        "errors_above_1e-8": 0
+      },
+      "Swing_Ratio_Val": {
+        "checked_rows": 4746,
+        "mean_absolute_error": 4.952800461538844e-18,
+        "max_absolute_error": 2.7755575615628914e-17,
+        "errors_above_1e-8": 0
+      },
+      "Swing_Amount_Val": {
+        "checked_rows": 4746,
+        "mean_absolute_error": 2.056700338399156e-15,
+        "max_absolute_error": 5.684341886080802e-14,
+        "errors_above_1e-8": 0
+      }
+    }
+  }
+}

.trellis/tasks/archive/2026-09/09-21-onechart-score-reconstruction/research/radar_manifest.json

@@ -0,0 +1 @@
+{"AVAILABLE_DATES":["2026-08-11","2026-08-12","2026-08-13","2026-08-14","2026-08-17","2026-08-18","2026-08-19","2026-08-20","2026-08-21","2026-08-24","2026-08-25","2026-08-26","2026-08-27","2026-08-28","2026-08-31","2026-09-01","2026-09-02","2026-09-03","2026-09-04","2026-09-07","2026-09-08","2026-09-09","2026-09-10","2026-09-11","2026-09-14","2026-09-15","2026-09-16","2026-09-17","2026-09-18","2026-09-21"],"DATA_SOURCE":"","LATEST_DATE":"2026-09-21","files":{"constituents":"radar_data/constituents.25ffae2b8f53.json","dates":{"2026-08-11":"radar_data/dates/2026-08-11.3ed082fdf5aa.json","2026-08-12":"radar_data/dates/2026-08-12.a61e39835037.json","2026-08-13":"radar_data/dates/2026-08-13.db6f36c2dd06.json","2026-08-14":"radar_data/dates/2026-08-14.fb36a77c6ae4.json","2026-08-17":"radar_data/dates/2026-08-17.d69d703faef6.json","2026-08-18":"radar_data/dates/2026-08-18.2c339eebabd6.json","2026-08-19":"radar_data/dates/2026-08-19.fca1cdf24170.json","2026-08-20":"radar_data/dates/2026-08-20.88ff543739cc.json","2026-08-21":"radar_data/dates/2026-08-21.a08c301a8dd7.json","2026-08-24":"radar_data/dates/2026-08-24.9135129011a3.json","2026-08-25":"radar_data/dates/2026-08-25.9393e22d8754.json","2026-08-26":"radar_data/dates/2026-08-26.f49c721846fb.json","2026-08-27":"radar_data/dates/2026-08-27.2dc5f5627eeb.json","2026-08-28":"radar_data/dates/2026-08-28.c92100ea9ae1.json","2026-08-31":"radar_data/dates/2026-08-31.c094ac3098c9.json","2026-09-01":"radar_data/dates/2026-09-01.e6253d4364f6.json","2026-09-02":"radar_data/dates/2026-09-02.1e4a8e6102d5.json","2026-09-03":"radar_data/dates/2026-09-03.ec356ce27a57.json","2026-09-04":"radar_data/dates/2026-09-04.deaf468364a2.json","2026-09-07":"radar_data/dates/2026-09-07.874c2aaa1925.json","2026-09-08":"radar_data/dates/2026-09-08.f93f7b9b2eab.json","2026-09-09":"radar_data/dates/2026-09-09.7a9919c800d9.json","2026-09-10":"radar_data/dates/2026-09-10.29e5d3c66a03.json","2026-09-11":"radar_data/dates/2026-09-11.738e1fec6654.json","2026-09-14":"radar_data/dates/2026-09-14.6b21a73a38f6.json","2026-09-15":"radar_data/dates/2026-09-15.9d5afec9a676.json","2026-09-16":"radar_data/dates/2026-09-16.48d01087bfbd.json","2026-09-17":"radar_data/dates/2026-09-17.04d53b204a8f.json","2026-09-18":"radar_data/dates/2026-09-18.b7a298aedf8d.json","2026-09-21":"radar_data/dates/2026-09-21.22531a461a8b.json"},"rank_history":"radar_data/rank_history.1d389cbfa3e1.json"},"schema_version":1,"version":"7a4fc78a8366"}

.trellis/tasks/archive/2026-09/09-21-onechart-score-reconstruction/research/raw-reaggregation.sql

@@ -0,0 +1 @@
+WITH s AS MATERIALIZED (SELECT DISTINCT ON (api_name,target_trade_date,partition_key) api_name,target_trade_date,partition_key,payload,observed_at FROM sector_radar_source_snapshot WHERE target_trade_date BETWEEN '2026-09-07' AND '2026-09-21' AND api_name IN ('dc_member','daily','moneyflow_dc') ORDER BY api_name,target_trade_date,partition_key,observed_at DESC), d AS (SELECT DISTINCT ON (target_trade_date,e->>'ts_code') target_trade_date,e->>'ts_code' AS code,(e->>'amount')::numeric*1000 AS amount FROM s CROSS JOIN LATERAL jsonb_array_elements(payload) e WHERE api_name='daily' ORDER BY target_trade_date,e->>'ts_code',observed_at DESC), f AS (SELECT DISTINCT ON (target_trade_date,e->>'ts_code') target_trade_date,e->>'ts_code' AS code,(e->>'net_amount')::numeric*10000 AS net FROM s CROSS JOIN LATERAL jsonb_array_elements(payload) e WHERE api_name='moneyflow_dc' ORDER BY target_trade_date,e->>'ts_code',observed_at DESC), m AS (SELECT DISTINCT target_trade_date,e->>'ts_code' AS sector,e->>'con_code' AS code FROM s CROSS JOIN LATERAL jsonb_array_elements(payload) e WHERE api_name='dc_member' AND partition_key<>'all') SELECT m.target_trade_date AS trade_date,m.sector AS sector_code,count(*) AS member_count,count(d.amount) AS daily_count,count(f.net) AS flow_count,sum(d.amount) AS turnover_yuan,sum(f.net) AS net_amount_yuan,sum(d.amount) FILTER (WHERE m.code LIKE '%.BJ') AS bj_turnover_yuan FROM m LEFT JOIN d ON d.target_trade_date=m.target_trade_date AND d.code=m.code LEFT JOIN f ON f.target_trade_date=m.target_trade_date AND f.code=m.code GROUP BY m.target_trade_date,m.sector ORDER BY m.target_trade_date,m.sector

.trellis/tasks/archive/2026-09/09-21-onechart-score-reconstruction/research/reproduce.py

@@ -0,0 +1,97 @@
+"""从固定公开输入复算 OneChart 指标；预测阶段不使用网站评分或排名。"""
+
+from __future__ import annotations
+
+import gzip
+import json
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+
+ROOT = Path(__file__).resolve().parent
+
+
+def calculate(rows: list[dict]) -> pd.DataFrame:
+    """按板块有观测的历史记录计算；预热不足保留 NaN，不填补未知输入。"""
+    frame = pd.DataFrame(rows).sort_values(["ts_code", "trade_date"])
+    if frame.duplicated(["trade_date", "type", "ts_code"]).any():
+        raise ValueError("公开输入存在重复主键")
+    if frame["Ratio_Raw_Pct"].eq(0).any():
+        raise ValueError("零流入率无法通过金额/比率反求成交额；需要原始成交额")
+
+    frame["turnover_proxy_yuan"] = (
+        frame["Amount_Raw_BN"] * 1e8 / frame["Ratio_Raw_Pct"]
+    )
+    for field in ["Ratio_Raw_Pct", "Amount_Raw_BN", "turnover_proxy_yuan"]:
+        for window in [3, 5, 10]:
+            frame[f"{field}_ma{window}"] = frame.groupby("ts_code")[field].transform(
+                lambda series: series.rolling(window, min_periods=window).mean()
+            )
+
+    # -99 是公开金额/比率所能直接验证的代数修正，不把它当成原始成交额。
+    frame["liquidity_weight"] = (
+        np.log10(frame["turnover_proxy_yuan_ma5"] - 99) / 10
+    )
+    groups = frame.groupby(["trade_date", "type"])
+    for field in ["Ratio_Raw_Pct", "Ratio_Raw_Pct_ma3", "Ratio_Raw_Pct_ma10", "Amount_Raw_BN"]:
+        frame[f"{field}_percentile"] = groups[field].rank(method="average", pct=True)
+
+    frame["pred_Ratio_Score"] = (
+        1000 * frame["Ratio_Raw_Pct_percentile"] * frame["liquidity_weight"]
+    )
+    frame["pred_Swing_Score"] = (
+        1000
+        * 0.5
+        * (frame["Ratio_Raw_Pct_ma3_percentile"] + frame["Ratio_Raw_Pct_ma10_percentile"])
+        * frame["liquidity_weight"]
+    )
+    frame["pred_Amount_Score"] = (
+        1000 * frame["Amount_Raw_BN_percentile"] * frame["liquidity_weight"]
+    )
+    frame["pred_Swing_Ratio_Val"] = (
+        0.5 * (frame["Ratio_Raw_Pct_ma3"] + frame["Ratio_Raw_Pct_ma10"])
+    )
+    frame["pred_Swing_Amount_Val"] = (
+        0.5 * (frame["Amount_Raw_BN_ma3"] + frame["Amount_Raw_BN_ma10"])
+    )
+    return frame
+
+
+def validate(frame: pd.DataFrame) -> dict:
+    """比较固定公式的预测与网站输出，报告预热、全历史与稳定覆盖窗口。"""
+    metrics = ["Ratio_Score", "Swing_Score", "Amount_Score", "Swing_Ratio_Val", "Swing_Amount_Val"]
+    report = {"rows": len(frame), "dates": frame["trade_date"].nunique(), "windows": {}}
+    for name, subset in [
+        ("all_available", frame),
+        ("2026-09-04_to_2026-09-21", frame[frame["trade_date"].ge("2026-09-04")]),
+        ("2026-09-14_to_2026-09-21", frame[frame["trade_date"].ge("2026-09-14")]),
+    ]:
+        result = {"rows": len(subset), "dates": subset["trade_date"].nunique()}
+        for metric in metrics:
+            errors = (subset[metric] - subset[f"pred_{metric}"]).abs().dropna()
+            result[metric] = {
+                "checked_rows": len(errors), "mean_absolute_error": errors.mean(),
+                "max_absolute_error": errors.max(), "errors_above_1e-8": int(errors.gt(1e-8).sum()),
+            }
+        if name == "2026-09-04_to_2026-09-21":
+            groups = subset.groupby(["trade_date", "type"])
+            count = groups["ts_code"].transform("size")
+            for metric in ["Ratio", "Swing"]:
+                ranks = groups[f"pred_{metric}_Score"].rank(ascending=False)
+                percentiles = 100 * (count - ranks + 1) / count
+                result[f"{metric}_ranking"] = {
+                    "rank_position_mismatches": int(ranks.ne(subset[f"{metric}_RankPos"]).sum()),
+                    "rank_percentile_max_error": percentiles.sub(subset[f"{metric}_RankPct"]).abs().max(),
+                }
+        report["windows"][name] = result
+    return report
+
+
+if __name__ == "__main__":
+    fixture = json.loads(gzip.decompress((ROOT / "public-inputs.json.gz").read_bytes()))
+    calculated = calculate(fixture["rows"])
+    result = validate(calculated)
+    (ROOT / "public-validation.json").write_text(json.dumps(result, ensure_ascii=False, indent=2) + "\n")
+    print(json.dumps(result, ensure_ascii=False, indent=2))

.trellis/tasks/archive/2026-09/09-21-onechart-score-reconstruction/research/worked-examples.json

@@ -0,0 +1,59 @@
+[
+  {
+    "index_name":"中药概念 (概念)",
+    "ts_code":"BK0615.DC",
+    "type":"概念板块",
+    "Ratio_Raw_Pct":0.079794960955587,
+    "Ratio_Raw_Pct_ma3":0.033754406576305,
+    "Ratio_Raw_Pct_ma10":-0.005866010935792,
+    "Ratio_Raw_Pct_percentile":0.995169082125604,
+    "Ratio_Raw_Pct_ma3_percentile":0.929951690821256,
+    "Ratio_Raw_Pct_ma10_percentile":0.64975845410628,
+    "turnover_proxy_yuan_ma5":26311461138.200000762939453,
+    "liquidity_weight":1.042014496452983,
+    "pred_Ratio_Score":1036.9806099966886,
+    "Ratio_Score":1036.9806099966886,
+    "pred_Swing_Score":823.040435604167897,
+    "Swing_Score":823.040435604167897,
+    "Ratio_RankPos":2,
+    "Swing_RankPos":49
+  },
+  {
+    "index_name":"养老概念 (概念)",
+    "ts_code":"BK0653.DC",
+    "type":"概念板块",
+    "Ratio_Raw_Pct":0.065820703429991,
+    "Ratio_Raw_Pct_ma3":0.037193483577325,
+    "Ratio_Raw_Pct_ma10":0.006875783666745,
+    "Ratio_Raw_Pct_percentile":0.985507246376812,
+    "Ratio_Raw_Pct_ma3_percentile":0.949275362318841,
+    "Ratio_Raw_Pct_ma10_percentile":0.963768115942029,
+    "turnover_proxy_yuan_ma5":32135609228.599998474121094,
+    "liquidity_weight":1.050698653636457,
+    "pred_Ratio_Score":1035.471136917088188,
+    "Ratio_Score":1035.471136917088415,
+    "pred_Swing_Score":1005.016103478350374,
+    "Swing_Score":1005.016103478350374,
+    "Ratio_RankPos":3,
+    "Swing_RankPos":2
+  },
+  {
+    "index_name":"病原体防治 (概念)",
+    "ts_code":"BK1657.DC",
+    "type":"概念板块",
+    "Ratio_Raw_Pct":0.064737379547795,
+    "Ratio_Raw_Pct_ma3":0.029828519014713,
+    "Ratio_Raw_Pct_ma10":-0.005451455299003,
+    "Ratio_Raw_Pct_percentile":0.983091787439614,
+    "Ratio_Raw_Pct_ma3_percentile":0.908212560386474,
+    "Ratio_Raw_Pct_ma10_percentile":0.664251207729468,
+    "turnover_proxy_yuan_ma5":36511340146.0,
+    "liquidity_weight":1.056242777281107,
+    "pred_Ratio_Score":1038.383599887464925,
+    "Ratio_Score":1038.383599887464925,
+    "pred_Swing_Score":830.451748804348426,
+    "Swing_Score":830.451748804348426,
+    "Ratio_RankPos":1,
+    "Swing_RankPos":47
+  }
+]

.trellis/tasks/archive/2026-09/09-21-onechart-score-reconstruction/task.json

@@ -0,0 +1,33 @@
+{
+  "id": "onechart-score-reconstruction",
+  "name": "onechart-score-reconstruction",
+  "title": "还原 OneChart 波段与单日资金流评分",
+  "description": "只读数值还原 OneChart 单日与波段资金评分；12 日 9492 条公开样本精确重现，并完成 PostgreSQL 原始快照对照。",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "yuxuanhui",
+  "assignee": "yuxuanhui",
+  "createdAt": "2026-09-21",
+  "completedAt": "2026-09-21",
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "研究完成。没有实施产品修改、修改数据库、共享规格推广或提交。输入版本与成员口径差异详见 research/database-validation.md。",
+  "meta": {
+    "work_kind": "read_only_research",
+    "public_validation_rows": 9492,
+    "public_score_max_abs_error": 3.410605131648481e-13,
+    "database_latest_rows": 791,
+    "database_ratio_mae": 0.9783318452555938,
+    "database_swing_mae": 1.9075528008117222
+  }
+}

.trellis/tasks/archive/2026-09/09-21-radar-weighted-score-rank-change/check.jsonl

@@ -0,0 +1,9 @@
+{"file": ".trellis/spec/backend/index.md", "reason": "后端包边界与必需检查"}
+{"file": ".trellis/spec/backend/tushare-listed-stock-universe.md", "reason": "继续遵守当前上市证券母集，不能为对齐网站擅自改变范围"}
+{"file": ".trellis/spec/backend/http-api-contracts.md", "reason": "评分与三指标变化字段的端到端契约"}
+{"file": ".trellis/spec/frontend/component-guidelines.md", "reason": "镜像榜单、控件与可访问性"}
+{"file": ".trellis/spec/frontend/type-safety.md", "reason": "API nullable 字段与严格解析"}
+{"file": ".trellis/tasks/archive/2026-09/09-21-radar-weighted-score-rank-change/research/formula-evidence.md", "reason": "已验证的评分结构及数值证据边界"}
+{"file": ".trellis/tasks/archive/2026-09/09-21-radar-weighted-score-rank-change/research/code-evidence.md", "reason": "现有实现定位与需保持的版本/持久化行为"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "后端 Ruff、Pyright、pytest 和持久化检查"}
+{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "前端格式、lint、类型、行为与构建检查"}

.trellis/tasks/archive/2026-09/09-21-radar-weighted-score-rank-change/design.md

@@ -0,0 +1,48 @@
+# 设计：加权评分与排名变化
+
+## 计算与领域边界
+
+评分留在 sector_radar 领域/发布阶段，不在 React 中根据当前页数据计算百分位。当前每板块 MetricStrategy 只能得到该板块历史，因此新增全池评分步骤，接收同一目标日所有板块的原始特征，按日期、类型分池计算。
+
+新版本拟为 `zhixing_ratio_weighted_v2` 和 `zhixing_swing_weighted_v2`。设 A 为现有聚合成交额元、F 为聚合主力净额元；按前置研究的可复算输入约定取 `r=F/(A+100)`，A<=0 或输入未知时不制造比率。W=`log10(1+MA5(A))/10`；P 为原始指标升序平均名次/N。
+
+```text
+单日原值 = r
+单日评分 = 1000 * P(r) * W
+波段原值 = .5*MA3(r) + .5*MA10(r)
+波段评分 = 1000*(.5*P(MA3(r)) + .5*P(MA10(r)))*W
+```
+
+使用 Decimal 计算金额、比率和对数；仅在输出展示时保留 1 位小数。P 的并列值采用平均名次，最终分数并列沿用 sector_code 升序作为稳定破同分规则。原始值与 weighted_score 分离；窗口不足时保留可确定的原始值，评分和对应名次为空，不以原始值替代缺失评分。质量状态和覆盖率继续传播。
+
+新版本使用保存的交易日历确定窗口与对比日期，缺少某个应有交易日输入时保留未知；不得悄悄以更早成功发布替代缺失交易日。第一个可复算日期受库内真实历史覆盖限制。
+
+## 排名、历史与版本
+
+`rank_metric_observations` 对金额继续使用原始金额，对新版本单日/波段使用 weighted_score。上下普通榜筛选使用最终百分位；底榜排序也须与评分键一致。排名变化在同版本最终名次上计算 `past_rank-current_rank`；取 ceil(有效排名池大小×10%)，历史不可比者不进入变化候选。
+
+一行排名变化响应提供所选基准兼容字段 rank_change，以及 amount/ratio/swing 三个变化值，供中心主列和两侧辅助列复用。查询选出的前后榜由所选基准确定；点击辅助列只改变该侧当前候选排列。字段均允许 null。
+
+旧发布按其实际 metric_versions 解析定义与历史，不用新版本常量把旧数据过滤成空，也不比较 v1 与 v2 名次。榜单、详情和历史折线共享版本解析与排名事实。首次切换期间旧发布评分显示“—”；历史重算完成后，同日最新成功发布提供新评分。
+
+## 持久化与历史重算
+
+新增 Alembic migration，为 `sector_radar_ranking` 增加 nullable NUMERIC weighted_score，保持 metric_value 原义。同步所有 INSERT、SELECT、序列化和反序列化；内存仓库保持同等语义。
+
+发布构建使用统一评分服务，版本参与 input_hash。增加离线重算入口，仅使用已落库聚合事实和原发布的来源关联，不初始化 Tushare 客户端。按交易日先后创建新派生发布，保留旧发布与原始快照；固定源 publication IDs 避免重算期间新发布改变本轮输入。复用现有按日锁、事务和 last-good 规则，重算幂等键包含源发布身份/输入指纹和新策略版本。
+
+重算时必须复制/关联原聚合的 pct_change、leading_code 及来源组，使新发布的详情仍可读取；不能只写 ranking 而产生空详情。适配器需要提供 publication 精确的 aggregate records 与来源读取，避免现有 history 方法丢失这些元信息。
+
+生产数据库的迁移和重算是独立运行步骤；在本地代码和验证准备完成前不执行外部写入。回退可恢复旧代码版本并重新选择保留的旧发布；nullable 新列本身保持兼容。
+
+## HTTP 与前端
+
+- 在榜单行和必要详情摘要中扩展 weighted_score；排名变化补充三指标变化映射与对比日期信息，同步 Pydantic、TypeScript、解析器和 query 测试。
+- 单日/波段左右增加评分列，1 位小数、缺失“—”；其余原始百分比保留独立展示。
+- rank_change 使用独立次行，左侧三枚排序基准按钮，右侧近 1–5 日下拉。默认波段率和 1 日，仅在 URL 没有显式值时采用默认。
+- 标题为排名飙升榜/排名暴跌榜，中央为“{基准全名}排名变化”；主列显示所选指标变化，辅助列显示另外两项，增加涨跌幅。
+- 延续现有主题、表格镜像、板块详情入口和响应式横向滚动；不添加未要求的全局导出、搜索改版或主题重制。
+
+## 主要风险
+
+新算法会改变单日/波段榜及历史名次；必须依靠新版本与离线重算切换，不能给旧名次套新评分。知行的 1000 个板块及按日成员与 OneChart 的 791 板块输入不同，算法结构一致不保证逐值一致。原站并列、缺失与极低成交额策略未完全公开，本系统明确采用上述确定规则。

.trellis/tasks/archive/2026-09/09-21-radar-weighted-score-rank-change/implement.jsonl

@@ -0,0 +1,7 @@
+{"file": ".trellis/spec/backend/index.md", "reason": "后端包边界与必需检查"}
+{"file": ".trellis/spec/backend/tushare-listed-stock-universe.md", "reason": "继续遵守当前上市证券母集，不能为对齐网站擅自改变范围"}
+{"file": ".trellis/spec/backend/http-api-contracts.md", "reason": "评分与三指标变化字段的端到端契约"}
+{"file": ".trellis/spec/frontend/component-guidelines.md", "reason": "镜像榜单、控件与可访问性"}
+{"file": ".trellis/spec/frontend/type-safety.md", "reason": "API nullable 字段与严格解析"}
+{"file": ".trellis/tasks/archive/2026-09/09-21-radar-weighted-score-rank-change/research/formula-evidence.md", "reason": "已验证的评分结构及数值证据边界"}
+{"file": ".trellis/tasks/archive/2026-09/09-21-radar-weighted-score-rank-change/research/code-evidence.md", "reason": "现有实现定位与需保持的版本/持久化行为"}

.trellis/tasks/archive/2026-09/09-21-radar-weighted-score-rank-change/implement.md

@@ -0,0 +1,39 @@
+# 执行计划
+
+状态：本地实现与范围内验收完成；全仓既有失败已在实施前版本复现。详细结果及生产应用命令见 `validation.md`。
+
+1. 完整阅读要修改的文件；确认已保存的评分研究、接口契约、版本及缺失语义。核对需要使用的 Alembic/Pydantic 等当前版本与官方文档。
+2. 实现版本化评分特征和全池计算，分离 raw value/score；更换单日/波段排序键，补独立数值样例、并列、未来数据排除及缺失窗口测试。
+3. 新增 nullable score 列迁移；同步 PostgreSQL/内存仓库所有读写与 historical ranking 查询。补充真实数据库往返、旧行 NULL 和事务失败测试。
+4. 接入发布构建与 input_hash；实现不访问 Tushare 的历史重算入口、新旧版本解析及严格对比日期。验证幂等、旧发布保留、失败 last-good 与详情来源完整。
+5. 扩展榜单/详情 HTTP 输出和前端类型解析，支持评分、三指标变化值及对比日期；覆盖不匹配版本与缺失历史。
+6. 单日/波段表格添加评分列与侧内排序；按截图调整排名变化次级控制行、双榜标题、中央标题、涨跌幅和两项辅助变化列，保持 URL/查询联动。
+7. 执行领域、发布、读取、HTTP、仓库、前端 API 和页面行为测试；用本地测试数据库验证迁移和离线重算，避免使用用户生产库进行测试写入。
+8. 完成后端 Ruff/Pyright/pytest 与前端格式、lint、typecheck、Vitest/build。浏览器实际检查三基准、1–5 日、空历史、评分列和窄屏；保存必要截图和验证结果。
+9. 检查 diff 范围、已有用户改动和未验证事项；交付本地成果及明确的迁移/重算命令，不自行提交、部署或写入生产库。
+
+## 验证命令
+
+```bash
+cd zhixing-server
+uv run ruff format --check .
+uv run ruff check .
+uv run pyright
+uv run pytest
+```
+
+```bash
+cd zhixing-web
+pnpm check
+pnpm build
+```
+
+实现期间先执行相关测试，最后执行项目规定完整检查；通过后仅在新改动或未解决问题需要时重复。
+
+## 高风险核验点
+
+- P 必须来自完整同类池，不能来自当前页面 TOP10% 子集。
+- Swing 分数是两次排名后合成，不是合成 raw 后再排名。
+- 历史不足时不能伪造评分/0变化；不能跨失败交易日跳位或跨版本相减。
+- migration 列顺序涉及所有 ranking SELECT 与 fake row，不得只改写入。
+- 离线重算的新发布必须可继续打开详情，且不得重新请求上游或改变旧快照。

.trellis/tasks/archive/2026-09/09-21-radar-weighted-score-rank-change/prd.md

@@ -0,0 +1,46 @@
+# 雷达加权评分与排名变化复刻
+
+## Goal
+
+根据已验证的 OneChart 评分公式，为单日和波段榜增加加权评分，并复刻排名变化的排序基准、1至5日窗口和双榜交互。
+
+## Requirements
+
+- R1：单日流入率与波段流入率双榜各增加“加权评分”列，左右镜像排列，保留 1 位小数，支持表头排序；原始流入率仍单独展示。
+- R2：采用本轮前置研究验证的评分结构。单日和波段榜按各自加权评分形成最终排名；波段原始流入率采用 3 日、10 日单日流入率均值各 50%。单日净额榜按净额形成排名。
+- R3：排名变化视图按参考截图提供独立次级控制行：左侧“排序基准”含波段率、单日率、单日额，右侧“统计天数”含近 1–5 日；首次进入默认波段率、近 1 日，并保留 URL 中显式指定的选择。
+- R4：排名变化视图展示“排名飙升榜 TOP 10% / 排名暴跌榜 BOTTOM 10%”，中央标题随基准切换；每行显示涨跌幅、所选基准的名次变化以及其余两个指标的名次变化。上下榜由所选基准决定，表头排序只重排该榜现有候选。
+- R5：名次变化为过去名次减当前名次，统计基于交易日，概念与行业分池。历史缺失、算法版本不兼容时显示“—”，不得伪造 0 或混用新旧算法名次。
+- R6：评分、最终名次、排名变化和详情历史使用相同算法版本；提供基于已有聚合事实重算历史的能力，旧发布保持可追溯。已有旧版本数据升级前仍能安全读取。
+- R7：继续使用知行当前数据库、板块池、按日成员快照与当前上市股票范围。复刻评分结构与交互，不以抓取 OneChart 结果替代业务计算，也不承诺与不同输入口径的网站逐值相等。
+
+## 范围边界
+
+- 本任务包含必要的领域计算、数据库派生字段迁移、HTTP 契约、前端及测试，以及历史重算命令。
+- 不包含调整证券母集、将网站当前成员回填历史、额外的榜单导出或搜索功能重写。
+- 本地实现与非破坏性验证按任务执行；生产迁移、生产历史重算、部署不在本轮执行范围内；Git 提交与推送已由后续用户请求明确授权。
+
+## Acceptance Criteria
+
+- [x] AC1/R1：单日/波段榜显示左右“加权评分”列，有限值为 1 位小数，缺失为“—”，排序与表头状态正确。
+- [x] AC2/R2：独立样例验证百分位、5 日成交额权重、3/10 日各 50% 及“先分别排名再合成”；高原始比率但低评分的反例能按评分正确排名。
+- [x] AC3/R3–R4：三基准 × 五窗口切换正确更新双榜、中央标题和辅助两列，URL 刷新可恢复；正负方向、镜像布局和窄屏横向滚动正确。
+- [x] AC4/R5：交易日跨周末、缺发布、缺板块、零变化、并列及新旧版本不匹配均有测试，榜单选取为对应池 ceil(N×10%) 个有效变化候选的上限。
+- [x] AC5/R6：旧行 weighted_score 为空时可读取；历史重算创建可追溯新发布且幂等，不请求外部数据；失败不影响最近成功发布，详情与榜单的当前名次一致。
+- [ ] AC6/R7：沿用当前股票/板块数据范围；单元、HTTP、前端、持久化及浏览器验证覆盖变更，项目规定的质量检查通过。
+
+## 已确认的现状与依据
+
+- 前置研究：`research/formula-evidence.md`。公开输入 9,492 条样本的评分与最终名次可精确重现；数据库输入存在成员/板块池差异。
+- 当前单日/波段只有原始 metric_value；旧波段策略实际为 3 至 10 日八个净额/成交额窗口等权，并非新研究中的两个窗口，见 `domain/metrics.py:140` 起。
+- 当前排名变化已有基础 API 与 1–5 日变化值，但 UI 控件、标题、辅助列不匹配截图，且历史名次基于旧原始指标，定位见 `research/code-evidence.md`。
+
+## 决策状态
+
+用户已明确回复“同意，开始实施”，批准本版方案。执行现有数据口径下的评分和交互升级；按个人约定由主代理编码与最终验证，子代理仅承担只读探索和独立核验。
+
+## 本轮验收状态
+
+AC1–AC5 已完成。AC6 的变更范围检查和浏览器验收通过；全仓检查仍有在实施前 HEAD 上独立复现的既有失败，因此保留未完全通过状态。详见 `validation.md`。本地实现已交付；功能代码已提交为 `b9981aa`，生产迁移、重算和部署未执行。
+
+用户已于本轮授权提交并推送。本任务的实现和范围内验证完成；AC6 的全仓基线失败仍明确保留为已知限制，不扩展修复选股/行情模块。线上重算说明已补入 `docs/market-data-sync.md`。

.trellis/tasks/archive/2026-09/09-21-radar-weighted-score-rank-change/research/code-evidence.md

@@ -0,0 +1,36 @@
+# 现有实现与改动定位
+
+只读研究已完成：`/root/radar_storage_research`、`/root/radar_ui_research`，主会话另行阅读领域算法、models、read、build 和 HTTP 相关契约。
+
+## 领域与应用
+
+- `domain/metrics.py:140` 起，旧 SwingEqualThreeToTenStrategy 取 3–10 日八个窗口的累计净额/累计成交额，再等权平均；需采用新版本，不能把它误认作前置研究的两个窗口。
+- `domain/ranking.py:42` 的排序键按 observation.value 排序；`with_rank_changes` 同版本过去名次减当前名次；select_rank_change_side 已实现 ceil(N×10%)，不需另写重复算法。
+- `application/build.py:694` 的 _rank 读取 9 个历史成功日期再拼当前日；历史排名取前 5 次成功发布，并非严格前 5 交易日。
+- `application/build.py:753` 的 input_hash 包含策略版本；重算可沿用版本隔离与幂等思路。
+- `application/read.py` 的 _METRIC_DEFINITIONS 和 `application/details.py:25` 的 _METRIC_VERSIONS 都硬编码当前策略；升级必须让旧发布保持可读。
+- `application/read.py:289` 的 extras 只服务 amount/ratio，swing/rank_change 的涨跌幅、净额和辅助字段需要补齐。
+- `application/details.py:173` 的 history_data 已按发布来源中的交易日历补出缺口，适合统一严格交易日语义；必须避免每行单独查库。
+
+## 存储
+
+- `domain/persistence.py:294–355` 定义 aggregate、ranking、history 读写契约。
+- `infrastructure/postgres.py:532–710` 为事务发布，`:741–778` 为 ranking 批写，`:1145–1173` 为序列化，`:1239–1267` 为固定列反序列化。
+- ranking SELECT 位于 `postgres.py:871–964`、`:996–1033`，当前只含 metric_value，没有 score。
+- `postgres.py:966–994` 的 aggregate history 只返回原始金额/coverage，不包含 publication_id、pct_change、leading_code，离线重算需要精确来源记录。
+- 最新迁移为 `0009_radar_sector_detail`。新增 score 应采用独立 migration，旧值可空。
+- 单测 `tests/unit/sector_radar/test_postgres_repository.py:43–65` 使用 17 列 fake row，必须随查询同步。现有集成测试尚未覆盖 ranking/aggregate 往返。
+
+## 前端
+
+- `pages/sector-radar-page.tsx:209–229` 已有两个下拉，分别为变化指标/对比区间；改为截图的按钮组与统计天数次行。
+- `pages/sector-radar-page.tsx:406–428` 顶部双榜和中央标题仍是普通资金榜文案。
+- `pages/sector-radar-page.tsx:430–463`、`:643–708` 是单日/波段镜像列，无 score。
+- `pages/sector-radar-page.tsx:465–500` 的变化榜目前只显示样本、排名百分位与一个变化值；应展示涨跌幅及另外两项指标变化。
+- `api/sector-radar.types.ts:61–114` 与 `api/sector-radar.api.ts:277–377` 仅承载单个 rank_change，需扩展。
+- 路由与 query key 已保存基准/天数，保留这一结构；URL 显式值优先。
+- 页面测试 `sector-radar-page.test.tsx:654–683` 已覆盖正变化/缺历史，需增加评分、三基准五窗口、镜像辅助列、侧内排序与截图文案。
+
+## 参考站核对
+
+本会话下载的 `/tmp/onechart-public-evidence/index.html` 中：`:1197` 默认 Swing/1 日，`:1380` 附近 mirrorMetricLabel 随基准变，`:1397–1427` 的 mirrorAuxColumns 在变化榜显示另外两个基准，在单日/波段榜显示 score/净额/在榜。前置研究完整来源和数值证据位于已归档的评分研究任务。

.trellis/tasks/archive/2026-09/09-21-radar-weighted-score-rank-change/research/formula-evidence.md

@@ -0,0 +1,19 @@
+# 加权公式与验证边界
+
+前置研究在 2026-09-04 至 2026-09-21 的 9,492 条公开样本上复现单日、波段评分与最终排名；分数最大误差 3.41e-13，属于浮点运算误差。这是观测数据还原，不是原站源码证据。
+
+对本项目已有聚合数据，F 为主力净额元、A 为成交额元：
+
+```text
+r = F / (A + 100)
+W = log10(1 + MA5(A)) / 10
+单日评分 = 1000 × P(r) × W
+波段评分 = 500 × (P(MA3(r)) + P(MA10(r))) × W
+波段原值 = (MA3(r) + MA10(r)) / 2
+```
+
+P 为同日、同类型全池升序平均名次 / N。波段必须先分别排名，再合成。最终评分并列按板块代码稳定排序。权重可能大于 1，分数不是固定上限 1000 的百分制。
+
+公开字段可以确认的等价权重是 `log10(MA5(F/r)-99)/10`；`A=F/r-100` 是本任务采用的可复算口径，不能证明原站源码中具体常量的用途。原站边界与并列规则未完全公开，本地明确使用 design.md 中的完整交易日窗口、平均并列名次及缺失语义。
+
+公开验证池为 791 个板块，本地数据库池和按日成员不同。本项目保留当前上市股票与已保存历史输入，因此不承诺与网站逐值相同。原始研究数据和复算快照保留在本地前置研究任务中，不是运行本功能的依赖。

.trellis/tasks/archive/2026-09/09-21-radar-weighted-score-rank-change/research/seed_local_preview.py

@@ -0,0 +1,166 @@
+"""Synthetic browser fixtures; restricted to the disposable local radar test DB."""
+
+import hashlib
+import math
+import os
+from dataclasses import replace
+from datetime import UTC, date, datetime, timedelta
+from decimal import Decimal
+from urllib.parse import urlsplit
+
+import psycopg
+
+from zhixing_server.modules.sector_radar.application.scoring import calculate_rankings
+from zhixing_server.modules.sector_radar.domain.metrics import (
+    AmountNetStrategy,
+    RatioTurnoverStrategy,
+    SwingEqualThreeToTenStrategy,
+)
+from zhixing_server.modules.sector_radar.domain.models import (
+    PublicationStatus,
+    RadarPublication,
+    SectorDailyAggregate,
+    SectorType,
+)
+from zhixing_server.modules.sector_radar.domain.persistence import (
+    DailyAggregateRecord,
+    PublicationSourceGroup,
+    PublicationSourceRecord,
+    RankingRecord,
+)
+from zhixing_server.modules.sector_radar.domain.source import build_source_snapshot
+from zhixing_server.modules.sector_radar.infrastructure.postgres import (
+    PostgresSectorRadarRepository,
+)
+
+url = os.environ["ZHIXING_TEST_DATABASE_URL"]
+location = urlsplit(url)
+if (location.hostname, location.port, location.path) != ("127.0.0.1", 55439, "/radar_test"):
+    raise SystemExit("Preview seeding is restricted to the disposable local radar test database")
+with psycopg.connect(url) as connection:
+    connection.execute("TRUNCATE sector_radar_publication CASCADE")
+
+start = date(2026, 8, 10)
+days = tuple(
+    start + timedelta(days=n) for n in range(43) if (start + timedelta(days=n)).weekday() < 5
+)
+strategies = (AmountNetStrategy(), RatioTurnoverStrategy(), SwingEqualThreeToTenStrategy())
+names = (
+    "人工智能",
+    "机器人",
+    "商业航天",
+    "低空经济",
+    "半导体",
+    "创新药",
+    "新能源",
+    "电力设备",
+    "数字经济",
+    "消费电子",
+)
+now = datetime.now(UTC)
+calendar = build_source_snapshot(
+    api_name="trade_cal",
+    params={"fixture": "weighted-radar-preview"},
+    rows=[{"exchange": "SSE", "cal_date": day, "is_open": 1} for day in days],
+    target_trade_date=days[-1],
+    observed_at=now,
+)
+repository = PostgresSectorRadarRepository(url)
+history = []
+try:
+    repository.save_source_snapshots((calendar,))
+    for index, day in enumerate(days):
+        aggregates = []
+        for sector_type, size in ((SectorType.CONCEPT, 300), (SectorType.INDUSTRY, 100)):
+            for n in range(size):
+                turnover = Decimal(
+                    str(10 ** (8 + n % 4) * (1 + 0.2 * math.cos(n + index)))
+                ).quantize(Decimal(".01"))
+                ratio = Decimal(
+                    str(
+                        0.09 * math.sin(n * 1.37 + index * 0.43) + 0.02 * math.cos(n * 0.71 + index)
+                    )
+                )
+                aggregates.append(
+                    SectorDailyAggregate(
+                        day,
+                        sector_type,
+                        f"TEST-{sector_type.value[0]}-{n:04}",
+                        f"{names[n % len(names)]} {n + 1}",
+                        10,
+                        10,
+                        (turnover * ratio).quantize(Decimal(".01")),
+                        turnover,
+                        Decimal(1),
+                        Decimal(1),
+                    )
+                )
+        publication = RadarPublication(
+            f"preview-{day}",
+            day,
+            PublicationStatus.RUNNING,
+            "local-preview-v1",
+            "synthetic-preview-v1",
+            tuple(strategy.metric_version for strategy in strategies),
+            None,
+            Decimal(1),
+            now,
+        )
+        repository.create_publication(publication)
+        repository.save_publication_sources(
+            (
+                PublicationSourceRecord(
+                    publication.publication_id, PublicationSourceGroup.CALENDAR, 0, calendar
+                ),
+            )
+        )
+        for sector_type, group in (
+            (SectorType.CONCEPT, PublicationSourceGroup.CONCEPT_INDICES),
+            (SectorType.INDUSTRY, PublicationSourceGroup.INDUSTRY_INDICES),
+        ):
+            snapshot = build_source_snapshot(
+                api_name="dc_index",
+                params={"fixture": "preview", "type": sector_type.value},
+                rows=[
+                    {
+                        "trade_date": day,
+                        "ts_code": row.sector_code,
+                        "name": row.sector_name,
+                        "pct_change": Decimal(str(3 * math.sin(n + index))).quantize(
+                            Decimal(".01")
+                        ),
+                    }
+                    for n, row in enumerate(aggregates)
+                    if row.sector_type is sector_type
+                ],
+                target_trade_date=day,
+                observed_at=now,
+            )
+            repository.save_source_snapshots((snapshot,))
+            repository.save_publication_sources(
+                (PublicationSourceRecord(publication.publication_id, group, 0, snapshot),)
+            )
+        ranks = calculate_rankings(day, aggregates, history, days, strategies)
+        repository.finalize_publication(
+            replace(
+                publication,
+                status=PublicationStatus.SUCCESS,
+                input_hash=hashlib.sha256(str(day).encode()).hexdigest(),
+                finished_at=now,
+            ),
+            memberships=(),
+            stock_facts=(),
+            daily_aggregates=(
+                DailyAggregateRecord(
+                    publication.publication_id,
+                    row,
+                    Decimal(str(3 * math.sin(n + index))).quantize(Decimal(".01")),
+                )
+                for n, row in enumerate(aggregates)
+            ),
+            rankings=(RankingRecord(publication.publication_id, row) for row in ranks),
+        )
+        history.extend(aggregates)
+    print(f"Seeded {len(days)} days × 400 synthetic sectors; no production data or provider calls.")
+finally:
+    repository.close()

.trellis/tasks/archive/2026-09/09-21-radar-weighted-score-rank-change/task.json

@@ -0,0 +1,41 @@
+{
+  "id": "radar-weighted-score-rank-change",
+  "name": "radar-weighted-score-rank-change",
+  "title": "雷达加权评分与排名变化复刻",
+  "description": "根据已验证的 OneChart 评分公式，为单日和波段榜增加加权评分，并复刻排名变化的排序基准、1至5日窗口和双榜交互。",
+  "status": "completed",
+  "dev_type": "fullstack",
+  "scope": "sector-radar",
+  "package": null,
+  "priority": "P2",
+  "creator": "yuxuanhui",
+  "assignee": "yuxuanhui",
+  "createdAt": "2026-09-21",
+  "completedAt": "2026-09-21",
+  "branch": "develop",
+  "base_branch": "develop",
+  "worktree_path": null,
+  "commit": "b9981aa48de32dc1fac03f2febfbdd6786ff0f72",
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [
+    "zhixing-server/src/zhixing_server/modules/sector_radar/domain/weighted.py",
+    "zhixing-server/src/zhixing_server/modules/sector_radar/application/recompute.py",
+    "zhixing-server/migrations/versions/0010_radar_weighted_score.py",
+    "zhixing-web/src/features/sector-radar/pages/sector-radar-page.tsx",
+    "zhixing-web/src/features/sector-radar/components/radar-table-sort.ts"
+  ],
+  "notes": "功能代码提交 b9981aa；后端雷达 110 项、前端雷达 74 项及浏览器 30 组合通过。独立检查未发现新增阻塞。全仓既有失败见 validation.md；原始研究快照未纳入提交，生产迁移、重算、部署未执行。",
+  "meta": {
+    "planning_status": "approved",
+    "planning_summary_version": 1,
+    "production_writes_authorized": false,
+    "implementation_status": "complete",
+    "validation_status": "scoped_pass_with_verified_baseline_failures",
+    "commit_push_authorized": true,
+    "spec_sync": "No shared spec promotion; reviewed formula and limitations retained in task artifacts.",
+    "accepted_baseline_limitations": true
+  }
+}

.trellis/tasks/archive/2026-09/09-21-radar-weighted-score-rank-change/validation.md

@@ -0,0 +1,71 @@
+# 实施与验证记录
+
+2026-09-21，本地实施完成。功能代码已提交为 `b9981aa`；本轮用户已授权推送。生产数据库未迁移、未重算，未部署。
+
+## 已实现
+
+- 单日/波段流入率增加镜像加权评分列，保留 1 位小数，原始率独立展示。左右列头分别排序，加载该侧完整候选榜后应用排序，NULL 始终置后。
+- 新算法版本为 `zhixing_ratio_weighted_v2`、`zhixing_swing_weighted_v2`。全池平均名次百分位与 5 日成交额权重在后端计算，波段使用 MA3/MA10 分别排名后各占 50%。
+- 排名变化提供波段率/单日率/单日额、近 1–5 天、涨跌幅、另外两项指标的变化、镜像双榜和随基准更新的标题。URL 无显式值时默认波段率、近 1 天。
+- 对比使用保存的交易日历和同版本名次。缺发布、缺板块、历史不足或版本不匹配时保持未知，不跳过缺失交易日、不伪造零。
+- 迁移 `0010_radar_weighted_score` 增加 nullable NUMERIC(28,12) 和有限值约束。全部排名读写路径、HTTP、前端解析与详情历史同步扩展。
+- `sector-radar-build --recompute` 只读取已有聚合事实与源快照，按日期生成新发布，保留原发布。当前名次、历史和详情使用相同版本。
+
+## 实际验证
+
+| 检查 | 结果 |
+| --- | --- |
+| 后端雷达领域、构建、读取、HTTP、PostgreSQL 集成 | 110 passed |
+| 前端雷达 API、query、详情、页面 | 74 passed |
+| 后端 Ruff format/check | 通过 |
+| 本次后端模块、测试和迁移 Pyright | 0 errors |
+| 前端格式、ESLint、TypeScript 和生产 build | 通过；Vite 仍提示既有大 chunk |
+| migration 0010 → 0009 → 0010 | 288 条原始排名保留，新增评分为 NULL |
+| 真实 PostgreSQL 重算 | 保留旧发布、评分在各读取路径一致、详情来源完整、失败不替换 last-good |
+| CLI 完整重算 | 31 日 × 400 个合成板块；首次 success，重复 31 日均 unchanged |
+| 浏览器 2 类型 × 3 基准 × 5 天数 | 30 组合通过；首行变化与 API 一致，刷新恢复 URL 选择 |
+| 浏览器评分排序 | 左榜完整 31 个、右榜完整 30 个候选；升降序正确且两侧独立 |
+| 浏览器窄屏与缺历史 | 390px 页面无整页横向溢出；960px 表格可横向滚动；空历史文案完整可见 |
+| Git diff/context manifests | diff --check 与 7/9 条上下文清单校验通过 |
+
+数据库验证均在单独创建的本地 PostgreSQL 17 容器执行，未连接生产数据库。浏览器预览为合成测试数据；`research/seed_local_preview.py` 限制只能写入本地测试库。控制台仅观察到既有 favicon.ico 404，没有本次页面异常。
+
+## 全仓基线问题
+
+完整命令已执行，但不能报告全仓检查通过。已用 `git archive HEAD`（实施前 HEAD `669e89d`）及相同依赖独立复现：
+
+- 后端全量 Pyright：14 个相同错误，位于 selection 的 `chart.py`、`gold_brick.py`、`test_run.py`。
+- 后端全量 pytest：本次 230 passed / 6 failed，修改前 221 passed / 同样 6 failed。既有 market_data 集成测试调用不存在的 Connection.executemany；旧迁移测试日志配置导致后续 5 个日志断言失败。雷达相关 110 项在独立运行时全部通过。
+- 前端 `pnpm check` 的格式、lint 和类型均通过；全量 Vitest 为 148 passed / 4 failed。修改前 selection 页面同样 4 个执行状态弹窗测试失败（其余 20 个通过）。
+
+这些既有选股/行情问题未在本任务扩展修复。前端 `.prettierignore` 补充已被 Git 忽略的 `.playwright-cli`，避免旧浏览器快照影响格式检查。
+
+## 生产应用步骤（尚未执行）
+
+生产 Compose 的完整构建、迁移、重算顺序见 `docs/market-data-sync.md`。以下为直接使用 Python 环境时的等价命令。
+
+在目标环境确认 `ZHIXING_DATABASE_URL` 指向正确数据库，先执行迁移，再上线代码并重算现有日期区间：
+
+```bash
+cd zhixing-server
+uv run alembic upgrade head
+uv run sector-radar-build --recompute --start-date 2026-08-28 --end-date 2026-09-21
+```
+
+日期应覆盖需要展示的已有历史；命令只处理区间内已有成功发布。单日评分需要连续 5 个交易日成交额，波段评分需要连续 10 个交易日输入；要比较近 5 日波段名次，还需要相应更早窗口。缺失日期保持未知，重算不补造原始行情或成员数据。
+
+新列允许旧行为 NULL，旧发布保留追溯。回退需切回保留的旧版本发布；不能在仍运行新代码时直接删列。当前代码库没有自动生产回退动作，本任务没有执行任何生产状态变更。
+
+## 预览证据
+
+- `output/playwright/radar-rank-change-desktop.png`
+- `output/playwright/radar-swing-desktop.png`
+- `output/playwright/radar-ratio-desktop.png`
+- `output/playwright/radar-rank-change-mobile.png`
+- `output/playwright/radar-missing-history-mobile.png`
+
+本地预览：`http://127.0.0.1:15173/sector-radar?view=rank_change&tradeDate=2026-09-21`。前端端口 15173，后端端口 18081，数据库容器 `zhixing-radar-score-test`（本地端口 55439）；均用于隔离验收。
+
+## 提交前复核
+
+本轮独立只读检查由 `/root/radar_commit_review` 完成，未发现新增正确性或部署阻塞；范围内 Ruff/Pyright 和 diff 检查通过。Compose Job 的 entrypoint 与新版 CLI 参数已核对，并使用无生产凭据的配置通过 `docker compose config --quiet`。线上操作说明已补入 `docs/market-data-sync.md`；本轮只执行 Git 提交与推送，不执行线上迁移、重算或部署。

.trellis/workspace/yuxuanhui/index.md

@@ -8,8 +8,8 @@
 
 <!-- @@@auto:current-status -->
 - **Active File**: `journal-1.md`
-- **Total Sessions**: 15
+- **Total Sessions**: 17
-- **Last Active**: 2026-09-01
+- **Last Active**: 2026-09-25
 <!-- @@@/auto:current-status -->
 
 ---
@@ -19,7 +19,7 @@
 <!-- @@@auto:active-documents -->
 | File | Lines | Status |
 |------|-------|--------|
-| `journal-1.md` | ~356 | Active |
+| `journal-1.md` | ~420 | Active |
 <!-- @@@/auto:active-documents -->
 
 ---
@@ -29,6 +29,8 @@
 <!-- @@@auto:session-history -->
 | # | Date | Title | Commits | Branch |
 |---|------|-------|---------|--------|
+| 17 | 2026-09-25 | 部署运行器调整与全部存量任务收尾 | `f020362` | `develop` |
+| 16 | 2026-09-21 | 雷达加权评分与排名变化上线准备 | `b9981aa` | `develop` |
 | 15 | 2026-09-01 | 选股模块技术图表迭代 | `9145fe4`, `feb8fd4` | `-` |
 | 14 | 2026-09-01 | 完成板块资金雷达双榜交互对齐 | `744cb76` | `develop` |
 | 13 | 2026-09-01 | 板块资金雷达滚动加载迭代 | `be31235`, `5f34be5` | `develop` |

.trellis/workspace/yuxuanhui/journal-1.md

@@ -364,3 +364,57 @@
 ### Status
 
 [OK] **Completed**
+
+
+## Session 16: 雷达加权评分与排名变化上线准备
+
+**Date**: 2026-09-21
+**Task**: 雷达加权评分与排名变化上线准备
+**Branch**: `develop`
+
+### Summary
+
+实现单日/波段加权评分、三基准与1至5交易日排名变化、版本兼容与离线历史重算。雷达后端110项、前端74项和浏览器30组合通过；全仓既有失败已在修改前HEAD复现，独立复核无新增阻塞。补充生产Compose迁移及重算说明。用户授权提交和推送，生产数据库未改动；前置研究原始快照留本地。
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `b9981aa` | (see git log) |
+
+### Status
+
+[OK] **Completed**
+
+
+## Session 17: 部署运行器调整与全部存量任务收尾
+
+**Date**: 2026-09-25
+**Task**: 部署运行器调整与全部存量任务收尾
+**Branch**: `develop`
+
+### Summary
+
+生产部署运行器改为 tencent-prod，本地 origin 更新至 my-home/zhixing-system；按用户明确要求将全部 5 个未归档任务标记 completed 并归档，清理空 Redis 任务目录及残留会话引用。
+
+### Main Changes
+
+- 归档：09-01-optimize-stock-list-radar、09-04-add-gold-brick-strategy、09-05-selection-layout-sector-filter、09-06-capital-radar-daily-detail、09-07-api-performance-diagnosis。
+- 本次为用户要求的统一完结；保留原始 PRD、验收勾选、验证记录和历史限制，不将归档等同于全部功能重新验收通过。
+- 两份 .zcode/plans/ 文件的既有删除未修改、未纳入提交；未推送远端或执行部署。
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `f020362` | (see git log) |
+
+### Testing
+
+- [OK] 部署配置：YAML 解析、main 触发与 tencent-prod 标签断言、生产 Compose 默认及 jobs 配置校验、git diff --check 均通过。
+- [OK] 归档核验：5 个任务元数据仅修改 status/completedAt；其余任务文件哈希与归档前一致；全部活动任务清空，残留当前任务引用已清除。
+- [OK] 本轮未重跑产品测试或验证历史任务的线上验收；已有验证限制保留在归档文档中。
+
+### Status
+
+[OK] **Completed**

.zcode/plans/plan-sess_24b98073-00f4-4b58-a624-fbfe486bcf2a.md

@@ -1,35 +0,0 @@
-## 调研结论（可行性：具备）
-
-**现状**
-- 详情面板 `zhixing-web/src/features/selection/components/signal-detail-panel.tsx` 只展示名称/代码/价格/指标，无行业板块；`SelectionStockResult` 类型也无相关字段。
-- 后端 `market_stock` 表没同步 tushare `stock_basic.industry`；但项目已有 **sector_radar 模块**，通过 tushare `dc_index`/`dc_member` 每日同步"行业板块 + 概念板块"的成分股快照到 PostgreSQL 表 `sector_radar_membership`（trade_date + sector_type=industry/concept + sector_code/name + stock_code），只是目前只暴露了板块级 rankings 端点，**没有"按股票反查所属板块"的接口**——这就是缺口的全部。
-- 已确认决策：数据口径复用 sector_radar（DC 行业+概念）；仅详情面板展示，列表行不动。
-
-## 实施方案
-
-### 第 0 步：数据验证（前置）
-启动 docker compose 的 PostgreSQL，检查 `sector_radar_membership` 按交易日的覆盖情况。若选股目标日期无快照，运行现有 CLI `sector-radar-build` 回补。若 dc_member 接口因 tushare 积分不足失败，回退方案是给 `market_stock` 加 `stock_basic.industry` 列（Alembic 迁移），届时向你说明。
-
-### 后端（sector_radar 模块内新增"按股票反查"，不跨模块读表）
-1. `modules/sector_radar/infrastructure/postgres.py`：新增读查询——按 `stock_code` 查 `membership_status='available'` 且 `trade_date <= 目标日` 的最近可用快照（带出实际 membership 的 trade_date，point-in-time 语义，不用最新日期冒充历史）。
-2. `modules/sector_radar/application/read.py`：新增用例，输入 `ts_code + trade_date`，返回按类型分组的板块列表（industry 全部、concept 排序后默认截断 20 个）。
-3. `modules/sector_radar/presentation/http.py`：新增端点
-   `GET /api/v1/sector-radar/stocks/{ts_code}/membership?trade_date=YYYY-MM-DD&limit=20`
-   响应：`{ ts_code, trade_date, membership_trade_date, industries: [{code,name}], concepts: [{code,name}], concept_total }`，遵循 http-api-contracts spec（Pydantic 边界模型）。
-
-### 前端（selection feature）
-4. 新增 API 调用 + TanStack Query hook（`enabled: !!stock`，按 `stock.target_trade_date` 查询，随详情面板选中切换）。
-5. `signal-detail-panel.tsx`：股票名/代码/价格下方新增两行展示——
-   - **行业**：行业标签（通常 1 个）
-   - **所属板块**：概念板块 chips，最多显示 8 个 + "等 N 个"
-   加载中显示占位文案，无数据时静默隐藏（不打扰无板块数据的股票）。
-
-### 测试与验证
-- 后端：读用例单测（命中/无快照/截断）+ http 端点测试，参照 sector_radar 现有测试。
-- 前端：vitest 组件测试 + typecheck/lint。
-- 端到端：起 server + web，在 `/selection` 选一只股票确认行业与板块正确显示、无数据股票正常降级。
-
-### 涉及文件
-- `zhixing-server/.../modules/sector_radar/{application/read.py, infrastructure/postgres.py, presentation/http.py}`
-- `zhixing-web/src/features/selection/api/*`（新 query）
-- `zhixing-web/src/features/selection/components/signal-detail-panel.tsx`

.zcode/plans/plan-sess_55e3d246-e875-4283-bdfc-929f8f26a73f.md

@@ -1,42 +0,0 @@
-# 选股页面迭代：上搜索 + 左列表/右详情布局 & 板块筛选
-
-## 现状与关键结论
-
-- 布局：`selection-results-workbench.tsx` 目前是左右两栏 grid（左 320px 筛选+列表 / 右详情），筛选栏嵌在左栏顶部。
-- 板块数据：选股结果表（`selection_run_item`）没有板块字段；板块归属在 `sector_radar_membership` 表，现有 membership 接口只支持单股查询。**板块聚合必须由后端新增**（前端逐股请求既慢又只覆盖已加载分页，计数不准）。
-- 已确认口径（用户未答，按推荐执行）：概念板块（`sector_type='concept'`，与详情面板"板块"标签一致），单选；接口保留 `sector_type` 参数，后续扩展行业零成本。排序 = 按 `stock_count` 倒序（选项旁展示数量）。
-
-## 一、后端（zhixing-server）
-
-遵循 bounded-context-first（ADR 0001）：selection 不直接 join sector_radar 表，通过应用层端口调用 sector_radar 的读服务。
-
-1. **sector_radar 模块**（`application/read.py` + `infrastructure/postgres.py`）：
-   - 仓储新增两个只读方法（复用已有的 `get_last_good_publication` 解析快照日）：
-     - `load_sector_counts(stock_codes, snapshot_date, sector_type)`：`SELECT sector_code, sector_name, COUNT(*) FROM sector_radar_membership WHERE stock_code = ANY(%s) AND trade_date = %s AND sector_type = %s AND membership_status='available' GROUP BY 1,2`
-     - `load_sector_member_codes(snapshot_date, sector_code, sector_type)`：返回该板块成员股票代码列表
-   - 读服务 `ReadSectorRadar` 新增：`sector_counts(stock_codes, trade_date, sector_type)`（内部解析 last-good publication，返回按 stock_count 降序、名称升序）和 `sector_member_codes(trade_date, sector_code, sector_type)`。
-2. **selection 模块**：
-   - `domain/runs.py`：`SelectionResultQuery` 增加 `sector: str | None`；新增 `SelectionSectorCount(sector_code, sector_name, stock_count)` 值对象；定义端口协议 `SectorMembershipReader`（`sector_counts` / `sector_member_codes` 两个方法）。
-   - `application/run.py`：新增 `list_sector_counts(strategy, target_trade_date, sector_type)` —— 取 latest run，收集 `status='selected' AND signal_count>0` 的 ts_code，调端口聚合；`get_latest`/`get` 结果查询在 `query.sector` 有值时先调端口取成员代码，空则直接返回空页，否则把代码数组传入仓储。
-   - `infrastructure/postgres_runs.py`：`_stock_filter` 增加子句 `item.ts_code = ANY(%s)`（参数由应用层传入）。
-   - `presentation/http.py`：
-     - 新端点 `GET /api/v1/selection/sectors?strategy=&target_trade_date=&sector_type=` → `{ sector_type, snapshot_trade_date, sectors: [{sector_code, sector_name, stock_count}] }`
-     - `GET /results` 与 `GET /runs/{id}` 增加 `sector` query 参数校验（去空格、限长）。
-   - 组合根（router/依赖装配处）把 sector_radar 的读服务适配为 selection 的端口注入。
-3. **测试**：`tests/unit/sector_radar/`（新仓储方法）、`tests/unit/selection/test_postgres_runs.py`（sector 过滤、ANY 数组、空成员空页）、`tests/test_selection_http.py`（新端点契约 + results 带 sector）。跑 `./dev.sh check`（ruff/pyright/pytest）。
-
-## 二、前端（zhixing-web）
-
-1. **布局重构** `selection-results-workbench.tsx`：
-   - 外层改为 `flex flex-col`：顶部一个全宽 section 放搜索栏（关键词 / 信号分类 / **板块（新增）** / 排序 / 筛选结果计数），带 `rounded-md border bg-card` 与现有一致；
-   - 下方 `md:grid md:grid-cols-[320px_minmax(0,1fr)]` 左列表右详情；移动端纵向堆叠为 搜索 → 列表 → 详情。
-2. **类型与 API**（`selection.types.ts` / `selection.api.ts`）：新增 `SelectionSectorAggregate`；`SelectionResultsQuery` 加 `sector?`；`getSelectionResultSectors()`；`buildSelectionQueryParams` 带 sector。
-3. **查询层**（`selection.query.ts`）：`useSelectionResultSectors`（key：strategy+date，结果就绪后启用）；`selectionResultsQueryKey`/`selectionRunQueryKey` 加入 sector 使筛选变化触发重新请求。
-4. **路由**（`routes/route-tree.tsx`）：selectionRoute `validateSearch` 增加 `sector`（string，限长，默认 undefined）。
-5. **页面接线**（`selection-results-page.tsx`）：把 URL 中的 sector 传入 `useSelectionResults`；页面层调用 `useSelectionResultSectors` 并把聚合结果传给 workbench。
-6. **workbench 板块下拉**：选项 = "全部板块" + 聚合数据，item 渲染 `名称 + 数量徽标`（数量 tabular-nums，倒序由后端保证）；选择写 URL；聚合加载后若当前 sector 不在列表中（如切换策略/日期）自动重置为全部；板块无数据时下拉仅剩"全部板块"并禁用。
-
-## 三、执行方式
-
-- 按仓库 Trellis 工作流建任务目录并加载 `.trellis/spec/backend`（selection.md 契约：查询不触发重算、错误矩阵等）与前端规范后再动手；先后端（接口+测试）再前端接线，最后 `./dev.sh check` + 前端 lint/tsc 全量质量门禁。
-- 语义说明：板块数量 = 当次 run 全部选中股票中归属该板块的数量（不随关键词/信号分类变化）；列表"筛选结果 N 只" = 包含板块在内的全部过滤叠加后的 `stocks_total`。

docker-compose.prod.yml

@@ -1,7 +1,22 @@
 name: ${COMPOSE_PROJECT_NAME:-zhixing-system}
 
+x-observability-labels: &observability-labels
+  observability.logs: "true"
+  observability.project: "zhixing-system"
+  observability.env: "production"
+
+x-container-logging: &container-logging
+  driver: json-file
+  options:
+    max-size: "20m"
+    max-file: "5"
+
 services:
   server:
+    labels:
+      <<: *observability-labels
+      observability.service: "server"
+    logging: *container-logging
     build:
       context: ./zhixing-server
       target: production
@@ -47,6 +62,10 @@ services:
       - 1panel-network
 
   web:
+    labels:
+      <<: *observability-labels
+      observability.service: "web"
+    logging: *container-logging
     build:
       context: ./zhixing-web
       target: production
@@ -62,6 +81,10 @@ services:
       - "127.0.0.1:${ZHIXING_WEB_PORT:-8111}:80"
 
   migrate:
+    labels:
+      <<: *observability-labels
+      observability.service: "migrate"
+    logging: *container-logging
     profiles: ["jobs"]
     build:
       context: ./zhixing-server
@@ -78,6 +101,10 @@ services:
 
   # Named volumes are initialized as root; normalize ownership before app jobs run.
   market-data-init:
+    labels:
+      <<: *observability-labels
+      observability.service: "market-data-init"
+    logging: *container-logging
     profiles: ["jobs"]
     build:
       context: ./zhixing-server
@@ -93,6 +120,10 @@ services:
       - market-data:/app/data/market-data
 
   market-sync:
+    labels:
+      <<: *observability-labels
+      observability.service: "market-sync"
+    logging: *container-logging
     profiles: ["jobs"]
     build:
       context: ./zhixing-server
@@ -118,6 +149,10 @@ services:
       - 1panel-network
 
   sector-radar-build:
+    labels:
+      <<: *observability-labels
+      observability.service: "sector-radar-build"
+    logging: *container-logging
     profiles: ["jobs"]
     build:
       context: ./zhixing-server

docs/market-data-sync.md

@@ -123,3 +123,36 @@ docker compose -f docker-compose.prod.yml --profile jobs run --rm sector-radar-b
 `moneyflow_dc` 先按交易日拉取全市场快照；即使首批达到 6000 行，也会根据上述候选股票检查实际覆盖，并用固定两路 worker 逐只补拉缺失代码。全市场请求、补拉和 retry 在同一 adapter 内共享 `ZHIXING_SECTOR_RADAR_REQUEST_INTERVAL_SECONDS`（默认 0.2 秒）的请求启动间隔；空分片或普通请求重试耗尽会保留为覆盖缺口并形成 `partial`，来源返回错误日期、错误代码、重复键或分片再次触顶则整次构建失败。该限流只在单进程 adapter 内生效，生产调度仍不得让 `market-data-sync` 与 `sector-radar-build` 重叠运行。
 
 重复输入通过内容 hash 复用已有成功发布，不产生无意义修订；同一目标日由 PostgreSQL advisory lock 阻止并发构建。`success` 或 `unchanged` 返回 0，覆盖率不足的 `partial` 返回 2，输入、上游、锁或基础设施失败返回 1。`partial`/`failed` 会保留审计，但读取端只选择 `success` 作为 last-good。当前版本只提供手工和外部调度入口，不新增生产 Cron；待真实账号 capability、到达时点和首轮回填验证完成后再单独启用调度。
+
+### 升级加权评分并重算历史
+
+`--recompute` 只使用数据库中已有的板块聚合事实、交易日历和源快照，生成新的评分与排名发布；不调用 Tushare，不需要 token，不修改旧发布或历史成员。它与重新拉取上游的普通构建不同，不能和 `--retry-publication-id` 同用。
+
+在生产项目目录中，将代码更新到包含加权评分的提交，沿用生产 `.env`，依次执行以下命令；每步成功后再执行下一步。Compose 为不同服务使用不同镜像名，因此除服务端和前端外，也要构建迁移与重算 Job 的新镜像。
+
+```bash
+# 构建新代码，暂不替换运行中的服务
+docker compose -f docker-compose.prod.yml --profile jobs build \
+  server web migrate sector-radar-build
+
+# 先增加 nullable weighted_score 列（0010），再启动新服务
+docker compose -f docker-compose.prod.yml --profile jobs run --rm --no-deps migrate
+docker compose -f docker-compose.prod.yml up -d server web
+
+# 使用新 Job 镜像，按交易日顺序重算已有历史
+docker compose -f docker-compose.prod.yml --profile jobs run --rm --no-deps sector-radar-build \
+  --recompute --start-date 2026-08-28 --end-date 2026-09-21
+```
+
+这里的日期是示例，应覆盖需要展示的已有历史，区间包含起止日。单日评分需要连续 5 个交易日成交额，波段评分需要连续 10 个交易日流入率；近 5 日波段排名变化还要求更早的对比日也有足够历史并已采用同一算法版本。首次升级建议从最早已有成功发布开始重算整个展示区间。缺少交易日、板块或可比版本时显示“—”，重算不会补造缺失数据。
+
+输出的 `outcomes` 列出逐日结果；整个命令 `status` 为 `success` 或 `unchanged` 且退出码为 0 表示完成。相同输入重复运行返回 `unchanged`；失败会保留原 last-good，可修复原因后重跑同一区间。重算期间避免同时启动覆盖相同日期的普通构建或另一个重算任务。
+
+以后只重算某一天，可复用已构建的新 Job 镜像：
+
+```bash
+docker compose -f docker-compose.prod.yml --profile jobs run --rm --no-deps sector-radar-build \
+  --recompute --trade-date 2026-09-21
+```
+
+`--no-deps` 用于上述已手动完成迁移的流程，避免再次启动依赖服务。`sector-radar-build` 服务配置了同名 entrypoint，后面直接传 `--recompute` 等参数即可。