@geraldmaron/construct 1.0.18 → 1.0.19

package/lib/storage/hybrid-query.mjs

@@ -6,8 +6,24 @@ import { loadStateSnapshot, summarizeStateSnapshot } from './state-source.mjs';
 import { describeSqlStore } from './sql-store.mjs';
 import { describeVectorStore, searchLocalVectorIndex, vectorSearchLocal } from './vector-store.mjs';
 import { createSqlClient, closeSqlClient, readVectorConfig } from './backend.mjs';
-import { scoreByEmbedding } from './embeddings.mjs';
 import { embedText, getEmbeddingModelInfo } from './embeddings-engine.mjs';
+import { floatArrayToPgVector } from './vector-client.mjs';
+import { reciprocalRankFusion } from './rrf.mjs';
+
+// iterative_scan (pgvector >= 0.8.0) keeps a filtered ANN query from
+// under-returning; harmless for the current unfiltered query, and the correct
+// default once tag/metadata filters are added to the vector search.
+
+async function supportsIterativeScan(client) {
+  try {
+    const [row] = await client`SELECT extversion AS v FROM pg_extension WHERE extname = 'vector'`;
+    if (!row?.v) return false;
+    const [major, minor] = String(row.v).split('.').map((n) => parseInt(n, 10));
+    return major > 0 || (major === 0 && minor >= 8);
+  } catch {
+    return false;
+  }
+}
 
 function collectFileCandidates(snapshot) {
   const docs = [];
@@ -104,33 +120,38 @@ export function buildHybridSearchResults(rootDir, query, { limit = 10, env = pro
   };
 }
 
-export async function buildHybridSearchResultsAsync(rootDir, query, { limit = 10, env = process.env } = {}) {
+export async function buildHybridSearchResultsAsync(rootDir, query, { limit = 10, env = process.env, embed = embedText, embeddingModel: modelOverride = null } = {}) {
   const base = buildHybridSearchResults(rootDir, query, { limit, env });
   const client = createSqlClient(env);
   if (!client) return base;
 
   // Resolve the active embedding model so the SQL filter and the query
   // embedding agree on dimensionality and identity.
-  const modelInfo = await getEmbeddingModelInfo({ env });
-  const embeddingModel = modelInfo.model;
+  const embeddingModel = modelOverride || (await getEmbeddingModelInfo({ env })).model;
 
   try {
-    const embeddingRows = await client`
-      select d.id, d.kind, d.title, d.summary, d.body, d.source_path, d.tags, e.embedding
+    const queryVec = floatArrayToPgVector((await embed(query, { env })).embedding);
+    const iterative = await supportsIterativeScan(client);
+
+    // Native pgvector ANN over the HNSW index (not a JS full scan). When the
+    // extension supports it, relaxed_order iterative scan runs inside the txn.
+    const runVector = (sql) => sql`
+      select d.id, d.kind, d.title, d.summary, d.source_path
       from construct_documents d
       join construct_embeddings e on e.document_id = d.id
       where d.project = 'construct' and e.model = ${embeddingModel}
+      order by e.embedding <=> ${queryVec}
+      limit ${limit}
     `;
+    const vectorHits = iterative
+      ? await client.begin(async (sql) => {
+          await sql`SET LOCAL hnsw.iterative_scan = relaxed_order`;
+          return runVector(sql);
+        })
+      : await runVector(client);
 
-    const queryEmbedding = (await embedText(query, { env })).embedding;
-    const embeddedHits = scoreByEmbedding(
-      embeddingRows.map((row) => ({ ...row, embedding: row.embedding })),
-      Array.from(queryEmbedding),
-      { limit },
-    );
-
-    const sqlHits = await client`
-      select id, kind, title, summary, body, source_path
+    const keywordHits = await client`
+      select id, kind, title, summary, source_path
       from construct_documents
       where project = 'construct'
         and (title ilike ${`%${query}%`} or coalesce(summary, '') ilike ${`%${query}%`} or body ilike ${`%${query}%`})
@@ -138,39 +159,29 @@ export async function buildHybridSearchResultsAsync(rootDir, query, { limit = 10
       limit ${limit}
     `;
 
-    const merged = [...base.results];
-    for (const hit of embeddedHits) {
-      if (merged.some((entry) => entry.id === hit.id)) continue;
-      merged.push({
-        id: hit.id,
-        kind: hit.kind,
-        title: hit.title,
-        summary: hit.summary,
-        score: hit.score,
-        source_path: hit.source_path,
-      });
-    }
-    for (const hit of sqlHits) {
-      if (merged.some((entry) => entry.id === hit.id)) continue;
-      merged.push({
-        id: hit.id,
-        kind: hit.kind,
-        title: hit.title,
-        summary: hit.summary,
-        score: 1,
-        source_path: hit.source_path,
-      });
+    // One consolidated ranking: file BM25 (base) + neural ANN + keyword, fused
+    // by Reciprocal Rank Fusion so three incompatible score scales merge by
+    // rank rather than magnitude.
+    const lists = [base.results, vectorHits, keywordHits];
+    const byId = new Map();
+    for (const list of lists) {
+      for (const it of list) if (it && !byId.has(it.id)) byId.set(it.id, it);
     }
+    const results = reciprocalRankFusion(lists, { idOf: (x) => x.id, limit }).map(({ id, score }) => {
+      const it = byId.get(id);
+      return { id, kind: it.kind, title: it.title, summary: it.summary, score, source_path: it.source_path ?? null };
+    });
 
     return {
       ...base,
-      results: merged.slice(0, limit),
+      results,
       stores: {
         ...base.stores,
         vector: {
           ...base.stores.vector,
           ...readVectorConfig(env),
           model: embeddingModel,
+          iterativeScan: iterative,
         },
         sql: {
           ...base.stores.sql,

package/lib/storage/rrf.mjs

@@ -0,0 +1,42 @@
+/**
+ * lib/storage/rrf.mjs — Reciprocal Rank Fusion for hybrid retrieval.
+ *
+ * Combines N independently-ranked result lists (e.g. BM25 keyword and cosine
+ * vector) into one ranking by summing 1/(k + rank) across the lists a document
+ * appears in. Fusion is by RANK, not raw score, so it merges lists whose scores
+ * live on incompatible scales — BM25 is unbounded-positive, cosine is [-1,1] —
+ * without any normalization or hand-tuned weighting. k smooths how much top
+ * ranks dominate; 60 is the field default (Cormack, Clarke & Büttcher,
+ * "Reciprocal Rank Fusion outperforms Condorcet and individual Rank Learning
+ * Methods", SIGIR 2009) and the dominant fusion method across search engines.
+ */
+
+// Each ranked list is ordered best-first. A document's RRF score is the sum,
+// over every list it appears in, of 1/(k + rank) where rank is 1-based.
+
+export function reciprocalRankFusion(rankedLists, { k = 60, idOf = (x) => x.id, limit = null } = {}) {
+  if (!Array.isArray(rankedLists) || rankedLists.length === 0) return [];
+  if (!Number.isFinite(k) || k <= 0) throw new Error('reciprocalRankFusion: k must be a positive number');
+
+  const scores = new Map();
+  const items = new Map();
+
+  for (const list of rankedLists) {
+    if (!Array.isArray(list)) continue;
+    for (let rank = 1; rank <= list.length; rank += 1) {
+      const item = list[rank - 1];
+      if (item == null) continue;
+      const id = idOf(item);
+      if (id == null) continue;
+      scores.set(id, (scores.get(id) || 0) + 1 / (k + rank));
+      if (!items.has(id)) items.set(id, item);
+    }
+  }
+
+  // Deterministic order: by fused score desc, then id asc to break ties stably.
+  const fused = [...scores.entries()]
+    .sort((a, b) => (b[1] - a[1]) || String(a[0]).localeCompare(String(b[0])))
+    .map(([id, score]) => ({ item: items.get(id), id, score }));
+
+  return limit != null ? fused.slice(0, limit) : fused;
+}

package/lib/storage/vector-client.mjs

@@ -161,7 +161,7 @@ export class VectorClient {
   /**
    * Store an observation with its embedding.
    */
-  async storeObservation({ id, project, role, category, summary, content, tags, confidence, source, embedding, gitSha }) {
+  async storeObservation({ id, project, role, category, summary, content, tags, confidence, source, embedding, gitSha, contentHash = null, model = null }) {
     const sql = await this._getSql();
     if (!sql) return { mode: 'file', reason: 'no_sql' };
     const expected = await this.getEngineDimensions();
@@ -169,8 +169,8 @@ export class VectorClient {
 
     const embeddingVec = floatArrayToPgVector(embedding);
     await sql`
-      INSERT INTO construct_observations (id, project, role, category, summary, content, tags, confidence, source, git_sha, embedding)
-      VALUES (${id}, ${project}, ${role}, ${category}, ${summary}, ${content}, ${JSON.stringify(tags || [])}, ${confidence || 0.8}, ${source || null}, ${gitSha || null}, ${embeddingVec})
+      INSERT INTO construct_observations (id, project, role, category, summary, content, tags, confidence, source, git_sha, embedding, content_hash, model)
+      VALUES (${id}, ${project}, ${role}, ${category}, ${summary}, ${content}, ${JSON.stringify(tags || [])}, ${confidence || 0.8}, ${source || null}, ${gitSha || null}, ${embeddingVec}, ${contentHash}, ${model})
       ON CONFLICT (id) DO UPDATE SET
         summary = EXCLUDED.summary,
         content = EXCLUDED.content,
@@ -179,11 +179,26 @@ export class VectorClient {
         source = EXCLUDED.source,
         git_sha = EXCLUDED.git_sha,
         embedding = EXCLUDED.embedding,
+        content_hash = EXCLUDED.content_hash,
+        model = EXCLUDED.model,
         updated_at = now()
     `;
     return { mode: 'sql', id };
   }
 
+  // Fingerprint = the (content_hash, model) a stored observation was embedded
+  // with. Reconciliation compares this against the live content + current model
+  // to find rows needing re-embedding without re-reading every vector.
+
+  async getObservationFingerprints(ids = []) {
+    const sql = await this._getSql();
+    if (!sql || !Array.isArray(ids) || ids.length === 0) return new Map();
+    const rows = await sql`
+      SELECT id, content_hash, model FROM construct_observations WHERE id = ANY(${ids})
+    `;
+    return new Map(rows.map((r) => [r.id, { contentHash: r.content_hash, model: r.model }]));
+  }
+
   /**
    * Search observations by vector similarity.
    */

package/lib/telemetry/backends/local.mjs

@@ -30,7 +30,7 @@ export async function listTraces(teamId, windowMs) {
   if (!existsSync(dir)) return [];
 
   const since = Date.now() - windowMs;
-  const files = readdirSync(TRACES_DIR)
+  const files = readdirSync(dir)
     .filter((f) => f.endsWith('.jsonl'))
     .sort()
     .reverse()

package/lib/telemetry/skill-calls.mjs

@@ -32,7 +32,7 @@ export const DEFAULT_LOG_PATH = path.join(os.homedir(), '.cx', 'skill-calls.json
  *
  * @param {object} event
  * @param {string} event.skillId — path-relative-to-skills/ without the .md, e.g. "roles/engineer.platform"
- * @param {'mcp'|'prompt-composer'|'role-preload'|'pattern-promotion'|'validation'|'other'} event.source
+ * @param {'mcp'|'prompt-composer'|'role-preload'|'validation'|'other'} event.source
  * @param {string} [event.callerContext] — optional free-form context (agent name, MCP client id, etc.)
  * @param {object} [opts]
  * @param {string} [opts.logPath] — override the default log path (tests pass a tmpdir)

package/lib/templates/visual-requirements.mjs

@@ -0,0 +1,84 @@
+/**
+ * lib/templates/visual-requirements.mjs — required visuals per document type.
+ *
+ * The machine-readable form of docs/concepts/doc-visual-matrix.md: which doc
+ * types must carry which visual (a diagram of a given kind, or a table with given
+ * columns), expressed as postcondition checks so the existing validate.mjs engine
+ * enforces them. The shipped template for each listed type must satisfy its own
+ * requirements — pinned by tests/template-visuals.test.mjs — so the templates can
+ * never drift out of step with the matrix (beads wvbf.10 / wvbf.11).
+ */
+
+import { validateArtifactPostconditions } from '../contracts/validate.mjs';
+
+export const VISUAL_REQUIREMENTS = {
+  runbook: [
+    { id: 'runbook-diagnostic-flowchart', check: 'artifact-has-mermaid', diagram: 'flowchart' },
+  ],
+  'incident-report': [
+    { id: 'incident-timeline-table', check: 'artifact-table-has-columns', columns: ['Time (UTC)', 'Event'] },
+  ],
+  rfc: [
+    { id: 'rfc-sequence-diagram', check: 'artifact-has-mermaid', diagram: 'sequenceDiagram' },
+  ],
+};
+
+export function visualRequirementTypes() {
+  return Object.keys(VISUAL_REQUIREMENTS);
+}
+
+// The structural floor of the quality rubric (ADR-0018): the sections a domain
+// expert expects for each doc type. Each shipped template must satisfy its own
+// entry — pinned by tests/structure-requirements.test.mjs — so a template can
+// never quietly drop a required section. Section requirements compose with the
+// VISUAL_REQUIREMENTS above; lintDocStructure runs both.
+
+export const STRUCTURE_REQUIREMENTS = {
+  adr: ['Problem', 'Decision', 'Rejected alternatives', 'Consequences', 'Reversibility'],
+  rfc: ['Summary', 'Motivation', 'Proposed design', 'Risks', 'Verification'],
+  prd: ['Problem', 'Goals', 'Success metrics', 'Risks and mitigations'],
+  'research-brief': ['Sources', 'Findings', 'Confidence summary', 'Recommendation'],
+  'incident-report': ['Summary', 'Severity rationale', 'Impact', 'Timeline', 'Trigger', 'Root cause', 'Contributing factors', 'Action items'],
+  runbook: ['Alert trigger', 'Symptoms', 'Impact', 'Severity and response', 'Diagnostic steps', 'Remediation', 'Rollback', 'Escalation'],
+  strategy: ['Vision', 'Bets', 'Non-bets', 'North Star Metric', 'Metrics', 'Milestones', 'Risks'],
+  'signal-brief': ['Signal', 'Evidence', 'Counter-signal', 'What would make this actionable'],
+  prfaq: ['Problem statement', 'Press release', 'External FAQ', 'Internal FAQ', 'Evidence appendix'],
+  'customer-profile': ['Snapshot', 'Active pain points', 'Open asks', 'Evidence links'],
+  'one-pager': ['Problem', 'Proposal', 'Why now', 'Success measure', 'Cost', 'Asks'],
+  'product-intelligence-report': ['Executive readout', 'Evidence base', 'Themes', 'Customer asks', 'Product implications', 'Recommended actions', 'Gaps and risks'],
+  'backlog-proposal': ['Source evidence', 'Proposed changes', 'Duplicate and conflict check', 'Approval request'],
+  'persona-artifact': ['Goals', 'Frustrations', 'Decision rights', 'Output contract', 'Failure modes', 'Evidence'],
+  'skill-artifact': ['What this skill produces', 'When to invoke it', 'Competency rubric', 'Failure modes', 'Worked example'],
+  'research-finding': ['SOURCES', 'FINDINGS', 'INFERENCES', 'CONFIDENCE', 'GAPS', 'RECOMMENDATION'],
+};
+
+export function structureRequirementTypes() {
+  return [...new Set([...Object.keys(STRUCTURE_REQUIREMENTS), ...Object.keys(VISUAL_REQUIREMENTS)])];
+}
+
+/**
+ * Lint one document against both the required sections and required visuals for
+ * its type. Returns an array of violation strings (empty when satisfied or when
+ * the type declares no requirements).
+ */
+export function lintDocStructure(filePath, type) {
+  const sectionChecks = (STRUCTURE_REQUIREMENTS[type] || []).map((section) => ({
+    id: `${type}-section-${section}`,
+    check: 'artifact-has-section',
+    section,
+  }));
+  const postconditions = [...sectionChecks, ...(VISUAL_REQUIREMENTS[type] || [])];
+  if (postconditions.length === 0) return [];
+  return validateArtifactPostconditions({ contract: { postconditions }, artifactPath: filePath });
+}
+
+/**
+ * Lint one document against the visual requirements for its type. Returns an
+ * array of violation strings (empty when satisfied, or when the type has no
+ * declared visual requirements).
+ */
+export function lintDocVisuals(filePath, type) {
+  const postconditions = VISUAL_REQUIREMENTS[type];
+  if (!postconditions) return [];
+  return validateArtifactPostconditions({ contract: { postconditions }, artifactPath: filePath });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.18",
+  "version": "1.0.19",
   "type": "module",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
   "bin": {
@@ -54,6 +54,8 @@
     "test": "node scripts/run-tests.mjs",
     "test:functional": "node --test --test-timeout=120000 --test-concurrency=1 tests/functional/*.functional.test.mjs",
     "test:unit": "node scripts/run-tests.mjs --exclude=tests/functional",
+    "lint:js": "eslint bin/construct \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"tests/**/*.mjs\"",
+    "coverage": "c8 --reporter=text-summary --reporter=lcov --src=lib --src=bin node scripts/run-tests.mjs --exclude=tests/functional",
     "docs:init": "node lib/init-docs.mjs --yes",
     "docs:update": "node ./bin/construct docs:update",
     "docs:site": "node ./bin/construct docs:site",
@@ -92,5 +94,11 @@
   },
   "overrides": {
     "express-rate-limit": "8.5.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "c8": "^11.0.0",
+    "eslint": "^9.39.4",
+    "globals": "^17.6.0"
   }
 }

package/rules/common/comments.md

@@ -1,5 +1,8 @@
 ---
 description: Construct comment convention for JS/TS/MJS source files.
+enforced_by: lib/comment-lint.mjs
+adr_reference: ADR-0015
+precedence_tier: style
 ---
 # Comment Convention
 

package/rules/common/no-fabrication.md

@@ -1,5 +1,8 @@
 ---
 description: canonical anti-fabrication policy for Construct.
+enforced_by: lib/comment-lint.mjs, lib/contracts/validate.mjs
+adr_reference: ADR-0015
+precedence_tier: correctness
 ---
 # No-Fabrication Policy
 

package/rules/common/precedence.md

@@ -0,0 +1,19 @@
+---
+description: Canonical precedence order for resolving conflicting guidance.
+enforced_by: lib/decisions/precedence.mjs
+adr_reference: ADR-0015
+---
+# Rule precedence
+
+When two rules give contradictory direction for the same situation, the conflict resolves by tier, not by recency or proximity in the prompt. The canonical order, highest priority first:
+
+1. **safety** — preventing destructive or irreversible harm (data loss, secret exposure, production damage).
+2. **security** — preventing unauthorized access, injection, or privilege escalation.
+3. **correctness** — producing truthful, accurate, non-fabricated output that does what it claims.
+4. **durability** — keeping decisions and state from silently drifting or being lost.
+5. **performance** — speed, cost, and resource efficiency.
+6. **style** — naming, formatting, comment convention, and other presentation choices.
+
+A rule may declare its tier in frontmatter (`precedence_tier: <tier>`). A higher tier always governs: a style rule never overrides a correctness rule, and a performance optimization never overrides a safety constraint. The resolver lives in `lib/decisions/precedence.mjs`; `construct decisions check` fails if a rule declares a tier outside this list.
+
+This sets the resolution order. It does not detect whether two rules contradict — that judgment stays with the author and reviewer.

package/rules/common/research-sources.md

@@ -0,0 +1,32 @@
+---
+description: Per-domain community starting points for sentiment and signal research.
+enforced_by: rules/common/research.md
+adr_reference: ADR-0017
+---
+# Community source catalog
+
+Starting points for **community signal** — sentiment, demand, friction, adoption experience — organized by research domain. These complement, never replace, the authoritative starting points in [research.md §2](research.md). Community sources are admissible only under the §10 checklist, and only for sentiment/experience claims (a source's class is relative to the claim — see research.md §2).
+
+Treat every entry as a starting point, not a settled citation: confirm the venue is still active and record the post date and Admiralty grade (research.md §4, §10) before any community source becomes load-bearing.
+
+| Domain | Reddit | Other community venues |
+|---|---|---|
+| AI tools, LLMs, agents | r/LocalLLaMA, r/MachineLearning, r/LanguageTechnology | Hacker News (Show HN / Ask HN), arXiv-sanity discussions, vendor Discords |
+| Developer tools, IDEs, languages | r/programming, r/webdev, r/javascript, r/Python, r/rust, r/golang | Stack Overflow (by tag) + the annual Developer Survey, Hacker News, Lobsters |
+| DevOps, platform, reliability | r/devops, r/sre, r/kubernetes, r/Terraform | CNCF Slack, Hacker News, platform vendor Discords |
+| Security, vulnerabilities | r/netsec, r/cybersecurity, r/AskNetsec | HackerOne / Bugcrowd public disclosures, OSS-Security mailing list, Hacker News |
+| Cloud infra, APIs, SDKs | r/aws, r/AZURE, r/googlecloud | Vendor community forums, provider Discords, Stack Overflow tags |
+| Data / ML engineering | r/dataengineering, r/MachineLearning, r/datascience | dbt Community Slack, Hacker News |
+| Product, market, adoption | r/SaaS, r/ProductManagement, r/startups | Hacker News (launches), Product Hunt discussion |
+| Regulatory, compliance, privacy | r/privacy, r/gdpr | IAPP community forums (primary regulation text remains the authority) |
+
+## How to read community signal
+
+- **Corroboration over volume from one place.** The same pain point raised independently across multiple threads or subreddits is stronger than one viral post.
+- **Engagement is evidence of resonance, not of truth.** High upvotes mean many people relate to the sentiment; they do not make a factual claim in the post true.
+- **Recency matters most for fast-moving domains** (research.md §1) — a frustration from two years ago may already be resolved.
+- **Record the grade.** Community sentiment sources are typically `D`–`F` on reliability; they reach `1`–`2` on credibility only when cross-corroborated. Do not inflate.
+
+## References
+
+- [Reddit](https://www.reddit.com), [Hacker News](https://news.ycombinator.com), [Stack Overflow Developer Survey](https://survey.stackoverflow.co)

package/rules/common/research.md

@@ -29,6 +29,17 @@ Use the narrowest, most authoritative starting point for the research domain:
 
 Tertiary sources (blogs, forums, Q&A, AI-generated summaries) may help locate primaries. They are not sufficient evidence for load-bearing claims.
 
+For where to look for community signal by domain, see [research-sources.md](research-sources.md).
+
+### Source class is relative to the claim
+
+A source's class is not fixed — it depends on what the claim is about. The same artifact can be primary for one claim and tertiary for another.
+
+- A Reddit thread is **tertiary** for "what does API X do" (the spec is primary), but **primary** for "developers report friction with API X's DX" — a first-hand account is primary evidence of the attitude it expresses.
+- A vendor blog post is **secondary** for a feature's behavior (the docs/source are primary), but **primary** for "the vendor publicly committed to X on date Y."
+
+Classify by the claim. For sentiment, demand, adoption-experience, and friction claims, community and forum content is admissible primary evidence under the conditions in §10. For factual, version, security, pricing, and compatibility claims, community content stays tertiary — locate the primary.
+
 ## 3. Start order
 
 Start with the narrowest authoritative source that can answer the question:
@@ -52,7 +63,8 @@ Start with the narrowest authoritative source that can answer the question:
 Record:
 
 - source title or path
-- source class: internal, primary, secondary, or tertiary
+- source class: internal, primary, secondary, or tertiary (for the specific claim — see §2)
+- Admiralty grade: source reliability `A`–`F` and information credibility `1`–`6` (see §10), recorded together, e.g. `B2`
 - version or revision when applicable
 - publication date, release date, or access date
 - why this source is relevant
@@ -119,7 +131,52 @@ Research outputs should include:
 
 Every substantive finding should point to a verified source path, URL, or document reference.
 
-## 10. Anti-patterns
+## 10. Community sources, credibility grading, and signal
+
+Community sources (Reddit, Stack Overflow, Hacker News, Discord, GitHub Discussions) are admissible as **primary evidence of sentiment, demand, friction, and adoption experience** (§2) — never as evidence for factual, version, security, pricing, or compatibility claims, where the primary must be located.
+
+### Admissibility checklist
+
+A community source supports a load-bearing sentiment/demand claim only when:
+
+- the venue is identified (which subreddit/tag/thread) and the post date is recorded;
+- the signal is corroborated — multiple independent threads/posts, or one high-engagement thread (substantial upvotes and a comment consensus), not a single low-engagement post;
+- it is recent enough for the topic's pace (§1);
+- the claim is about expressed experience or opinion, not a fact the poster is merely repeating.
+
+A single anonymous low-engagement post is noise. Cross-thread agreement, repeated independently-raised pain points, and high-engagement consensus are signal. State which you have.
+
+### Admiralty grade
+
+Grade every source on two independent axes, adapted from the NATO Admiralty Code, and record them together (e.g. `A1`, `B2`, `D4`). The axes are independent: a usually-reliable source can carry improbable information (`B5`), and an unreliable source can report something independently confirmed (`E1`).
+
+Source reliability:
+
+| Grade | Meaning |
+|---|---|
+| A | Completely reliable — authoritative primary, history of reliability (official docs, standards, peer-reviewed) |
+| B | Usually reliable — minor doubt (reputable vendor docs, established maintainers) |
+| C | Fairly reliable — some doubt, valid in the past (reputable secondary reporting) |
+| D | Not usually reliable — significant doubt (unvetted blogs, single-author claims) |
+| E | Unreliable — history of invalid information |
+| F | Cannot be judged — no basis to evaluate (anonymous, no track record) |
+
+Information credibility:
+
+| Grade | Meaning |
+|---|---|
+| 1 | Confirmed by other independent sources; consistent with known information |
+| 2 | Probably true — not confirmed, but logical and consistent |
+| 3 | Possibly true — not confirmed, reasonably logical, partial agreement |
+| 4 | Doubtful — not confirmed, possible but not logical, uncorroborated |
+| 5 | Improbable — contradicted by other information |
+| 6 | Cannot be judged — insufficient basis |
+
+Confidence mapping: a load-bearing claim may be stated `high` only on `A1`/`A2`/`B1`; `medium` on `B2`/`C2`/`C3`; otherwise `low`. Community sentiment sources are typically `D`–`F` on reliability but can reach `1`–`2` on credibility when cross-corroborated — record both honestly rather than inflating the claim.
+
+References: [NATO Admiralty Code](https://en.wikipedia.org/wiki/Admiralty_code), [primary-source definition](https://en.wikipedia.org/wiki/Primary_source).
+
+## 11. Anti-patterns
 
 Do not:
 

package/skills/roles/data-engineer.pipeline.md

@@ -31,8 +31,20 @@ Additional failure modes on top of the data engineer core.
 **Why it fails**: data breaks at the consumer boundary.
 **Counter-move**: publish contracts and run compatibility checks before deploy.
 
+## Methodology
+
+The monitors above tell you a job broke; lineage and SLAs tell you what it broke and whether that matters.
+
+**Lineage.** Every dataset should trace column-to-column from source to consumer, so that when a value is wrong you can answer "what fed this" and "what depends on this" without log archaeology. Capture lineage as metadata (which job, which inputs, which transform), not tribal knowledge; it is what makes an incident's blast radius computable.
+
+**Data SLAs / SLOs.** A pipeline without a stated freshness and completeness target has no definition of "broken." Set an SLA per consumed dataset (e.g. "fresh within 1h, 99.5% of rows present") and alert against the SLO, not against raw job status — a job that "succeeded" but delivered half the rows is a breach. Tie the SLA to the consumer's actual decision cadence, not to convenience.
+
+**Observability maturity.** Progress from "is the job green" → "is the data fresh and complete" → "is the distribution sane" (volume/null-rate/value drift). The last catches the silent corruption the first two miss.
+
 ## Self-check before shipping
 - [ ] Reruns, retries, and backfills are idempotent
-- [ ] Freshness, volume, schema, latency, and error monitors exist
+- [ ] Column-level lineage from source to consumer is captured as metadata
+- [ ] A freshness/completeness SLA exists per consumed dataset; alerts fire on SLO breach, not just job failure
+- [ ] Distribution monitors (volume, null-rate, value drift) exist, not just success/failure
 - [ ] Data contracts and compatibility tests are present
 - [ ] Ownership and runbook are clear

package/skills/roles/debugger.md

@@ -57,6 +57,15 @@ Load this before drafting. These are the failure modes that separate strong role
 **Why it fails**: the same bug returns in six months, silently.
 **Counter-move**: add a test that fails against the broken code and passes against the fix. Keep it.
 
+## Methodology
+
+Root cause is found by building a causal chain, not by guessing:
+
+- **Earliest anomaly first**, then work *forward* along cause→effect. The first error in the log is usually an effect; trace upstream to the first place reality diverged from expectation.
+- **Five whys, but each "why" is a tested link, not a story.** "Null pointer → the cache was empty → the warmer never ran → its trigger was disabled → the deploy disabled it." Every arrow must be confirmed by evidence (a log, a value, a repro), or the chain is fiction.
+- **Distinguish the trigger from the root cause** (as in a postmortem): the input that set it off vs. the system condition that let that input cause harm. Fix the root cause; note the trigger.
+- **Stop at the deepest link you can change.** Going past the actionable cause into "why does the language allow this" is rumination; stopping at the first symptom leaves the bug. The root cause is the earliest link whose change prevents recurrence.
+
 ## Self-check before shipping
 
 - [ ] Cause stated in one sentence before the fix

package/skills/roles/designer.accessibility.md

@@ -37,8 +37,18 @@ Additional failure modes on top of the designer core.
 **Why it fails**: triggers vestibular disorders; drives users away.
 **Counter-move**: honor `prefers-reduced-motion`. Provide pause controls for any auto-playing content.
 
+## Methodology
+
+Automated checks (axe, Lighthouse) catch perhaps a third of WCAG issues; the rest are found by use, not by scan:
+
+- **Test with a real screen reader**, not just the accessibility tree — drive the flow with VoiceOver or NVDA and confirm the announced order, labels, and state changes make sense aurally. The DOM can be valid while the spoken experience is incoherent.
+- **Keyboard-only, full task**: complete the whole task with no pointer. Watch focus order, visible focus, and focus traps (modals must trap and restore focus). A reachable control that focus never lands on is unreachable.
+- **Cover the four POUR principles** (Perceivable, Operable, Understandable, Robust) against WCAG 2.x AA — not just contrast and alt text. Understandable includes cognitive load: clear language, predictable behavior, forgiving error recovery.
+- **Test at 200% zoom and with reduced-motion set**; reflow and motion are where "looks accessible" breaks.
+
 ## Self-check before shipping
-- [ ] Keyboard-only path tested for every interactive element
-- [ ] Screen-reader output verified
+- [ ] Keyboard-only path completes the full task; focus order, visible focus, and traps checked
+- [ ] Screen-reader output verified by listening (VoiceOver/NVDA), not just the a11y tree
+- [ ] WCAG 2.x AA across POUR, including cognitive load — not only contrast/alt text
+- [ ] Tested at 200% zoom and with reduced-motion
 - [ ] Semantic HTML first; ARIA only where needed
-- [ ] Reduced-motion path exists and is tested

package/skills/roles/designer.md

@@ -58,8 +58,18 @@ Load this before drafting. These are the failure modes that separate strong role
 **Why it fails**: the product feels inconsistent even when individual screens are fine. Engineering cannot implement cleanly.
 **Counter-move**: name the tokens. space, color, type, radius, motion. before designing. Use them.
 
+## Methodology
+
+Design at the system level, not the screen level:
+
+- **Compose, don't draw.** Build from tokens → primitives → components → patterns (atomic design): a screen is an assembly of reused components, not a bespoke canvas. A new one-off where a component exists is debt; a new component should earn its place by appearing in ≥2 contexts.
+- **States are part of the component, not an afterthought.** Each component specifies its empty, loading, error, disabled, and populated states up front — the happy state alone is an incomplete design.
+- **Tokens carry meaning.** Name tokens by role (`color.text.danger`), not by value (`red-600`), so a theme or rebrand changes one definition, not every usage.
+- **Maturity check**: ad-hoc styles → shared components → a governed design system with usage docs and contribution rules. Name the current rung; "we have a component library" with widespread one-offs is rung two.
+
 ## Self-check before shipping
 
+- [ ] New UI composed from existing tokens/components; new components justified by reuse
 - [ ] Visual direction is explicit, not default
 - [ ] Empty / loading / error states designed as first-class
 - [ ] Primary actions visible at rest, not hover-gated

package/skills/roles/engineer.platform.md

@@ -42,8 +42,16 @@ Additional failure modes on top of the engineer core.
 **Why it fails**: platform surface area compounds blast radius. one leaked token touches every repo.
 **Counter-move**: treat platform secrets as production secrets. Rotate, scope-minimize, and audit.
 
+## Methodology
+
+**IaC maturity.** Infrastructure should climb a ladder: manual → scripted → declarative (Terraform/Pulumi) → declarative + policy-as-code + drift detection. The rung that matters is the last: state is reconciled (no manual console changes survive) and drift between declared and actual is detected and alerted, not discovered during an incident. Name the current rung honestly; "we have some Terraform" alongside hand-edited resources is rung two, not four.
+
+**Supply chain.** Every build emits an SBOM (software bill of materials) so a new CVE can be answered with "are we affected, where" in minutes, not a manual audit. Pin and verify dependencies (lockfiles, checksums, ideally signed provenance), and run the dependency/CVE audit in CI as a gate, not a report. The platform's blast radius is every repo it serves — a compromised build step is the highest-leverage attack.
+
 ## Self-check before shipping
 - [ ] First consumer migrated and measured
+- [ ] Infra is declarative with drift detection; no surviving manual changes
+- [ ] Build emits an SBOM; dependencies pinned/verified; CVE audit gates CI
 - [ ] Deprecation window respected for any breaking change
 - [ ] Failure diagnostics and artifacts preserved
 - [ ] Build-time and cost deltas measured

package/skills/roles/operator.md

@@ -69,10 +69,19 @@ Load this before producing operator output. SRE, ops, release, and durable-knowl
 
 **Why it fails**: no systematic comparison between planned work (documents) and actual work (tickets). Gaps accumulate silently until delivery dates slip.
 
-**Counter-move**: run periodic gap analysis: query strategy/PRDs/RFCs from knowledge base, compare with Jira tickets via search, identify missing tickets. Create补缺 tickets automatically (or queue for approval). Treat "execution gap" as a first-class risk signal.
+**Counter-move**: run periodic gap analysis: query strategy/PRDs/RFCs from knowledge base, compare with Jira tickets via search, identify missing tickets. Create gap-filling tickets automatically (or queue for approval). Treat "execution gap" as a first-class risk signal.
+
+## Methodology
+
+Sequencing work is a calculation, not a vibe:
+
+- **Critical path.** Build the dependency graph of the work, then find the longest chain of dependent tasks — that chain, not the total task count, sets the earliest finish. Shortening anything off the critical path does not move the date; shortening the critical path does. Re-find it after every scope change, because it moves.
+- **Slack.** Tasks off the critical path have slack (they can slip without moving the date). Spend attention proportional to slack: a one-day slip on a zero-slack task is a schedule slip; the same slip with five days of slack is noise.
+- **Resource leveling.** Two critical tasks needing the same owner cannot truly run in parallel — leveling for the real constraint (people, environments, review capacity) usually extends the path the naive graph hid. Sequence to the actual bottleneck.
 
 ## Self-check before shipping
 
+- [ ] Critical path identified; the date is driven by it, not by task count
 - [ ] Each runbook step names its purpose and expected output
 - [ ] Rollback is a tested, first-class plan with trigger criteria
 - [ ] Every alert is actionable; non-actionable signals moved to dashboards