@thebackstoryis/engineering-with-ai 0.2.9

package/skills-src/ewai-standards-check/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: ewai-standards-check
+description: Verify a supplied code snippet, one file, several files, a directory, a change set, or an entire repository against the accepted project standards and related decisions captured in SPECS. Use when an EWAI project owner asks whether code follows project standards, requests a standards audit or compliance check, needs gate evidence before moving work forward, or wants a durable Markdown standards-check report.
+---
+
+# EWAI Standards Check
+
+Check implementation evidence against project-owned standards. Resolve the SPECS root from `.ewai-pipeline/project.json`, treat it as the source of truth, and write a durable Markdown review; do not substitute generic best practice for a missing project rule.
+
+## Establish the review boundary
+
+1. Resolve the workspace and configured SPECS root from `.ewai-pipeline/project.json`; fall back to `./SPECS` only for a legacy/default project without a locator.
+2. Run the normal EWAI check-in when this is the first substantive action in the conversation.
+3. Confirm the target from the request:
+   - code supplied in the conversation;
+   - one file or an explicit list of files;
+   - a directory, commit, branch diff, or working-tree change set;
+   - the whole repository.
+4. Confirm whether the user wants review only or also wants fixes. Default to review only. Never alter code merely because a non-conformity is found.
+5. If the configured SPECS root is absent, stop and explain that there is no project standards contract to verify. Offer EWAI initialization or Archaeology rather than inventing a baseline.
+
+For a whole-repository request, inventory the source surfaces before checking them. Exclude generated, vendored, cache, build-output, dependency, and binary paths unless a project standard explicitly brings them into scope. Record every exclusion. Do not describe a sampled or partially inspected repository as compliant.
+
+## Build the applicable standards set
+
+Read project sources before inspecting implementation:
+
+1. Read `SPECS/5.Strategy/standards-index.md` when it exists and follow its routing instructions.
+2. Read applicable accepted rules under `SPECS/4.Constraints/`, including compliance constraints.
+3. Read accepted architecture, patterns, anti-patterns, decisions, schemas, SOPs, and stack guidance under `SPECS/5.Strategy/` when they constrain the target.
+4. Read relevant scope, domain, intent, requirement, journey, risk, gate, and Build records when they determine expected behaviour or required evidence.
+5. Read repository-local agent instructions named by the project, such as `AGENTS.md` or `CLAUDE.md`, only when SPECS adopts or routes to them. Record their authority explicitly.
+
+Create an applicability matrix before judging the code. Give each rule a stable identifier from the source when available; otherwise use `<relative-path>#<heading>`. For each rule record:
+
+- why it applies to this target;
+- which implementation surfaces can prove or disprove it;
+- what validation evidence is required;
+- whether it is `applicable`, `not-applicable`, `conflicting`, or `unresolved`.
+
+Do not silently choose between conflicting accepted records. Report the conflict as a standards defect and keep the affected checks unresolved until a project owner decides precedence.
+
+## Inspect implementation evidence
+
+Read the target and enough surrounding code to evaluate it accurately. Follow imports, callers, routes, schemas, tests, configuration, generated contracts, and framework conventions where the standard crosses file boundaries. A file-only request limits the reported target, not the contextual reading needed to understand it.
+
+Use the most specific available evidence:
+
+- source paths and line numbers;
+- symbols, routes, migrations, schemas, or configuration keys;
+- tests and their assertions;
+- formatter, linter, type-checker, static-analysis, security, or project validation output;
+- repository history when the standard or exception depends on an accepted decision.
+
+Run safe project-defined validation commands when they are necessary and available. Follow the project's execution instructions and record the exact command and outcome. A green tool result is evidence for the rules it actually covers, not proof that every project standard passes.
+
+Classify each applicable rule as:
+
+- `pass`: direct evidence satisfies the rule;
+- `non-conformity`: direct evidence contradicts the rule;
+- `warning`: the code creates a material concern but the rule is advisory or incomplete;
+- `unverified`: evidence is missing, inaccessible, ambiguous, or requires runtime/human validation;
+- `not-applicable`: the rule was considered and does not govern this target;
+- `standards-conflict`: accepted project sources disagree.
+
+Assign `critical`, `high`, `medium`, `low`, or `information` severity to non-passing findings. Separate certainty about the evidence from severity of the impact. Never claim security, compliance, correctness, or whole-repository conformance from absence of detected failures.
+
+## Write the Markdown report
+
+Read [the standards-check report contract](references/report-contract.md) completely before writing the result.
+
+Create:
+
+```text
+SPECS/3.Evidence/reviews/standards/<YYYY-MM-DD>-<target-slug>-standards-check.md
+```
+
+Use a collision-safe suffix rather than overwriting an existing report. Keep sensitive code out of the report; cite paths and describe evidence instead. For supplied snippets, assign displayed line numbers and label the evidence as conversation-supplied rather than repository-verified.
+
+The report must contain the target, commit or working-tree state, standards sources, applicability matrix, inspected evidence, exclusions, command results, outcome counts, detailed findings, unverified items, conflicts, and a proportionate remediation order. Include passes as well as problems so the report shows real coverage.
+
+If the check belongs to an intent or delivery stage, link the report from the applicable Build tracker or evidence record without changing the stage automatically. A report does not pass a gate by itself; the project's gate contract decides that.
+
+## Present the outcome
+
+Lead with the bounded conclusion and the report path. State:
+
+- how many rules passed, failed, warned, remained unverified, conflicted, or were not applicable;
+- the highest-severity findings;
+- whether coverage was complete, partial, or blocked for the requested boundary;
+- what decision, evidence, or remediation should happen next.
+
+If the user requested fixes, propose the smallest safe sequence and ask for any authority needed by the project before editing. After fixes, create a new report or an explicitly dated re-check section; preserve the original evidence.

