@geraldmaron/construct 1.0.14 → 1.0.16

package/skills/security/red-team.md

@@ -1,8 +1,7 @@
-<!--
-skills/security/red-team.md (Red Team) Use this skill when planning or executing offensive security assessments, advers
-
-Use this skill when planning or executing offensive security assessments, adversary emulation, or attack simulations. ## Reconnaissance
--->
+---
+name: security-red-team
+description: Use this skill when planning or executing offensive security assessments, adversary emulation, or attack simulations.
+---
 # Red Team
 
 Use this skill when planning or executing offensive security assessments, adversary emulation, or attack simulations.

package/skills/security/threat-intel.md

@@ -1,8 +1,7 @@
-<!--
-skills/security/threat-intel.md (Threat Intelligence) Use this skill when performing OSINT, threat modeling, or building threat intell
-
-Use this skill when performing OSINT, threat modeling, or building threat intelligence programs. ## OSINT Collection
--->
+---
+name: security-threat-intel
+description: Use this skill when performing OSINT, threat modeling, or building threat intelligence programs.
+---
 # Threat Intelligence
 
 Use this skill when performing OSINT, threat modeling, or building threat intelligence programs.

package/skills/security/vuln-research.md

@@ -1,8 +1,7 @@
-<!--
-skills/security/vuln-research.md (Vulnerability Research) Use this skill when analyzing binaries, fuzzing software, or developing exploits
-
-Use this skill when analyzing binaries, fuzzing software, or developing exploits for security research. ## Binary Analysis
--->
+---
+name: security-vuln-research
+description: Use this skill when analyzing binaries, fuzzing software, or developing exploits for security research.
+---
 # Vulnerability Research
 
 Use this skill when analyzing binaries, fuzzing software, or developing exploits for security research.

package/skills/strategy/competitive-landscape.md

@@ -1,11 +1,7 @@
-<!--
-skills/strategy/competitive-landscape.md (Competitive Landscape Analysis)
-Use when the team needs a structured read on where competitors sit, what
-customers have already decided, and where defensible whitespace exists.
-Covers Porter Five Forces, Jobs-to-be-Done framing, and competitive
-response sequencing.
--->
-
+---
+name: strategy-competitive-landscape
+description: Use when the team needs a structured read on market positioning before committing direction.
+---
 # Competitive Landscape Analysis
 
 Use when the team needs a structured read on market positioning before committing direction.

package/skills/strategy/market-research-methods.md

@@ -1,11 +1,7 @@
-<!--
-skills/strategy/market-research-methods.md (Market Research Methods)
-Use when planning customer discovery, validating product direction, or
-sizing a market. Covers qualitative and quantitative methods, JTBD
-interview technique, survey design traps, and research-to-decision
-handoff.
--->
-
+---
+name: strategy-market-research-methods
+description: Use when the team needs to validate assumptions before committing resources, or when a decision is being made on vibes rather than signal.
+---
 # Market Research Methods
 
 Use when the team needs to validate assumptions before committing resources, or when a decision is being made on vibes rather than signal.

package/skills/strategy/narrative-arc.md

@@ -1,11 +1,7 @@
-<!--
-skills/strategy/narrative-arc.md (Strategic Narrative Construction)
-Use when drafting a strategy memo, PRD positioning section, board update,
-or fundraising narrative. Covers Andy Raskin's strategic narrative
-structure, the five components of a compelling story, and common failure
-modes in executive communication.
--->
-
+---
+name: strategy-narrative-arc
+description: Use when the argument must move people, not just inform them. Strategic narrative is the difference between a document that gets read and one that changes what people do.
+---
 # Strategic Narrative Construction
 
 Use when the argument must move people, not just inform them. Strategic narrative is the difference between a document that gets read and one that changes what people do.

package/skills/strategy/pricing-positioning.md

@@ -1,11 +1,7 @@
-<!--
-skills/strategy/pricing-positioning.md (Pricing and Positioning)
-Use when setting or revisiting price, defining positioning vs. competitors,
-or preparing a go-to-market argument. Covers value-based vs. cost-plus
-pricing, willingness-to-pay research techniques, and positioning statement
-construction.
--->
-
+---
+name: strategy-pricing-positioning
+description: Use when the team needs to set price, adjust positioning, or defend either to stakeholders.
+---
 # Pricing and Positioning
 
 Use when the team needs to set price, adjust positioning, or defend either to stakeholders.

