@loomhelm/multi-task-flow 0.0.0-stage → 0.2.1

package/src/workflow/cli.ts

@@ -0,0 +1,48 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { LocalValidation, type ContractDecision, type ValidationEntry } from './local.ts';
+import { loadSkills, requireSkill, type SkillScope } from './skills.ts';
+
+async function main(): Promise<void> {
+  const [command, path, user, ...extra] = process.argv.slice(2);
+  if (!path || extra.length || (command === 'local-verify' && user)) throw new Error('Usage: workflow/cli.ts skills <project-skills-dir> [user-skills-dir] | local-verify <manifest.json>');
+  if (command === 'skills') {
+    const catalog = await loadSkills({ project: resolve(path), ...(user ? { user: resolve(user) } : {}) });
+    console.log(JSON.stringify(catalog));
+    if (catalog.diagnostics.length) process.exitCode = 1;
+    return;
+  }
+  if (command !== 'local-verify') throw new Error('Unknown workflow command');
+  const manifestPath = resolve(path);
+  const raw: unknown = JSON.parse(await readFile(manifestPath, 'utf8'));
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('Invalid workflow manifest');
+  const manifest = raw as Record<string, unknown>;
+  if (manifest.schemaVersion !== 1 || Object.keys(manifest).some(key => !['schemaVersion', 'repository', 'base', 'flowType', 'skills', 'contracts', 'implementation', 'validations'].includes(key))) throw new Error('Unsupported workflow manifest');
+  if (typeof manifest.repository !== 'string' || typeof manifest.base !== 'string' || typeof manifest.implementation !== 'string' || !Array.isArray(manifest.contracts) || !Array.isArray(manifest.validations)) throw new Error('Invalid workflow manifest');
+  const flowType = manifest.flowType ?? 'normal';
+  if (flowType !== 'normal' && flowType !== 'fast-track' && flowType !== 'local-merge') throw new Error('Invalid flow type');
+  const repository = resolve(dirname(manifestPath), manifest.repository);
+  let selectedSkills: ReturnType<typeof requireSkill>[] = [];
+  if (manifest.skills !== undefined) {
+    const value = manifest.skills as { project: string; user?: string; requirements: { name: string; range?: string; scopes?: SkillScope[] }[] };
+    if (!value || typeof value.project !== 'string' || (value.user !== undefined && typeof value.user !== 'string') || !Array.isArray(value.requirements)) throw new Error('Invalid skill requirements');
+    const catalog = await loadSkills({ project: resolve(repository, value.project), ...(value.user ? { user: resolve(repository, value.user) } : {}) });
+    if (catalog.diagnostics.length) {
+      console.error(JSON.stringify({ error: 'Skill catalog contains diagnostics', diagnostics: catalog.diagnostics }));
+      process.exitCode = 1;
+      return;
+    }
+    selectedSkills = value.requirements.map(requirement => {
+      if (!requirement || typeof requirement.name !== 'string') throw new Error('Invalid skill requirement');
+      return requireSkill(catalog, requirement.name, requirement);
+    });
+  }
+  const workflow = await LocalValidation.open(repository, manifest.base, flowType);
+  await workflow.settleContracts(manifest.contracts as ContractDecision[]);
+  await workflow.recordImplementation(manifest.implementation);
+  const snapshot = await workflow.validate(manifest.validations as ValidationEntry[]);
+  const readiness = await workflow.readiness();
+  console.log(JSON.stringify({ ...snapshot, selectedSkills, readiness }));
+  if (!readiness.ready) process.exitCode = 1;
+}
+main().catch(error => { console.error(JSON.stringify({ error: error instanceof Error ? error.message : 'Workflow failed' })); process.exitCode = 1; });

package/src/workflow/index.ts

@@ -0,0 +1,2 @@
+export * from './skills.ts';
+export * from './local.ts';

package/src/workflow/local.ts