package/skills-src/ewai-standards-check/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EWAI Standards Check"
+  short_description: "Verify code against project SPECS standards"
+  default_prompt: "Use $ewai-standards-check to verify this code against the standards captured in the project SPECS and write a Markdown report."

package/skills-src/ewai-standards-check/references/report-contract.md

@@ -0,0 +1,116 @@
+# Standards-check report contract
+
+Use this contract for every report written by `$ewai-standards-check`.
+
+## Required frontmatter
+
+```yaml
+---
+title: Standards check — <target>
+date: YYYY-MM-DD
+status: complete | partial | blocked
+scope: snippet | files | directory | change-set | repository
+target: <human-readable target>
+repository_revision: <commit SHA, working-tree state, or not-repository-backed>
+standards_baseline: <commit SHA or working-tree state for SPECS>
+reviewer: <AI host/model when known>
+---
+```
+
+Use `complete` only when every in-scope source surface and applicable standard has a supported outcome. Use `partial` for sampling, explicit exclusions that prevent full coverage, interrupted commands, or unresolved evidence. Use `blocked` when the standards baseline or target cannot be inspected meaningfully.
+
+## Required sections
+
+### 1. Conclusion
+
+State the bounded result in plain language. Never use an unqualified “compliant” for a partial review.
+
+### 2. Review scope
+
+Record:
+
+- requested target and review mode;
+- repositories, paths, symbols, snippet lines, commits, or diff range inspected;
+- revision and dirty-working-tree state;
+- generated, vendored, binary, unavailable, or deliberately excluded surfaces;
+- whether coverage is complete, partial, or blocked.
+
+### 3. Standards baseline
+
+List every SPECS source used, with a relative path and relevant heading or rule identifier. Distinguish:
+
+- binding constraints;
+- accepted decisions or patterns;
+- behavioural expectations and gate evidence;
+- advisory material;
+- unresolved or conflicting sources.
+
+Do not paste large sections of standards. Paraphrase the rule and link it to its source.
+
+### 4. Outcome summary
+
+Use this table:
+
+| Outcome | Count |
+|---|---:|
+| Pass | 0 |
+| Non-conformity | 0 |
+| Warning | 0 |
+| Unverified | 0 |
+| Standards conflict | 0 |
+| Not applicable | 0 |
+
+Add severity counts for non-passing findings when useful.
+
+### 5. Applicability and coverage matrix
+
+Use one row per considered rule:
+
+| Standard | Why it applies | Evidence inspected | Outcome | Finding |
+|---|---|---|---|---|
+
+Use a source-provided standard identifier when available; otherwise use `<path>#<heading>`. A whole-repository report must make unexamined source surfaces visible.
+
+### 6. Findings
+
+Give each non-passing finding a stable identifier such as `SC-001` and include:
+
+- outcome and severity;
+- standard source and concise rule;
+- implementation evidence with path and line or symbol references;
+- impact and affected scope;
+- confidence and any uncertainty;
+- smallest useful remediation;
+- verification needed after remediation.
+
+Keep one independently resolvable issue per finding. Do not combine unrelated violations to reduce the finding count.
+
+### 7. Confirmed conformance
+
+Summarize meaningful passes with their evidence. Avoid listing trivial formatting checks when they add no assurance.
+
+### 8. Unverified items and standards conflicts
+
+Explain missing evidence, runtime-only checks, inaccessible systems, ambiguous wording, contradictory records, and the accountable decision needed. Do not convert unknowns into passes.
+
+### 9. Validation commands
+
+Record each command, execution context, exit status, and relevant result. If no commands ran, say why.
+
+### 10. Recommended next actions
+
+Order actions by risk and dependency. Separate:
+
+1. standards decisions or missing evidence;
+2. critical and high remediation;
+3. lower-severity improvements;
+4. re-check and gate evidence.
+
+## Evidence rules
+
+- Prefer repository-relative links and line references.
+- Cite the standards baseline and implementation revision independently when they differ.
+- Mark conversation-supplied snippets as non-repository-backed.
+- Do not expose secrets, credentials, personal data, or unnecessarily reproduce vulnerable code.
+- Treat tool output as scoped evidence, not an authority beyond the checks the tool performs.
+- Preserve the original report. A later re-check should be a new dated report or a clearly attributable appended review event.

