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:
@@ -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:
|
||||
|
||||
@@ -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 |
|
||||
|
||||
Reference in New Issue
Block a user