@@ -0,0 +1,162 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile, realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { GitAdapter } from '../git.ts';
+import { runProcess } from '../runtime/process.ts';
+
+export type LocalStage = 'durable-contracts' | 'delivery-slices' | 'validation' | 'locally-validated';
+export type FlowType = 'normal' | 'fast-track' | 'local-merge';
+export interface ContractDecision { kind: 'spec' | 'adr'; disposition: 'link' | 'not-needed'; reason: string; paths: string[] }
+export interface ValidationEntry { id: string; command: string; args: string[]; required?: boolean; timeoutMs?: number; maxOutputBytes?: number }
+export interface ValidationReceipt {
+  id: string; entry: ValidationEntry; repository: string; base: string; head: string;
+  startedAt: string; finishedAt: string; status: 'passed' | 'failed' | 'interrupted';
+  code: number | null; signal: NodeJS.Signals | null; stdout: string; stderr: string;
+  error: string | null; outputDigest: string; candidateUnchanged: boolean;
+}
+export interface WorkflowSnapshot {
+  flowType: FlowType; repository: string; branch: string; base: string; stage: LocalStage;
+  contracts: { decision: ContractDecision; files: { path: string; digest: string }[] }[];
+  implementation: string | null; validationHead: string | null; receipts: ValidationReceipt[];
+}
+function nonempty(value: unknown): value is string { return typeof value === 'string' && value.trim().length > 0; }
+function digest(value: string | Buffer): string { return createHash('sha256').update(value).digest('hex'); }
+
+/** Local stages only; callers own persistence and integration with task ledgers.
+ * No push, PR, merge, release, formal review, or global Skill mutation. */
+export class LocalValidation {
+  private busy = false;
+  private constructor(private state: WorkflowSnapshot) {}
+  static async open(repository: string, baseRef: string, flowType: FlowType = 'normal'): Promise<LocalValidation> {
+    if (!['normal', 'fast-track', 'local-merge'].includes(flowType)) throw new Error('Invalid flow type');
+    if (!nonempty(baseRef) || baseRef.startsWith('-')) throw new Error('Explicit base required');
+    const current = await new GitAdapter(repository).inspect();
+    if (!current.branch || ['main', 'master'].includes(current.branch)) throw new Error('Topic branch required');
+    if (current.dirty) throw new Error('Clean candidate required; preserve existing changes');
+    const result = await runProcess('git', ['-C', current.root, 'rev-parse', '--verify', `${baseRef}^{commit}`]);
+    if (result.code !== 0) throw new Error('Unable to resolve base');
+    const base = result.stdout.trim();
+    const ancestor = await runProcess('git', ['-C', current.root, 'merge-base', '--is-ancestor', base, current.head]);
+    if (ancestor.code !== 0) throw new Error('Base must be an ancestor of candidate');
+    return new LocalValidation({ flowType, repository: await realpath(current.root), branch: current.branch, base,
+      stage: 'durable-contracts', contracts: [], implementation: null, validationHead: null, receipts: [] });
+  }
+  snapshot(): WorkflowSnapshot { return structuredClone(this.state); }
+  private async exclusive<T>(operation: () => Promise<T>): Promise<T> {
+    if (this.busy) throw new Error('Workflow operation in progress');
+    this.busy = true;
+    try { return await operation(); } finally { this.busy = false; }
+  }
+  private async candidate(): Promise<string> {
+    const current = await new GitAdapter(this.state.repository).inspect();
+    if (await realpath(current.root) !== this.state.repository || current.branch !== this.state.branch || current.dirty) throw new Error('Candidate changed or is dirty');
+    const ancestor = await runProcess('git', ['-C', this.state.repository, 'merge-base', '--is-ancestor', this.state.base, current.head]);
+    if (ancestor.code !== 0) throw new Error('Candidate no longer descends from base');
+    return current.head;
+  }
+  private async contractFile(path: string): Promise<string> {
+    if (!nonempty(path) || isAbsolute(path)) throw new Error('Contract paths must be repository-relative');
+    const actual = await realpath(resolve(this.state.repository, path));
+    const rel = relative(this.state.repository, actual);
+    if (!rel || rel === '..' || rel.startsWith('../') || isAbsolute(rel)) throw new Error('Contract escapes repository');
+    return digest(await readFile(actual));
+  }
+  private async checkContracts(): Promise<void> {
+    for (const item of this.state.contracts) for (const file of item.files) {
+      if (await this.contractFile(file.path) !== file.digest) throw new Error('Contract changed; settle contracts again');
+    }
+  }
+  /** Caller settles design decisions; references record evidence, never invent approval. */
+  async settleContracts(decisions: ContractDecision[]): Promise<WorkflowSnapshot> {
+    return this.exclusive(async () => {
+      await this.candidate();
+      if (!Array.isArray(decisions) || decisions.length !== 2 || decisions.some(d => !d) || new Set(decisions.map(d => d.kind)).size !== 2) throw new Error('Spec and ADR dispositions required');
+      const contracts: WorkflowSnapshot['contracts'] = [];
+      for (const decision of structuredClone(decisions)) {
+        if (!['spec', 'adr'].includes(decision.kind) || !['link', 'not-needed'].includes(decision.disposition) || !nonempty(decision.reason) || !Array.isArray(decision.paths) || decision.paths.some(p => !nonempty(p))) throw new Error('Invalid contract disposition');
+        if ((decision.disposition === 'link') !== (decision.paths.length > 0)) throw new Error('Linked contracts require paths; not-needed requires none');
+        const files = [];
+        for (const path of decision.paths) files.push({ path, digest: await this.contractFile(path) });
+        contracts.push({ decision, files });
+      }
+      this.state.contracts = contracts; this.state.implementation = null;
+      this.state.validationHead = null; this.state.receipts = []; this.state.stage = 'delivery-slices';
+      return this.snapshot();
+    });
+  }
+  async recordImplementation(detail: string): Promise<WorkflowSnapshot> {
+    return this.exclusive(async () => {
+      if (this.state.stage !== 'delivery-slices') throw new Error('Settle contracts before implementation');
+      if (!nonempty(detail)) throw new Error('Implementation evidence required');
+      await this.candidate(); await this.checkContracts();
+      this.state.implementation = detail; this.state.stage = 'validation';
+      return this.snapshot();
+    });
+  }
+  /** Explicit commands only, without shell expansion. New calls rerun the suite. */
+  async validate(entries: ValidationEntry[], signal?: AbortSignal): Promise<WorkflowSnapshot> {
+    return this.exclusive(async () => {
+      if (!this.state.implementation || !['validation', 'locally-validated'].includes(this.state.stage)) throw new Error('Implementation evidence required before validation');
+      if (!Array.isArray(entries) || entries.length === 0) throw new Error('Validation entries required');
+      const suite = structuredClone(entries), ids = new Set<string>();
+      for (const entry of suite) {
+        if (!entry || !nonempty(entry.id) || ids.has(entry.id) || !nonempty(entry.command) || !Array.isArray(entry.args) || entry.args.some(a => typeof a !== 'string') || (entry.required !== undefined && typeof entry.required !== 'boolean')) throw new Error('Invalid or duplicate validation entry');
+        ids.add(entry.id);
+        if ((entry.timeoutMs !== undefined && (!Number.isSafeInteger(entry.timeoutMs) || entry.timeoutMs < 1 || entry.timeoutMs > 1_800_000)) || (entry.maxOutputBytes !== undefined && (!Number.isSafeInteger(entry.maxOutputBytes) || entry.maxOutputBytes < 1 || entry.maxOutputBytes > 64 * 1024 * 1024))) throw new Error('Invalid validation limits');
+      }
+      this.state.stage = 'validation'; this.state.validationHead = null; this.state.receipts = [];
+      const head = await this.candidate();
+      try { await this.checkContracts(); }
+      catch (error) { this.state.stage = 'durable-contracts'; throw error; }
+      for (const entry of suite) {
+        if (signal?.aborted) break;
+        const startedAt = new Date().toISOString();
+        let code: number | null = null, childSignal: NodeJS.Signals | null = null;
+        let stdout = '', stderr = '', error: string | null = null;
+        let status: ValidationReceipt['status'] = 'failed';
+        try {
+          if (await this.candidate() !== head) throw new Error('Candidate moved during validation');
+          const result = await runProcess(entry.command, entry.args, {
+            cwd: this.state.repository, timeoutMs: entry.timeoutMs ?? 30_000,
+            maxOutputBytes: entry.maxOutputBytes ?? 1024 * 1024, ...(signal ? { signal } : {}),
+          });
+          ({ code, stdout, stderr } = result); childSignal = result.signal;
+          status = code === 0 && childSignal === null ? 'passed' : 'failed';
+        } catch (cause) {
+          error = cause instanceof Error ? cause.message : 'Validation execution failed';
+          status = signal?.aborted ? 'interrupted' : 'failed';
+        }
+        let candidateUnchanged = false;
+        try { candidateUnchanged = await this.candidate() === head; await this.checkContracts(); }
+        catch { candidateUnchanged = false; }
+        if (!candidateUnchanged) { status = 'failed'; error = 'Candidate or contracts changed during validation'; }
+        this.state.receipts.push({ id: randomUUID(), entry, repository: this.state.repository,
+          base: this.state.base, head, startedAt, finishedAt: new Date().toISOString(), status,
+          code, signal: childSignal, stdout, stderr, error, outputDigest: digest(JSON.stringify([stdout, stderr])), candidateUnchanged });
+        if (!candidateUnchanged || signal?.aborted) break;
+      }
+      const required = suite.filter(entry => entry.required !== false);
+      if (required.length > 0 && this.state.receipts.length === suite.length && this.state.receipts.every(receipt => receipt.candidateUnchanged) && required.every(entry => this.state.receipts.some(receipt => receipt.entry.id === entry.id && receipt.status === 'passed'))) {
+        this.state.validationHead = head; this.state.stage = 'locally-validated';
+      }
+      return this.snapshot();
+    });
+  }
+  async readiness(): Promise<{ ready: boolean; firstUnfinishedGate: LocalStage; reason: string | null }> {
+    return this.exclusive(async () => {
+      if (this.state.stage !== 'locally-validated') return { ready: false, firstUnfinishedGate: this.state.stage, reason: null };
+      try {
+        if (await this.candidate() !== this.state.validationHead) throw new Error('Validation HEAD is stale');
+        try { await this.checkContracts(); }
+        catch (error) {
+          this.state.stage = 'durable-contracts'; this.state.validationHead = null;
+          return { ready: false, firstUnfinishedGate: 'durable-contracts', reason: error instanceof Error ? error.message : 'Contract unavailable' };
+        }
+        return { ready: true, firstUnfinishedGate: 'locally-validated', reason: null };
+      } catch (error) {
+        this.state.stage = 'validation'; this.state.validationHead = null;
+        return { ready: false, firstUnfinishedGate: 'validation', reason: error instanceof Error ? error.message : 'Candidate unavailable' };
+      }
+    });
+  }
+}