package/skills-src/ewai-test-scenarios/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: ewai-test-scenarios
+description: Design source-grounded test scenarios with a dynamically selected ensemble of installed EWAI personas, record reviewed scenario evidence, and build automated tests from accepted scenario oracles. Use during EWAI Test Plan when persona perspectives can expose missing paths, or during Build when accepted automated or hybrid PTS scenarios apply to the current task.
+---
+
+# EWAI Persona-Driven Test Scenarios
+
+Resolve the project and configured SPECS root before acting. Read [the scenario contract](references/scenario-contract.md) before preparing, recording, or implementing a pack.
+
+Use the deterministic CLI for source truth and durable writes. Use agent judgement only to challenge coverage, propose hypotheses, reconcile scenarios, and implement tests. Never treat a persona perspective as evidence, a requirement, an approval, or a substitute for a real user or accountable specialist.
+
+## Choose the mode
+
+- During **Test Plan**, design and record scenarios through the preparation workflow below.
+- During **Build**, implement only accepted automated or hybrid scenarios assigned to the current leased task.
+- If both are needed, finish reviewed scenario design before using its oracles to build tests.
+
+## Prepare authoritative context
+
+Run:
+
+```bash
+ewai test-scenarios prepare <slug> --focus "<current testing concern>" --project . --json
+```
+
+Do not draft scenarios before preparation succeeds. The result owns the current source digest, bounded source references, contextual impact evidence, installed-tier availability, and active persona ensemble.
+
+Show the active persona name, tier, matched concerns, and engagement reason before semantic challenge. Engage only the returned ensemble. When the focus changes materially, prepare again and replace the ensemble with the newly selected personas; do not accumulate stale participants.
+
+Premium personas may participate only when reported as installed. Never sync, download, update, or expose premium persona bodies as part of this skill.
+
+## Challenge coverage with personas
+
+Ask each active persona to challenge one or more distinct concerns within its engagement reason. Consider happy path, alternate path, errors, permissions, accessibility, security and privacy, operations, recovery, data, misuse, adversarial behaviour, and regression only when the sources or an explicitly labelled hypothesis make them relevant.
+
+For every proposal:
+
+1. Cite one or more returned authoritative source IDs for the expected behaviour.
+2. Record the persona ID and the concern that prompted the proposal.
+3. Express preconditions, actions, and observable expected results.
+4. Route proof to automated tests, Manual QA, specialist assurance, or representative-user validation.
+5. Keep a proposal as an unresolved hypothesis when no authoritative source permits the oracle.
+
+An inferred Blast Radius concern can explain why a scenario should be investigated. It cannot, by itself, authorise expected product behaviour.
+
+When an organisation policy baseline is enabled, treat its current matched policy rule and accepted control evidence as an authoritative source for relevant test scenarios. Preserve the policy rule, control, evaluation digest, and evidence route in the scenario trace. Persona challenges may broaden misuse, privacy, security, accessibility, operational, or recovery coverage, but they cannot alter the policy oracle or satisfy a named-human or specialist-review control.
+
+## Review and record
+
+Before recording, have a named accountable reviewer:
+
+- de-duplicate equivalent scenarios;
+- resolve conflicting source interpretations or retain the conflict as a gap;
+- reject unsupported accepted oracles;
+- select the evidence route and owner;
+- name the planned test file and test name for automated or hybrid scenarios;
+- retain blocked, superseded, and unresolved hypotheses rather than deleting inconvenient history.
+
+Create a project-local candidate JSON file that follows `ewai.persona-test-scenarios/v1`, then run:
+
+```bash
+ewai test-scenarios record <slug> \
+  --input <project-relative-candidate.json> \
+  --reviewed-by "<named reviewer>" \
+  --project . \
+  --json
+```
+
+Inspect durable state with:
+
+```bash
+ewai test-scenarios status <slug> --project . --json
+```
+
+If status is `stale`, prepare and review again. If it is `invalid`, preserve the evidence and investigate the reported pair or digest failure; do not repair it by editing Markdown.
+
+## Build tests from accepted scenarios
+
+Read the current task contract, test standards, and authoritative `test-scenarios.json`. Select only accepted scenarios whose automation is `automated` or `hybrid` and whose planned test belongs to the current task write set.
+
+For each selected scenario ID:
+
+1. Read the cited source and accepted observable result.
+2. Write the failing test first and capture the expected RED evidence.
+3. Preserve the accepted oracle; never weaken or reverse it to match current code.
+4. Implement the smallest production change needed for that scenario.
+5. Run the focused GREEN command and then the task's refactor checks.
+6. Report the scenario ID, test file and name, command result, and remaining human evidence route.
+
+Do not mark Manual QA, specialist assurance, or representative-user validation as passed. Those routes require named human evidence even when an automated portion also passes.
+
+## Stop conditions
+
+Stop and escalate when source references disagree, a requested oracle has no authoritative source, the planned test falls outside the leased task, implementation would change an approval, a persona body would need to enter a safe projection, or a human evidence route is being simulated.