package/skills/utility/clean-code.md

@@ -1,8 +1,7 @@
-<!--
-skills/utility/clean-code.md (AI Slop Removal) Patterns and heuristics for identifying and removing AI-generated code smells. U
-
-Patterns and heuristics for identifying and removing AI-generated code smells. Use when cleaning up output from AI coding tools. ## Decision Tree
--->
+---
+name: utility-clean-code
+description: Patterns and heuristics for identifying and removing AI-generated code smells. Use when cleaning up output from AI coding tools.
+---
 # AI Slop Removal
 
 Patterns and heuristics for identifying and removing AI-generated code smells. Use when cleaning up output from AI coding tools.

package/specialists/policy-inventory.json

@@ -155,6 +155,20 @@
       "enforcement": "(persona prompt)",
       "mode": "honor-system",
       "description": "Architectural pattern guidance (module boundaries, error handling, async contracts) applied at authoring time."
+    },
+    {
+      "id": "review-before-change",
+      "source": "rules/common/review-before-change.md",
+      "enforcement": "(persona prompt)",
+      "mode": "honor-system",
+      "description": "Requires an existing-artifact audit before authoring or rewriting any durable doc, rule, template, or PRD/ADR/RFC. Extend or supersede; do not duplicate."
+    },
+    {
+      "id": "session-efficiency",
+      "source": "rules/common/efficiency.md",
+      "enforcement": "lib/read-tracker-store.mjs + session-start digest",
+      "mode": "deterministic",
+      "description": "Read discipline, probe-before-bulk-read, and tool parallelism rules. Read counts tracked per-file; the session-start efficiency digest surfaces files crossing the re-read threshold."
     }
   ]
 }

package/lib/specialist-contracts-enforce.mjs

