@hadooppei/hwcode 0.1.0

package/.pi/lib/workflow-guard.ts

@@ -0,0 +1,99 @@
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+
+export interface GuardEnvironment {
+	home?: string;
+	tmpdir?: string;
+}
+
+export interface ExternalPathReference {
+	raw: string;
+	resolved: string;
+}
+
+function realpathWithMissingTail(path: string): string {
+	const tail: string[] = [];
+	let cursor = resolve(path);
+
+	while (!existsSync(cursor)) {
+		const parent = dirname(cursor);
+		if (parent === cursor) return resolve(path);
+		tail.unshift(cursor.slice(parent.length + (parent.endsWith(sep) ? 0 : 1)));
+		cursor = parent;
+	}
+
+	return resolve(realpathSync(cursor), ...tail);
+}
+
+export function canonicalizeWorkspaceRoot(root: string): string {
+	return realpathWithMissingTail(root);
+}
+
+export function resolveToolPath(root: string, rawPath: string, home?: string): string {
+	const expanded = rawPath === "~" || rawPath.startsWith(`~${sep}`)
+		? resolve(home ?? root, rawPath.slice(2))
+		: rawPath;
+	return realpathWithMissingTail(isAbsolute(expanded) ? expanded : resolve(root, expanded));
+}
+
+export function isPathInsideRoot(root: string, candidate: string): boolean {
+	const relation = relative(canonicalizeWorkspaceRoot(root), realpathWithMissingTail(candidate));
+	return relation === "" || (!relation.startsWith(`..${sep}`) && relation !== ".." && !isAbsolute(relation));
+}
+
+function stripTrailingShellPunctuation(value: string): string {
+	return value.replace(/[\]}),;]+$/g, "");
+}
+
+function addExternalReference(
+	result: Map<string, ExternalPathReference>,
+	root: string,
+	raw: string,
+	resolved: string,
+): void {
+	const cleanResolved = realpathWithMissingTail(stripTrailingShellPunctuation(resolved));
+	if (!isPathInsideRoot(root, cleanResolved)) {
+		result.set(`${raw}\0${cleanResolved}`, { raw, resolved: cleanResolved });
+	}
+}
+
+/**
+ * Find paths that a shell command explicitly names outside the workflow root.
+ * This is intentionally conservative; it is an approval gate, not a shell sandbox.
+ */
+export function findExternalPathReferences(
+	command: string,
+	root: string,
+	environment: GuardEnvironment = {},
+): ExternalPathReference[] {
+	const result = new Map<string, ExternalPathReference>();
+	const canonicalRoot = canonicalizeWorkspaceRoot(root);
+	const home = environment.home;
+	const tmpdir = environment.tmpdir ?? "/tmp";
+
+	for (const match of command.matchAll(/\$\{?HOME\}?((?:\/[\w.@%+=:,~-]+)*)/g)) {
+		if (home) addExternalReference(result, canonicalRoot, match[0], resolve(home, `.${match[1] ?? ""}`));
+	}
+	for (const match of command.matchAll(/\$\{?TMPDIR\}?((?:\/[\w.@%+=:,~-]+)*)/g)) {
+		addExternalReference(result, canonicalRoot, match[0], resolve(tmpdir, `.${match[1] ?? ""}`));
+	}
+	for (const match of command.matchAll(/(?:^|[\s"'`=(:,<>])(~(?:\/[\w.@%+=:,~-]+)*)/g)) {
+		if (home) addExternalReference(result, canonicalRoot, match[1], resolveToolPath(canonicalRoot, match[1], home));
+	}
+
+	for (const match of command.matchAll(/(?:^|[\s"'`=(:,<>])((?:\/(?!\/)[^\s"'`|&;]+))/g)) {
+		const raw = stripTrailingShellPunctuation(match[1]);
+		addExternalReference(result, canonicalRoot, raw, raw);
+	}
+
+	for (const match of command.matchAll(/(?:^|[\s"'`=(:,<>])((?:\.\.\/)+[^\s"'`|&;]*)/g)) {
+		const raw = stripTrailingShellPunctuation(match[1]);
+		addExternalReference(result, canonicalRoot, raw, resolve(canonicalRoot, raw));
+	}
+
+	if (/\bmktemp\b/.test(command)) {
+		addExternalReference(result, canonicalRoot, "mktemp(default)", tmpdir);
+	}
+
+	return [...result.values()];
+}

package/.pi/lib/working-directory.ts

@@ -0,0 +1,252 @@
+import { realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+
+export const WORKING_DIRECTORY_STATE_TYPE = "hwcode-working-directory";
+
+interface SessionEntry {
+	type: string;
+	customType?: string;
+	data?: unknown;
+}
+
+interface SessionDirectorySource {
+	getCwd(): string;
+	getEntries(): readonly SessionEntry[];
+	getSessionId(): string;
+}
+
+export interface WorkingDirectoryState {
+	version: 1;
+	cwd: string;
+	previousCwd?: string;
+}
+
+export interface DirectoryChange {
+	argument: string;
+	remainder: string;
+}
+
+export interface ChainedDirectoryChange {
+	argument: string;
+	standalone: boolean;
+}
+
+const workingDirectories = new Map<string, WorkingDirectoryState>();
+
+function isWorkingDirectoryState(value: unknown): value is WorkingDirectoryState {
+	if (!value || typeof value !== "object") return false;
+	const data = value as Record<string, unknown>;
+	return data.version === 1
+		&& typeof data.cwd === "string"
+		&& (data.previousCwd === undefined || typeof data.previousCwd === "string");
+}
+
+export function findPersistedWorkingDirectory(
+	entries: readonly SessionEntry[],
+): WorkingDirectoryState | undefined {
+	for (const entry of [...entries].reverse()) {
+		if (entry.type !== "custom" || entry.customType !== WORKING_DIRECTORY_STATE_TYPE) continue;
+		if (isWorkingDirectoryState(entry.data)) return entry.data;
+	}
+	return undefined;
+}
+
+export function canonicalizeDirectory(path: string): string {
+	const canonical = realpathSync(path);
+	if (!statSync(canonical).isDirectory()) throw new Error(`Not a directory: ${path}`);
+	return canonical;
+}
+
+function initialState(source: SessionDirectorySource): WorkingDirectoryState {
+	const persisted = findPersistedWorkingDirectory(source.getEntries());
+	if (persisted) return { ...persisted, cwd: canonicalizeDirectory(persisted.cwd) };
+	return { version: 1, cwd: canonicalizeDirectory(source.getCwd()) };
+}
+
+export function getWorkingDirectoryState(source: SessionDirectorySource): WorkingDirectoryState {
+	return workingDirectories.get(source.getSessionId()) ?? initialState(source);
+}
+
+export function getWorkingDirectory(source: SessionDirectorySource): string {
+	return getWorkingDirectoryState(source).cwd;
+}
+
+export function setWorkingDirectoryState(
+	source: SessionDirectorySource,
+	state: WorkingDirectoryState,
+): void {
+	workingDirectories.set(source.getSessionId(), state);
+}
+
+export function resetWorkingDirectoryState(source: SessionDirectorySource): WorkingDirectoryState {
+	const state = initialState(source);
+	setWorkingDirectoryState(source, state);
+	return state;
+}
+
+function expandHome(path: string, home: string): string {
+	if (path === "~" || path === "$HOME" || path === "${HOME}") return home;
+	if (path.startsWith("~/")) return resolve(home, path.slice(2));
+	if (path.startsWith("$HOME/")) return resolve(home, path.slice(6));
+	if (path.startsWith("${HOME}/")) return resolve(home, path.slice(8));
+	return path;
+}
+
+export function resolveDirectoryArgument(
+	base: string,
+	argument: string,
+	previousCwd?: string,
+	home = homedir(),
+): string {
+	if (argument === "-") {
+		if (!previousCwd) throw new Error("No previous working directory is available.");
+		return canonicalizeDirectory(previousCwd);
+	}
+	const expanded = expandHome(argument || home, home);
+	return canonicalizeDirectory(isAbsolute(expanded) ? expanded : resolve(base, expanded));
+}
+
+export function resolveWorkingPath(base: string, path: string, home = homedir()): string {
+	const expanded = expandHome(path, home);
+	return isAbsolute(expanded) ? expanded : resolve(base, expanded);
+}
+
+function readShellWord(command: string, start: number): { value: string; end: number } | undefined {
+	let value = "";
+	let quote: "'" | '"' | undefined;
+	let index = start;
+
+	for (; index < command.length; index += 1) {
+		const character = command[index];
+		if (quote) {
+			if (character === quote) {
+				quote = undefined;
+				continue;
+			}
+			if (character === "\\" && quote === '"' && index + 1 < command.length) {
+				index += 1;
+				value += command[index];
+				continue;
+			}
+			value += character;
+			continue;
+		}
+
+		if (character === "'" || character === '"') {
+			quote = character;
+			continue;
+		}
+		if (character === "\\" && index + 1 < command.length) {
+			index += 1;
+			value += command[index];
+			continue;
+		}
+		if (/\s/u.test(character) || character === ";" || character === "&") break;
+		if ("|<>`".includes(character) || character === "$" && command[index + 1] === "(") return undefined;
+		value += character;
+	}
+
+	if (quote || value.length === 0) return undefined;
+	return { value, end: index };
+}
+
+/** Parse a leading persistent `cd`, optionally followed by `&&` or `;`. */
+export function parseLeadingDirectoryChange(command: string): DirectoryChange | undefined {
+	let index = 0;
+	while (/\s/u.test(command[index] ?? "")) index += 1;
+	if (command.slice(index, index + 2) !== "cd") return undefined;
+	const next = command[index + 2];
+	if (next && !/\s/u.test(next) && next !== ";" && command.slice(index + 2, index + 4) !== "&&") {
+		return undefined;
+	}
+	index += 2;
+	while (/\s/u.test(command[index] ?? "")) index += 1;
+	if (command.slice(index, index + 2) === "--") {
+		index += 2;
+		while (/\s/u.test(command[index] ?? "")) index += 1;
+	}
+
+	let argument = "";
+	if (index < command.length && command[index] !== ";" && command.slice(index, index + 2) !== "&&") {
+		const word = readShellWord(command, index);
+		if (!word) return undefined;
+		argument = word.value;
+		index = word.end;
+	}
+	while (/\s/u.test(command[index] ?? "")) index += 1;
+
+	if (index >= command.length) return { argument, remainder: "" };
+	if (command.slice(index, index + 2) === "&&") index += 2;
+	else if (command[index] === ";") index += 1;
+	else return undefined;
+
+	return { argument, remainder: command.slice(index).trimStart() };
+}
+
+/** Find a standalone `cd` segment in a top-level `&&` or `;` command chain. */
+export function findChainedDirectoryChange(command: string): ChainedDirectoryChange | undefined {
+	const segments: string[] = [];
+	let segmentStart = 0;
+	let quote: "'" | '"' | undefined;
+	let escaped = false;
+	let nesting = 0;
+
+	for (let index = 0; index < command.length; index += 1) {
+		const character = command[index];
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (character === "\\" && quote !== "'") {
+			escaped = true;
+			continue;
+		}
+		if (quote) {
+			if (character === quote) quote = undefined;
+			continue;
+		}
+		if (character === "'" || character === '"') {
+			quote = character;
+			continue;
+		}
+		if (character === "(" || character === "{") {
+			nesting += 1;
+			continue;
+		}
+		if (character === ")" || character === "}") {
+			nesting = Math.max(0, nesting - 1);
+			continue;
+		}
+		if (nesting > 0) continue;
+
+		const separatorLength = command.slice(index, index + 2) === "&&" ? 2 : character === ";" ? 1 : 0;
+		if (!separatorLength) continue;
+		segments.push(command.slice(segmentStart, index));
+		index += separatorLength - 1;
+		segmentStart = index + 1;
+	}
+	segments.push(command.slice(segmentStart));
+
+	for (const segment of segments) {
+		const parsed = parseLeadingDirectoryChange(segment);
+		if (parsed && !parsed.remainder) {
+			return { argument: parsed.argument, standalone: segments.length === 1 };
+		}
+	}
+	return undefined;
+}
+
+export function getActiveWorkflowRoot(entries: readonly SessionEntry[]): string | undefined {
+	for (const entry of [...entries].reverse()) {
+		if (entry.type !== "custom" || entry.customType !== "hwcode-workflow-state") continue;
+		if (!entry.data || typeof entry.data !== "object") return undefined;
+		const data = entry.data as Record<string, unknown>;
+		return data.active === true && typeof data.root === "string" ? data.root : undefined;
+	}
+	return undefined;
+}
+
+export function shellQuote(value: string): string {
+	return `'${value.replaceAll("'", `'"'"'`)}'`;
+}

package/.pi/model-providers.json

@@ -0,0 +1,62 @@
+{
+  "providers": [
+    {
+      "id": "local",
+      "name": "Qwen3 VL (8081)",
+      "baseUrl": "http://127.0.0.1:8081",
+      "apiKeyEnv": "PI_LOCAL_MODEL_API_KEY",
+      "models": [
+        {
+          "id": "qwen3-VL:2b",
+          "name": "Qwen3 VL 2B",
+          "input": ["text", "image"],
+          "contextWindow": 32768,
+          "maxTokens": 8192
+        }
+      ]
+    },
+    {
+      "id": "local-8080",
+      "name": "Qwen3.5 9B (8080)",
+      "baseUrl": "http://127.0.0.1:8080",
+      "apiKeyEnv": "PI_LOCAL_MODEL_API_KEY",
+      "models": [
+        {
+          "id": "Qwen3.5-9B-Q4_K_M",
+          "name": "Qwen3.5 9B Q4_K_M",
+          "input": ["text"],
+          "contextWindow": 32768,
+          "maxTokens": 8192
+        }
+      ]
+    },
+    {
+      "id": "hw",
+      "name": "hw",
+      "baseUrl": "http://127.0.0.1:8080/v1",
+      "apiKeyEnv": "HW_API_KEY",
+      "login": {
+        "enabled": true,
+        "promptBaseUrl": true,
+        "promptApiKey": true,
+        "apiKeyRequired": false,
+        "catalogPath": "models",
+        "timeoutMs": 15000
+      },
+      "modelDefaults": {
+        "input": ["text"],
+        "contextWindow": 32768,
+        "maxTokens": 8192
+      },
+      "models": [
+        {
+          "id": "Qwen3.5-9B-Q4_K_M",
+          "name": "Qwen3.5 9B Q4_K_M",
+          "input": ["text"],
+          "contextWindow": 32768,
+          "maxTokens": 8192
+        }
+      ]
+    }
+  ]
+}

package/.pi/skills/hwcode-sdd/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: hwcode-sdd
+description: Run a strict Git-root-locked spec-driven development workflow that inventories a repository, clarifies requirements, produces traceable specification artifacts, designs tests first, and implements with red-green-refactor. Use when the user invokes /hwcode-sdd or explicitly requests specification-led development.
+---
+
+# HWCode SDD
+
+Make the approved specification the source of truth. Move through discovery, specification, planning, tests, implementation, and convergence without skipping uncertainty.
+
+## Enforce activation and phase gates
+
+Confirm that the activation message states a locked project root and Git status. If this skill was invoked directly without the `/hwcode-sdd` project command, do not begin work; ask the user to run `/hwcode-sdd [initial requirement]`. The command confirms the directory, enforces the path boundary, initializes Git when approved, and verifies that the current directory is the repository root.
+
+Use the locked root as the only project workspace. Use in-root paths silently. Explain a genuine external-path need and rely on the one-call approval prompt; never bypass it.
+
+Do not implement production behavior until the user has explicitly approved the requirements and then the design, test plan, and task plan. If later evidence exposes ambiguity, return to the earliest affected artifact and obtain approval again.
+
+## Establish a safe Git baseline
+
+Inspect repository instructions, `.gitignore`, and the reported working tree before the codebase scan.
+
+- If Git was just initialized, inspect all candidate files for credentials, local sessions, generated dependencies, build output, and machine-local configuration. Propose necessary ignore rules. Show the files proposed for staging and a baseline commit message, then obtain explicit approval before staging and committing.
+- If an existing repository is dirty, summarize tracked and untracked changes without overwriting them. Offer a checkpoint commit, continuing with the dirty baseline, or stopping. Record the chosen baseline in the specification metadata.
+- If the tree is clean, continue without creating a commit.
+
+Never stage `.env` files, credentials, tokens, keys, local session data, dependency directories, or generated secrets. Never create a commit without explicit user approval.
+
+## Inventory the repository
+
+Scan read-only before asking for the feature specification. Inspect only relevant levels of:
+
+- project and agent instructions;
+- manifests, entry points, top-level structure, and runtime configuration;
+- business modules and principal data flows;
+- routes, controllers, RPC/GraphQL contracts, schemas, and public interfaces;
+- persistence, authentication, authorization, external services, and background jobs;
+- containers, infrastructure, CI/CD, deployment configuration, and operational hooks;
+- test layout, fixtures, quality commands, and coverage signals.
+
+For a monorepo, summarize the whole repository at the top level and ask which application or package is in scope.
+
+Report findings in this exact table shape, citing file paths as evidence:
+
+| Area | Findings | Evidence |
+|---|---|---|
+| Purpose | ... | ... |
+| Entry points and runtime | ... | ... |
+| Business modules | ... | ... |
+| Routes and APIs | ... | ... |
+| Data and persistence | ... | ... |
+| Integrations | ... | ... |
+| Auth and permissions | ... | ... |
+| Jobs and asynchronous work | ... | ... |
+| Containers and deployment | ... | ... |
+| Tests and tooling | ... | ... |
+| Unknowns and risks | ... | ... |
+
+State when an area is absent or not discoverable. Then ask what requirement the user wants to implement, while retaining any requirement supplied in the activation message.
+
+## Clarify and approve the specification
+
+Separate required behavior and rationale from technical design. Check completeness across:
+
+- actors, user journeys, triggers, inputs, outputs, and state changes;
+- business rules, permissions, validation, failures, edge cases, and recovery;
+- UI/API contracts, data ownership, compatibility, and migration;
+- performance, reliability, security, privacy, accessibility, and observability;
+- rollout, acceptance criteria, non-goals, and explicit out-of-scope behavior.
+
+Do not invent a material product decision. Ask up to five of the most blocking questions per round in a table:
+
+| ID | Question | Why it is needed | Options / recommendation |
+|---|---|---|---|
+
+Use repository evidence to recommend a default when possible. Continue QA rounds until no blocking ambiguity remains. If an expected test outcome is uncertain, treat that as an incomplete requirement and return to QA.
+
+Create `.hwcode/specs/<requirement-slug>/requirements.md` using the template in [spec-artifacts.md](references/spec-artifacts.md). Assign stable `FR-xxx`, `NFR-xxx`, and `AC-xxx` identifiers. Present the completed draft and obtain explicit approval before design work.
+
+## Design and plan tests first
+
+Read [spec-artifacts.md](references/spec-artifacts.md) and create, in order:
+
+1. `design.md` describing current behavior, the chosen architecture, contracts, data flow, errors, security, observability, migration, alternatives, and risks.
+2. `test-plan.md` mapping every acceptance criterion and applicable requirement to automated or explicitly justified manual verification.
+3. `tasks.md` containing dependency-aware tasks with exact target files where known. Put test and fixture tasks before their corresponding implementation tasks.
+
+Maintain a traceability matrix from requirement to acceptance criterion, test, and implementation task. Analyze all four artifacts for contradictions, missing coverage, unresolved markers, and unsupported assumptions. Return upstream to repair gaps. Present the plan and obtain explicit approval before implementation.
+
+## Implement with red-green-refactor
+
+Follow the repository's existing test patterns. If no suitable test framework exists, propose the smallest appropriate setup and obtain approval before adding dependencies.
+
+For each behavior slice:
+
+1. Add or refine the specified test first.
+2. Run it and confirm it fails because the behavior is absent, not because the test is broken.
+3. Implement the minimum production change that satisfies the test and approved design.
+4. Run the focused test until green.
+5. Refactor without changing specified behavior.
+6. Run the broader relevant suite plus available type, lint, build, security, contract, or migration checks.
+7. Update task status and traceability evidence.
+
+Require an explicit waiver, recorded in `requirements.md` and `test-plan.md`, for behavior that cannot reasonably begin with an automated failing test. Never weaken a test merely to make an implementation pass.
+
+## Converge before completion
+
+Compare the approved requirements, design, tests, tasks, and final code. Resolve drift by changing the correct upstream artifact and re-approving material changes. Finish with:
+
+- delivered behavior and non-goals;
+- requirement-to-test-to-code traceability;
+- commands run and results;
+- migrations, operational considerations, residual risks, and follow-ups;
+- Git status and a suggested checkpoint, without committing unless explicitly approved.

package/.pi/skills/hwcode-sdd/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "HWCode SDD"
+  short_description: "Repository-aware spec-driven development workflow"
+  default_prompt: "Use $hwcode-sdd to analyze this repository and drive a tested feature from specification to implementation."

package/.pi/skills/hwcode-sdd/references/spec-artifacts.md

@@ -0,0 +1,161 @@
+# HWCode SDD artifact templates
+
+Keep all artifacts concise, evidence-based, and mutually consistent. Use stable identifiers after assignment; mark superseded requirements instead of silently renumbering them.
+
+## requirements.md
+
+```markdown
+# <Requirement title>
+
+## Metadata
+- Status: Draft | Approved | Superseded
+- Owner: <user or team>
+- Created / updated: <dates>
+- Repository baseline: <commit or explicitly accepted dirty state>
+- Scope: <application/package>
+
+## Problem and context
+<Current behavior, affected users, and why this matters. Cite repository evidence.>
+
+## Goals
+- G-001 ...
+
+## Non-goals
+- NG-001 ...
+
+## Actors and scenarios
+### Scenario S-001: <name>
+<Trigger, primary flow, state changes, and result.>
+
+## Functional requirements
+- FR-001: The system must ...
+
+## Interfaces, API, and data
+<Inputs, outputs, schemas, validation, compatibility, ownership, and migration.>
+
+## Non-functional requirements
+- NFR-001: <measurable security, reliability, performance, privacy, accessibility, or observability constraint>
+
+## Acceptance criteria
+- AC-001 (FR-001)
+  - Given ...
+  - When ...
+  - Then ...
+
+## Edge cases and failure behavior
+- E-001 ...
+
+## Rollout and migration
+<Feature flags, backward compatibility, data migration, rollback, and monitoring.>
+
+## Decisions
+| ID | Decision | Rationale | Date |
+|---|---|---|---|
+
+## Open questions
+- None, or list blocking/non-blocking questions with owners.
+```
+
+Approval gate: no blocking open question remains; behavior is testable; boundaries and non-goals are explicit; the user explicitly approves the document.
+
+## design.md
+
+```markdown
+# Design: <Requirement title>
+
+## Requirements covered
+<FR/NFR/AC identifiers>
+
+## Current behavior and constraints
+<Relevant architecture and repository evidence.>
+
+## Chosen design
+<Components, boundaries, responsibilities, and rationale.>
+
+## Control and data flow
+<Key request/event sequences and state transitions.>
+
+## Contracts and data model
+<API signatures, schemas, persistence, validation, and compatibility.>
+
+## Errors and recovery
+<Failure semantics, retries, idempotency, rollback, and user feedback.>
+
+## Security, privacy, and observability
+<Auth, authorization, secrets, sensitive data, logs, metrics, and alerts.>
+
+## Migration and rollout
+<Ordering, compatibility window, flags, rollback, and cleanup.>
+
+## Alternatives rejected
+| Alternative | Benefit | Reason rejected |
+|---|---|---|
+
+## Risks and mitigations
+| Risk | Likelihood / impact | Mitigation |
+|---|---|---|
+```
+
+Approval gate: every architectural decision traces to an approved requirement; contracts and failures are precise enough to test; the user explicitly approves the design.
+
+## test-plan.md
+
+```markdown
+# Test plan: <Requirement title>
+
+## Strategy and scope
+<Test levels, important boundaries, and exclusions.>
+
+## Environment and fixtures
+<Deterministic setup, data, mocks/fakes, cleanup, and external-path needs.>
+
+## Traceability
+| Test ID | Requirements / AC | Level | Scenario | Expected result | Planned file |
+|---|---|---|---|---|---|
+| T-001 | FR-001, AC-001 | Unit / integration / contract / E2E | ... | ... | ... |
+
+## Failure and boundary coverage
+<Validation, permissions, concurrency, retries, timeouts, empty/large inputs, and regressions as applicable.>
+
+## Non-functional verification
+<Security, performance, reliability, accessibility, privacy, and observability checks.>
+
+## Manual checks and approved waivers
+<Why automation is impractical, exact procedure, expected result, approver, and date. Use "None" by default.>
+
+## Exit criteria
+- Every applicable requirement and acceptance criterion has evidence.
+- Focused and broader relevant checks pass.
+- No unexplained flaky, skipped, weakened, or quarantined test remains.
+```
+
+Approval gate: normal, error, edge, and regression cases are covered; uncertain expected results have returned to requirements QA; the user explicitly approves the plan.
+
+## tasks.md
+
+```markdown
+# Tasks: <Requirement title>
+
+## Execution rules
+- Respect dependencies and phase gates.
+- For each behavior, execute test task before implementation task.
+- Update status and evidence without deleting history.
+
+## Tasks
+- [ ] TASK-001 [FR-001, T-001] Add failing test in `<path>`
+  - Depends on: none
+  - Red evidence: <pending>
+- [ ] TASK-002 [FR-001, T-001] Implement behavior in `<path>`
+  - Depends on: TASK-001
+  - Green evidence: <pending>
+- [ ] TASK-003 [FR-001] Refactor and run broader checks
+  - Depends on: TASK-002
+  - Evidence: <pending>
+
+## Final convergence
+- [ ] All FR/NFR/AC identifiers map to tests and implementation evidence.
+- [ ] Requirements, design, tests, tasks, and code contain no material drift.
+- [ ] Migration, rollout, security, and operational work is complete or explicitly deferred.
+```
+
+Approval gate: tasks are small and dependency-aware; test tasks precede production tasks; file targets and verification commands are concrete where discoverable; the user explicitly approves implementation.