package/src/workflow/skills.ts

@@ -0,0 +1,148 @@
+import { createHash } from 'node:crypto';
+import { readFile, readdir, realpath } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+export type SkillScope = 'project' | 'user';
+export interface Skill {
+  name: string;
+  description: string;
+  content: string;
+  path: string;
+  scope: SkillScope;
+  version: string | null;
+  digest: string;
+}
+export interface SkillCatalog {
+  skills: Skill[];
+  diagnostics: { name: string; scope: SkillScope; message: string }[];
+}
+export interface SkillRoots { project: string; user?: string }
+const namePattern = /^[a-z0-9][a-z0-9-]*$/;
+const versionPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+function versionParts(version: string): number[] {
+  if (!versionPattern.test(version)) throw new Error(`Unsupported version: ${version}`);
+  const parts = version.split('.').map(Number);
+  if (parts.some(value => !Number.isSafeInteger(value))) throw new Error('Version component exceeds safe integer');
+  return parts;
+}
+function compare(a: number[], b: number[]): number {
+  for (let i = 0; i < 3; i++) { if (a[i] !== b[i]) return a[i]! < b[i]! ? -1 : 1; }
+  return 0;
+}
+/** Deliberately small range grammar: *, exact, ^, ~, or whitespace-separated comparators. */
+export function satisfiesVersion(version: string, range: string): boolean {
+  const actual = versionParts(version);
+  if (range === '*') return true;
+  const terms = range.trim().split(/\s+/);
+  if (!range.trim()) throw new Error('Empty version range');
+  // Parse all terms before comparing, so malformed suffixes never silently pass.
+  const checks = terms.map(term => {
+    const match = /^(\^|~|>=|<=|>|<|=)?(\d+\.\d+\.\d+)$/.exec(term);
+    if (!match) throw new Error(`Unsupported version range: ${range}`);
+    const target = versionParts(match[2]!);
+    const operator = match[1] ?? '=';
+    const order = compare(actual, target);
+    switch (operator) {
+      case '=': return order === 0;
+      case '>': return order > 0;
+      case '>=': return order >= 0;
+      case '<': return order < 0;
+      case '<=': return order <= 0;
+      case '~': return order >= 0 && actual[0] === target[0] && actual[1] === target[1];
+      case '^': {
+        const fixed = target[0] !== 0 ? 1 : target[1] !== 0 ? 2 : 3;
+        return order >= 0 && actual.slice(0, fixed).every((value, i) => value === target[i]);
+      }
+      default: throw new Error('Unsupported version operator');
+    }
+  });
+  return checks.every(Boolean);
+}
+
+// Skill bodies remain opaque Markdown. Only the conventional name and description
+// scalar fields are read; machine compatibility lives in a separate JSON sidecar.
+function metadata(content: string): { name: string; description: string } {
+  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
+  if (!frontmatter) throw new Error('SKILL.md requires frontmatter');
+  const scalar = (key: string): string => {
+    const matches = [...frontmatter[1]!.matchAll(new RegExp(`^${key}:\\s*(.+)$`, 'gm'))];
+    if (matches.length !== 1) throw new Error(`Expected one ${key} scalar`);
+    const value = matches[0]![1]!.trim();
+    if (value.startsWith('"')) {
+      const parsed: unknown = JSON.parse(value);
+      if (typeof parsed !== 'string' || !parsed.trim()) throw new Error(`Invalid ${key}`);
+      return parsed;
+    }
+    if (value.startsWith("'")) {
+      if (!value.endsWith("'")) throw new Error(`Invalid ${key}`);
+      return value.slice(1, -1).replaceAll("''", "'");
+    }
+    if (/^[>|[{&*!]/.test(value)) throw new Error(`Unsupported ${key} scalar`);
+    return value;
+  };
+  const name = scalar('name'), description = scalar('description');
+  if (!namePattern.test(name) || !description.trim()) throw new Error('Invalid skill identity');
+  return { name, description };
+}
+
+async function optionalText(path: string): Promise<string | null> {
+  try { return await readFile(path, 'utf8'); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null; throw error; }
+}
+
+/** Roots are explicit skill directories, e.g. <repo>/.agents/skills and ~/.agents/skills.
+ * Symlinked skill packages are supported; nothing is written or executed. */
+export async function loadSkills(roots: SkillRoots): Promise<SkillCatalog> {
+  const result: SkillCatalog = { skills: [], diagnostics: [] };
+  const claimed = new Set<string>();
+  for (const scope of ['project', 'user'] as const) {
+    const root = roots[scope];
+    if (!root) continue;
+    let entries;
+    try { entries = await readdir(resolve(root), { withFileTypes: true }); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue; throw error; }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if ((!entry.isDirectory() && !entry.isSymbolicLink()) || !namePattern.test(entry.name)) continue;
+      if (claimed.has(entry.name)) continue;
+      claimed.add(entry.name); // An invalid project override must not fall back to a user skill.
+      try {
+        const path = await realpath(join(root, entry.name, 'SKILL.md'));
+        const content = await readFile(path, 'utf8');
+        const fields = metadata(content);
+        if (fields.name !== entry.name) throw new Error('Skill name must match its directory');
+        const sidecar = await optionalText(join(root, entry.name, 'loomhelm.json'));
+        let version: string | null = null;
+        if (sidecar !== null) {
+          const data: unknown = JSON.parse(sidecar);
+          if (!data || typeof data !== 'object' || Array.isArray(data)) throw new Error('Invalid skill manifest');
+          const value = data as Record<string, unknown>;
+          if (value.schemaVersion !== 1 || Object.keys(value).some(key => !['schemaVersion', 'version', 'scopes'].includes(key))) throw new Error('Unsupported skill manifest');
+          if (value.version !== undefined) {
+            if (typeof value.version !== 'string') throw new Error('Invalid skill version');
+            versionParts(value.version); version = value.version;
+          }
+          if (!Array.isArray(value.scopes) || value.scopes.length === 0 || value.scopes.some(s => s !== 'project' && s !== 'user')) throw new Error('Invalid skill scopes');
+          if (!value.scopes.includes(scope)) throw new Error(`Skill is not applicable to ${scope} scope`);
+        }
+        result.skills.push({ ...fields, content, path, scope, version, digest: createHash('sha256').update(JSON.stringify([content, sidecar])).digest('hex') });
+      } catch (error) {
+        result.diagnostics.push({ name: entry.name, scope, message: error instanceof Error ? error.message : 'Unable to load skill' });
+      }
+    }
+  }
+  return result;
+}
+
+export function requireSkill(catalog: SkillCatalog, name: string, options: { range?: string; scopes?: readonly SkillScope[] } = {}): Skill {
+  if (options.range !== undefined && typeof options.range !== 'string') throw new Error('Invalid version range');
+  if (options.scopes !== undefined && (!Array.isArray(options.scopes) || options.scopes.length === 0 || options.scopes.some(scope => scope !== 'project' && scope !== 'user'))) throw new Error('Invalid required scopes');
+  const skill = catalog.skills.find(item => item.name === name);
+  if (!skill) throw new Error(`Skill unavailable: ${name}`);
+  if (options.scopes && !options.scopes.includes(skill.scope)) throw new Error(`Skill scope mismatch: ${name}`);
+  if (options.range !== undefined) {
+    if (skill.version === null) throw new Error(`Skill version unknown: ${name}`);
+    if (!satisfiesVersion(skill.version, options.range)) throw new Error(`Skill version mismatch: ${name}`);
+  }
+  return structuredClone(skill);
+}

package/toolkit/AGENTS.md

@@ -0,0 +1,47 @@
+# Loomhelm engineering guide
+
+## Product and scope
+
+Loomhelm is a self-hosted project management Web/PWA and remote Codex workspace for individuals and small teams. Read `docs/PRD.md` for the complete product scope, user journeys, business decisions and acceptance, then `docs/specs/phase1-core/SPEC.md` for established engineering contracts. Read its companions for implementation coverage and compatibility history. The main coordinator maintains the PRD and synchronizes confirmed product decisions into the engineering contracts; design context is supporting material. Resolve contradictions before implementation. Task scheduling and coordination stay outside the repository.
+
+The backend is Go with chi, PostgreSQL, pgx/sqlc, goose and River. Server, Worker and Connector are separate processes. React/Vite/TypeScript, Bun workspaces, TanStack Router/Query, shadcn/Tailwind and Storybook form the frontend. Bun is not the business backend runtime. The independent TypeScript client lives in `clients/typescript/`, requires Bun 1.4.4 and runs TypeScript source directly, and does not replace the Go Connector. The default integration branch is `main`; begin work from a freshly verified complete mainline rather than a partial or historical topic branch.
+
+Business feature implementation and public business contract finalization require the owner's explicit confirmation of the phase-one PRD and resolution of the affected business decisions. Proposed defaults in the PRD are not approval. Engineering skeletons, infrastructure, capability research and the existing design discussion may proceed independently. Product UI implementation additionally requires the owner's approval of the complete UI design. There is exactly one complete UI design task; information architecture, prototype, visual design and handoff are internal steps of that task. Before UI approval, frontend work remains limited to the technical framework, neutral verification surfaces and that design task's prototypes.
+
+## Working conventions
+
+- Communicate with the owner in Chinese; use English code, identifiers and conventional commit subjects. Every commit requires `--signoff`; never bypass hooks.
+- Read actual files and current Git state first. Preserve unrelated user changes and local configuration. Shared manifests, lockfiles and composition roots have one integration owner; sibling work must remain in its declared paths.
+- Delegated implementation, research, design and advisory review must use `gpt-5.6-luna` with `max`. Formal runtime review must use `gpt-6-luna` with `max`. Select the profile by role; task difficulty, risk, duration or a failed attempt does not authorize a different profile. If the required profile is unavailable, report a blocker rather than substituting another profile.
+- Use the existing shared engineering workflow for PR publication, review, checks and merge. Child PRs target the designated parent branch directly; the owner controls the final parent PR merge. GitHub operations use `gh`; do not change remotes, upstreams, credentials or branch rules without explicit authorization.
+- Keep new topic requirements in `docs/specs/<topic>/SPEC.md` with `IMPLEMENTATION.md` and `HISTORY.md`. Record hard-to-reverse architecture decisions in `docs/adr/`. Do not commit orchestration manifests, task boards, conversation state or temporary implementation plans.
+- Keep each Markdown prose paragraph on one source line. Formatting uses the installed markdown-style Policy, pinned dprint and the canonical Lefthook path; do not infer a paragraph width from formatter settings.
+
+## Skill 源码维护
+
+- 在本仓库中请求优化、修复或补充本项目提供的 Skill 时，默认维护目标是当前工作区内的源码。用户通过 `$skill-name`、Skill 链接或绝对路径引用全局安装版本，只表示要处理的 Skill 身份；即使 Agent 自动加载了全局 `SKILL.md`，也不代表授权编辑该安装副本。例如，引用全局 `fast-flow/SKILL.md` 请求优化时，应定位本仓库 `skills/fast-flow/`。
+- 写入前先按 Skill 名称、`skills/README.md`、`skills/catalog.json`、`skills/source-manifest.json` 和实际内容核实源码映射，再读取仓库内对应 `SKILL.md` 及受影响的关联资源。全局版本可用于识别和比较；若版本有差异，以仓库当前合同为修改基线，不能把安装副本整份覆盖回仓库，也不能仅凭全局文档中的相对路径或运行根目录决定编辑位置。
+- 修改应落在 `skills/<skill-name>/` 及确有影响的 `skills/bin/`、模板、references、资源清单或检查入口，并遵循仓库已有的资源登记、摘要更新和验证要求。修改前解析符号链接并确认实际写入路径位于当前仓库工作区；不得通过链接意外写入全局安装目录、vendor checkout 或其他工作区。
+- 区分根 `skills/` 的自有源包、`.agents/skills/` 的项目 Policy 安装面，以及由其他仓库维护的外部 Skill；同名不等于同源。若本仓库没有对应维护源或映射存在歧义，先报告已确认的来源与缺失信息，再由主人确认目标，不得猜测路径或直接改全局版本。
+- 源码优化与安装升级是独立操作。更新、重装全局 Skill，或同步用户级脚本、服务和运行资源，须有覆盖该操作的主人明确授权。交付时说明实际修改的仓库路径、验证结果，以及全局安装版本是否已更新；只完成源码修改时，不得声称用户正在使用的全局版本已经生效。
+
+## Policy routing
+
+- Development previews: `.agents/skills/development-preview/SKILL.md`; read after interactive Web UI changes or when the owner requests a development preview.
+- Markdown edits and hooks: `.agents/skills/markdown-style/SKILL.md`.
+- Fresh worktrees, setup and local resource recovery: `.agents/skills/worktree-bootstrap/SKILL.md`.
+- CI, required checks, waivers and delivery gates: `.agents/skills/quality-gates/SKILL.md`.
+- Durable database, journal, queue or artifact state: `.agents/skills/persistent-state-migrations/SKILL.md`.
+- Public interface or persistent-state compatibility changes: `.agents/skills/semver-change-governance/SKILL.md`.
+- Expected-success workflow failures: `.agents/skills/release-failure-notification/SKILL.md`; installing this Policy does not select a notification provider, destination or credential.
+- Viewer 兼容维护遵循 `docs/adr/0026-viewer-compatibility-lifecycle.md`：最新 viewer 双读受支持历史格式，旧 viewer 仅作隔离只读兜底；自动迁移仅限机械、无语义推断且可恢复的转换，历史内容不自动清理。兼容代码清理是独立的 release-level 决策，历史格式、迁移、兜底和拒绝路径测试必须保留。
+
+## Verification and runtime
+
+- Use a session-owned Agent VM for Linux, Docker/Compose, image builds, integration/E2E and heavy validation. Local Docker is disabled. Follow the installed agent-vm protocol and lease contract; each task session owns its own VM.
+- Multi-task-flow dashboard delivery and inspection use the current host’s available built-in browser first, including ChatGPT Desktop and Codex Desktop. This specific route overrides the generic ego-browser preference for this dashboard only; follow `skills/multi-task-flow/SKILL.md` for capability checks, fallback and delivery verification.
+- Lease and register ports before starting long-lived local services. Never reuse or stop an unrelated listener.
+- UI components and reusable states require Storybook coverage; full-page evidence prefers a deterministic, login-free `ui_demo`. Follow ui-visual-evidence for controlled capture, immutable chat snapshots and owner confirmation. Real-program screenshots require explicit target and scope authorization.
+- Codex verification uses disposable test directories and sessions. Keep Codex credentials on the host. Do not equate reading history, resuming a copy or opening another process with controlling an existing active desktop session.
+- REST and MCP share application behavior, project permissions, command identity and approval semantics. Persist commands and events; reconcile ambiguous delivery instead of blindly repeating side effects.
+- Blue-green readiness, HTTP drain, Worker generation/fencing, Connector recovery and durable-state compatibility are separate gates. Candidate identity is the actual source SHA plus digest. Do not rebuild during promotion, automatically reverse deployed migrations or claim safe rollback beyond the demonstrated compatibility window.