docs(validation): update agent configs, skills, ADRs, specs

- qa-tester: add validation v2 testing checklist
- speckit.plan: add component reuse scan for frontend
- molecular-cot-logging: add Svelte logger + CLI reader
- semantics-svelte: add RSM model-first protocol, frontend stack
- templates: update plan/tasks/ux-reference templates
- ADR-0004: add llm_dashboard_validation plugin registration
- ADR-0008: add assistant tool registry for v2 validation
- Specs: update 017 tasks from 51 to 99
This commit is contained in:
2026-05-31 22:32:32 +03:00
parent 40c9f849b2
commit 05ef6cdff8
10 changed files with 241 additions and 223 deletions

View File

@@ -260,70 +260,67 @@ def _summarise_args(args, kwargs) -> dict:
## V. Svelte / Frontend Pattern
```javascript
// ── trace-id from HTTP response header ──────────────────────
let _traceId = $state("");
The frontend implementation lives at `frontend/src/lib/cot-logger.ts` (installed as `$lib/cot-logger`).
export function initTraceId() {
// Called once from root layout after first fetch
}
### API
export function setTraceId(id) { _traceId = id; }
export function getTraceId() { return _traceId; }
```typescript
function log(
src: string, // e.g. "MigrationModel.executeMigration"
marker: LogMarker, // "REASON" | "REFLECT" | "EXPLORE"
intent: string, // human-readable one-liner
payload?: Record<string, unknown>, // params, result snippet
error?: string, // required for EXPLORE
): void;
```
// ── Component-level CoT logger ──────────────────────────────
export function log(src, marker, intent, payload, error) {
const record = {
ts: new Date().toISOString(),
level: marker === "EXPLORE" ? "WARNING" : "INFO",
trace_id: _traceId || "no-trace",
src,
marker,
intent,
};
if (payload) record.payload = payload;
if (error) record.error = error;
### Import
const line = JSON.stringify(record);
if (marker === "EXPLORE") {
console.warn(line);
} else {
console.info(line);
}
}
```typescript
import { log, setTraceId, getTraceId } from "$lib/cot-logger";
```
### Usage in a Svelte component
```svelte
<script>
<script lang="ts">
import { log } from "$lib/cot-logger";
import { fetchApi } from "$lib/api";
import { page } from "$app/stores";
let { jobId } = $props();
let { jobId }: { jobId: string } = $props();
async function loadJob() {
log("JobDetail.loadJob", "REASON", "Fetch job details", { jobId });
async function loadJob(): Promise<void> {
log("JobDetail", "REASON", "Fetch job details", { jobId });
try {
const resp = await fetchApi(`/api/jobs/${jobId}`);
if (!resp.ok) throw new Error(`Status ${resp.status}`);
const data = await resp.json();
log("JobDetail.loadJob", "REFLECT", "Job details loaded",
log("JobDetail", "REFLECT", "Job details loaded",
{ rows: data.records?.length });
return data;
} catch (e) {
log("JobDetail.loadJob", "EXPLORE", "Failed to load job",
{ jobId }, error = e.message);
} catch (e: unknown) {
log("JobDetail", "EXPLORE", "Failed to load job",
{ jobId }, e instanceof Error ? e.message : "Unknown");
throw e;
}
}
</script>
```
### trace_id Propagation
The trace ID is set automatically when the backend returns it. Call `setTraceId(id)` manually if needed:
```typescript
import { setTraceId } from "$lib/cot-logger";
import { requestApi } from "$lib/api";
const res = await requestApi("/api/endpoint");
if (res.trace_id) setTraceId(res.trace_id);
```
## VI. CLI / Stdout Reader (for humans)
To make JSON lines readable in development:

View File

@@ -277,6 +277,21 @@ search_contracts query="users" type="Model"
Frontend logging uses `log()` from `$lib/cot-logger`, emitting **JSON lines** per MolecularCoTLogging protocol.
Import: `import { log } from "$lib/cot-logger";`
The logger is a TypeScript module at `frontend/src/lib/cot-logger.ts` with full type support:
```typescript
import { log } from "$lib/cot-logger";
// Before an operation:
log("ComponentName", "REASON", "What we are about to do", { param: value });
// After successful verification:
log("ComponentName", "REFLECT", "Operation completed", { result: value });
// On error or fallback:
log("ComponentName", "EXPLORE", "Operation failed", { param: value }, "Error description");
```
### Marker Reference
| Marker | When | Signature |