@@ -1,172 +0,0 @@
-/**
- * lib/specialist-contracts-enforce.mjs — runtime contract enforcement.
- *
- * Wraps `validatePacket` from `lib/specialist-contracts.mjs` with three production
- * concerns:
- *
- *   1. Block on violation. `enforcePacket` throws a `ContractViolationError`
- *      when the packet doesn't satisfy the contract direction. Callers can
- *      catch and degrade if they want advisory mode, but the default is hard
- *      enforcement so contract bugs surface loudly.
- *
- *   2. Tamper-evident violation log. Every violation appends a JSONL record
- *      to `~/.cx/contract-violations.jsonl` with a sha256 chain-hash over
- *      the prior line. Same pattern as the mutation audit trail. Operators
- *      can replay the chain to detect after-the-fact tampering.
- *
- *   3. Visibility into `construct doctor`. `recentViolations(windowMs)`
- *      returns the last N violations so doctor can surface
- *      "3 contract violations in the last 24h — see ~/.cx/contract-violations.jsonl".
- *
- * The enforcement is identity-aware. Each violation logs the active agent
- * (via `~/.cx/last-agent.json` like audit-trail does) so operators can
- * identify which producer or consumer is at fault.
- */
-
-import { existsSync, mkdirSync, statSync, readFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { homedir } from 'node:os';
-import { createHash } from 'node:crypto';
-import { getContractById, validatePacket } from './specialist-contracts.mjs';
-import { appendBounded } from './logging/rotate.mjs';
-import { resolveProjectScopedPath } from './project-root.mjs';
-import { validatePostconditions } from './specialists/postconditions.mjs';
-
-const CX_DIR = join(homedir(), '.cx');
-// contract-violations are PROJECT-SCOPED — a violation belongs to a
-// specific contract chain in a specific project. Resolves to
-// <project>/.cx/contract-violations.jsonl when inside a project, falling
-// back to the legacy ~/.cx path for standalone invocations. Resolved on
-// every call so cwd/HOME changes inside the same process (tests, harness
-// reuse) route correctly.
-
-function logFile() {
-  return resolveProjectScopedPath('contract-violations.jsonl', { ensureDir: false });
-}
-const LAST_AGENT = join(CX_DIR, 'last-agent.json');
-
-export class ContractViolationError extends Error {
-  constructor({ contractId, direction, missing, verdict = 'CONTRACT_VIOLATION', postconditionFailures = [] }) {
-    const detail = postconditionFailures.length > 0
-      ? `postcondition(s) failed: ${postconditionFailures.map((f) => f.id).join(', ')}`
-      : `missing field(s): ${(missing || []).join(', ')}`;
-    super(`contract '${contractId}' (${direction}) violated — ${detail}`);
-    this.name = 'ContractViolationError';
-    this.contractId = contractId;
-    this.direction = direction;
-    this.missing = missing || [];
-    this.verdict = verdict;
-    this.postconditionFailures = postconditionFailures;
-  }
-}
-
-function sha256(input) { return createHash('sha256').update(input).digest('hex'); }
-
-function readLastAgent() {
-  try { return JSON.parse(readFileSync(LAST_AGENT, 'utf8'))?.agent || 'construct'; }
-  catch { return 'construct'; }
-}
-
-function readPrevLineHash() {
-  try {
-    const file = logFile();
-    if (!existsSync(file)) return null;
-    const size = statSync(file).size;
-    if (size === 0) return null;
-    const tail = readFileSync(file, 'utf8').slice(Math.max(0, size - 2048));
-    const lines = tail.split('\n').filter(Boolean);
-    return lines.length === 0 ? null : sha256(lines[lines.length - 1]);
-  } catch { return null; }
-}
-
-function logViolation(contractId, direction, missing, packet, extra = {}) {
-  try {
-    const file = logFile();
-    mkdirSync(dirname(file), { recursive: true });
-    const record = {
-      ts: new Date().toISOString(),
-      agent: readLastAgent(),
-      contractId,
-      direction,
-      missing,
-      packet_keys: packet && typeof packet === 'object' ? Object.keys(packet) : null,
-      prev_line_hash: readPrevLineHash(),
-      ...extra,
-    };
-    appendBounded('contract-violations', file, JSON.stringify(record) + '\n');
-  } catch { /* logging is best-effort */ }
-}
-
-/**
- * Validate `packet` against `contractId` in the given `direction`. Throws
- * a `ContractViolationError` on failure (and logs the violation). Returns
- * the validation result on success so callers can inspect the resolved
- * contract metadata.
- *
- * For `direction === 'output'`, also evaluates the producer's binary
- * postconditions from `lib/agents/postconditions.mjs`. A failed postcondition
- * raises with `verdict: 'BLOCKED_CONTRACT'` so the dispatcher can branch on
- * the typed verdict rather than parsing the error message.
- *
- * @param {string} contractId
- * @param {object} packet
- * @param {'input'|'output'} [direction]
- * @returns {{ ok: true, contract, direction }}
- */
-export function enforcePacket(contractId, packet, direction = 'input') {
-  const result = validatePacket(contractId, packet, direction);
-  if (!result.ok) {
-    if (result.reason === 'contract-not-found') {
-      throw new ContractViolationError({
-        contractId,
-        direction,
-        missing: ['(contract not found)'],
-      });
-    }
-    logViolation(contractId, direction, result.missing || [], packet);
-    throw new ContractViolationError({
-      contractId,
-      direction,
-      missing: result.missing || [],
-    });
-  }
-
-  if (direction === 'output') {
-    const contract = result.contract || getContractById(contractId);
-    const producer = contract?.producer;
-    if (producer) {
-      const postcondition = validatePostconditions(producer, packet);
-      if (!postcondition.ok) {
-        logViolation(contractId, direction, [], packet, {
-          verdict: 'BLOCKED_CONTRACT',
-          postconditionFailures: postcondition.failures,
-        });
-        throw new ContractViolationError({
-          contractId,
-          direction,
-          verdict: 'BLOCKED_CONTRACT',
-          postconditionFailures: postcondition.failures,
-        });
-      }
-    }
-  }
-
-  return result;
-}
-
-/**
- * Read recent violations from the chain log. Returns oldest-first.
- */
-export function recentViolations({ windowMs = 24 * 60 * 60 * 1000 } = {}) {
-  const file = logFile();
-  if (!existsSync(file)) return [];
-  try {
-    const cutoff = Date.now() - windowMs;
-    return readFileSync(file, 'utf8')
-      .trim()
-      .split('\n')
-      .filter(Boolean)
-      .map((line) => { try { return JSON.parse(line); } catch { return null; } })
-      .filter((r) => r && new Date(r.ts).getTime() >= cutoff);
-  } catch { return []; }
-}

package/rules/common/agents.md

@@ -1,28 +0,0 @@
-<!--
-rules/common/agents.md: platform-agnostic agent orchestration guidance.
-
-Defines when to route to specialist agents, parallel execution rules,
-and multi-perspective analysis patterns. Does not reference specific
-platform agent types or config paths.
--->
-# Agent Orchestration
-
-## Immediate Agent Usage
-
-No user prompt needed: match the task to the right specialist:
-1. Complex feature requests - planning specialist
-2. Code just written/modified - code review specialist
-3. Bug fix or new feature - TDD specialist
-4. Architectural decision - architecture specialist
-
-## Parallel Task Execution
-
-ALWAYS use parallel execution for independent operations. Launch multiple specialists concurrently when their work is independent.
-
-## Multi-Perspective Analysis
-
-For complex problems, use multiple specialist perspectives:
-- Factual reviewer
-- Senior engineer
-- Security expert
-- Consistency reviewer

package/rules/common/development-workflow.md

@@ -1,32 +0,0 @@
-<!--
-rules/common/development-workflow.md: feature implementation pipeline.
-
-Defines the research-plan-TDD-review-commit workflow that runs before
-git operations. References testing.md, code-review.md, git-workflow.md.
--->
-# Development Workflow
-
-## Feature Implementation Workflow
-
-0. **Research & Reuse** _(mandatory before any new implementation or artifact)_
-   - **Search existing code first:** Look for existing implementations, templates, and patterns before writing anything new.
-   - **Search existing artifacts:** Before authoring a doc, rule, template, strategy, PRD, ADR, or RFC, audit what already exists. See [review-before-change.md](review-before-change.md) for the audit checklist. Extend or supersede; do not duplicate.
-   - **Check docs:** Confirm API behavior, package usage, and version-specific details before implementing.
-   - **Check package registries:** npm, PyPI, crates.io before writing utility code.
-   - Prefer adopting a proven approach over writing net-new code.
-
-1. **Plan** - Break into phases; identify dependencies and risks.
-
-2. **TDD** - Write tests first (RED), implement (GREEN), refactor (IMPROVE). See [testing.md](testing.md).
-
-3. **Code Review** - Review immediately after writing. See [code-review.md](code-review.md).
-
-3.5. **Docs** _(mandatory for any user-facing change)_
-   - If you added or changed a CLI command, API endpoint, config option, or architecture boundary: update `docs/concepts/architecture.md` and create or update the relevant `docs/cookbook/` recipe.
-   - If you added a CLI command, ensure the cookbook index links to a recipe for it.
-   - Run `construct docs:update` to regenerate AUTO-managed regions.
-   - A change is not DONE if a user-facing capability exists with no documentation.
-
-4. **Commit** - Conventional commits format. See [git-workflow.md](git-workflow.md).
-
-5. **Pre-Review Checks** - CI passing, conflicts resolved, branch synced.

package/rules/common/performance.md

@@ -1,55 +0,0 @@
-<!--
-rules/common/performance.md: model-agnostic performance and context management rules.
-
-Defines model selection tiers, context window management heuristics,
-and build troubleshooting steps. No platform-specific tool names or config paths.
--->
-# Performance Optimization
-
-## Model Selection Strategy
-
-**Fast tier** (small/cheap models):
-- Lightweight agents with frequent invocation
-- Pair programming and code generation
-- Worker agents in multi-agent systems
-
-**Standard tier** (mid-range models):
-- Main development work
-- Orchestrating multi-agent workflows
-- Complex coding tasks
-
-**Reasoning tier** (large/frontier models):
-- Complex architectural decisions
-- Maximum reasoning requirements
-- Research and analysis tasks
-
-## Context Window Management
-
-Avoid last 20% of context window for:
-- Large-scale refactoring
-- Feature implementation spanning multiple files
-- Debugging complex interactions
-
-Prefer this retrieval ladder before loading more context:
-1. Targeted search to narrow candidate files
-2. Targeted reads (aim for <400 lines)
-3. Parallel reads for the minimum necessary file set
-4. Summarize to a context artifact before broad re-exploration
-
-Heuristics:
-- Re-reading the same file multiple times without a state change is a retrieval smell.
-- Large reads should be reserved for files where local structure matters more than symbol search.
-- Use workflow/context artifacts as cached state instead of rediscovering background repeatedly.
-
-Lower context sensitivity tasks:
-- Single-file edits
-- Independent utility creation
-- Documentation updates
-- Simple bug fixes
-
-## Build Troubleshooting
-
-If build fails:
-1. Analyze error messages
-2. Fix incrementally
-3. Verify after each fix