package/skills-src/ewai-test-scenarios/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EWAI Test Scenarios"
+  short_description: "Design persona-led scenarios and build traceable tests"
+  default_prompt: "Use $ewai-test-scenarios to design source-grounded persona test scenarios or build tests from an accepted scenario pack."

package/skills-src/ewai-test-scenarios/references/scenario-contract.md

@@ -0,0 +1,88 @@
+# Persona test-scenario contract
+
+Read this reference when preparing a candidate pack, reviewing validation errors, implementing accepted tests, or interpreting workspace status.
+
+## Authority layers
+
+| Layer | May do | Must not do |
+| --- | --- | --- |
+| Authoritative source | Define an accepted outcome, constraint, journey, criterion, standard, claim, or test obligation | Be silently replaced by persona output |
+| Contextual impact evidence | Identify an observed or inferred area worth challenging | Authorise expected product behaviour by itself |
+| Persona contribution | Expose a concern, edge case, ambiguity, or hypothesis | Act as stakeholder fact, approval, or completed evidence |
+| Human decision | Accept, reject, block, supersede, or route a scenario | Be inferred from model fluency |
+| Test evidence | Demonstrate the accepted observable result through the named route | Rewrite the oracle to make current code pass |
+
+## Preparation contract
+
+`ewai test-scenarios prepare <slug> --focus "..." --project . --json` returns `ewai.persona-test-brief/v1` with:
+
+- `sourceDigest` for the bounded project evidence;
+- `authoritativeSources[]` containing stable IDs, kind, label, safe path, digest, and excerpt;
+- `contextualEvidence[]` for non-authoritative impact context;
+- `activePersonas[]` containing only ID, name, tier, category, bounded description, matched signals, and engagement reason;
+- installed availability for core, premium, personal, and project tiers;
+- unresolved questions, recording enums, and the human-authority boundary.
+
+Preparation is read-only. It never invokes a network, Git, an LLM, or premium synchronisation.
+
+## Candidate schema
+
+Use this shape:
+
+```json
+{
+  "schema": "ewai.persona-test-scenarios/v1",
+  "slug": "customer-access",
+  "focus": "permission and recovery",
+  "preparedSourceDigest": "<digest from preparation>",
+  "scenarios": [
+    {
+      "id": "PTS-001",
+      "title": "Authorised delegate completes the request",
+      "type": "happy-path",
+      "sourceRefs": ["intent:journey:J-001", "intent:acceptance:AC-001"],
+      "personaContributions": [
+        {
+          "personaId": "project.product-owner",
+          "concern": "Prove the intended outcome and permission boundary."
+        }
+      ],
+      "preconditions": ["An authenticated delegate may request access."],
+      "actions": ["Submit a valid access request."],
+      "expectedResults": ["The request is accepted and a clear success outcome is displayed."],
+      "evidenceRoute": "automated",
+      "automation": "automated",
+      "plannedTest": {
+        "file": "tests/access.test.mjs",
+        "name": "authorised delegate completes access request"
+      },
+      "owner": "Delivery team",
+      "status": "accepted"
+    }
+  ],
+  "gaps": []
+}
+```
+
+Scenario IDs use `PTS-###` and remain stable. Supported types are `happy-path`, `alternate`, `error`, `permissions`, `accessibility`, `security-privacy`, `operations`, `recovery`, `data`, `misuse`, `adversarial`, and `regression`.
+
+Supported status values are `accepted`, `blocked`, `superseded`, and `hypothesis`. An accepted scenario needs at least one known authoritative source reference. A blocked or hypothesis item may preserve a question without presenting it as accepted behaviour.
+
+Evidence routes are `automated`, `manual-qa`, `specialist-assurance`, and `representative-user`. Automation values are `automated`, `manual`, and `hybrid`. Automated and hybrid scenarios require a safe repository-relative planned test file and named test.
+
+## Evidence and status
+
+Recording writes authoritative `test-scenarios.json` and readable `test-scenarios.md` under the delivery root. The JSON retains the content digest and the Markdown digest. Identical input is idempotent; conflicting accepted evidence is not overwritten.
+
+Status means:
+
+- `missing`: no reviewed pack exists;
+- `recorded`: the pair and current sources match;
+- `stale`: an authoritative source changed after review;
+- `invalid`: the pair, schema, slug, content digest, or Markdown digest does not match.
+
+JSON is authoritative. Never parse or manually edit Markdown to repair scenario state.
+
+## Human evidence boundary
+
+Manual QA remains an explicit named human gate. Specialist assurance requires an accountable practitioner. Representative-user validation requires real representative participants. Persona simulation may improve the question set but may not complete any of those routes.

package/src/afk-worker.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { executeAfkRun } from './runtime/afk-conductor.mjs';
+
+function option(name) {
+  const index = process.argv.indexOf(name);
+  return index < 0 ? '' : process.argv[index + 1] ?? '';
+}
+
+const projectRoot = option('--project');
+const runId = option('--run');
+if (!projectRoot || !runId) {
+  console.error('Usage: afk-worker --project PATH --run RUN_ID');
+  process.exitCode = 2;
+} else {
+  await executeAfkRun(projectRoot, runId);
+}