@thebackstoryis/engineering-with-ai 0.2.9

package/skills-src/ewai-archaeology/references/lifecycle-reconstruction.md

@@ -0,0 +1,177 @@
+# SPECS lifecycle reconstruction
+
+Use this reference during a deep whole-project dig to reconstruct the durable project knowledge EWAI would normally have captured while the system was conceived, designed, built, validated, operated, and improved.
+
+## Reconstruction principle
+
+Work capability by capability, then reconcile across the whole system. For each material capability, inspect every SPECS area and every applicable delivery stage. Do not treat an empty area as implicitly complete: record it as not applicable, blocked, or a visible knowledge gap.
+
+Reconstruct records under the archaeology bundle first:
+
+```text
+SPECS/3.Evidence/archaeology/<date>-<slug>/
+├── specs-reconstruction-ledger.yaml
+├── capability-catalog.yaml
+├── archaeology-artifact-manifest.yaml
+└── proposals/
+    └── SPECS/
+        ├── 1.Scope/
+        ├── 2.Purpose/
+        ├── 3.Evidence/
+        ├── 4.Constraints/
+        ├── 5.Strategy/
+        └── 6.Build/
+```
+
+The proposals tree mirrors the canonical destination. Promote reviewed records into the project SPECS without losing the archaeology provenance link.
+
+## SPECS reconstruction matrix
+
+### 1.Scope — what the system contains and touches
+
+Attempt to reconstruct:
+
+- system context, boundaries, repositories, runtime surfaces, actors, external systems, and ownership;
+- domain glossary, entities, relationships, bounded contexts, lifecycle states, and invariants;
+- personas grounded in actual roles or research, clearly separated from inferred actors;
+- API, event, command, integration, and data-contract inventories;
+- research, source material, templates, and inter-team handoffs visible in the record.
+
+Typical evidence includes routes, schemas, models, interfaces, UI labels, integration adapters, ownership files, tickets, transcripts, and recurring terminology.
+
+### 2.Purpose — why capabilities exist and what outcomes they serve
+
+Attempt to reconstruct:
+
+- project and capability intents;
+- user, operator, administrator, support, and failure-recovery journeys;
+- functional and non-functional requirements, including those encoded only in tests;
+- acceptance criteria, success measures, non-goals, dependencies, and open decisions;
+- explorations and discussions that materially changed scope or behavior.
+
+Implementation can establish observable behavior, not business approval. Mark inferred purpose and retrospective acceptance criteria for human confirmation.
+
+### 3.Evidence — what supports, challenges, or explains the knowledge
+
+Attempt to reconstruct:
+
+- evidence ledgers, test-derived behavior, validation outcomes, and gate evidence;
+- a project security review and code-quality review, with material findings split into individual risks, constraints, technical-debt entries, patterns, decisions, or remediation candidates;
+- incidents, regressions, postmortem signals, risks, technical debt, and unresolved contradictions;
+- iteration history, delivery evidence, manual-validation evidence, and operational observations;
+- retrospectives and lessons suggested by later fixes, reversals, or repeated mistakes;
+- compliance-applicability candidates awaiting qualified review.
+
+Absence of evidence is itself a recorded gap; never convert it into a passed gate.
+
+### 4.Constraints — rules the project appears required to obey
+
+Attempt to reconstruct:
+
+- engineering, architecture, security, privacy, accessibility, data, testing, and operational constraints;
+- organisation or tenant isolation, identifier, validation, response, audit, retention, and deployment rules;
+- external obligations and compliance constraints only when supported by an authoritative source and qualified owner;
+- exceptions, compensating controls, expiry or review dates, and observed violations.
+
+A repeated implementation convention is a candidate constraint or pattern, not automatically a binding standard.
+
+### 5.Strategy — how and why the system takes its current shape
+
+Attempt to reconstruct:
+
+- system context, runtime topology, component boundaries, data architecture, integration architecture, and technology stack;
+- architectural and implementation patterns, anti-patterns, checklists, and reusable conventions;
+- ADRs for material architectural, product, security, data, delivery, and operational decisions;
+- option records showing alternatives genuinely evidenced as considered, evaluation criteria, trade-offs, and the selected outcome;
+- SOPs, runbooks, recovery procedures, maintenance practices, and context capsules.
+
+For a reconstructed ADR, separate:
+
+1. the decision outcome observed in live code;
+2. the historical context supported by evidence;
+3. alternatives demonstrably considered in commits, PRs, issues, docs, or testimony;
+4. plausible alternatives that still need confirmation;
+5. consequences observed later;
+6. current status: active, superseded, drifted, partial, or unknown.
+
+Never say an option was considered merely because it would have been reasonable.
+
+### 6.Build — how individual capabilities appear to have been delivered
+
+Attempt to reconstruct, where evidence survives:
+
+- intent trackers and phase history;
+- design and prototype references;
+- implementation and test plans;
+- task graphs, dependencies, sequence, handoffs, approvals, and blockers;
+- standards sweeps, test execution, external review, delivery, manual QA, and retrospective outcomes;
+- links between commits, releases, migrations, incidents, and the capability they changed.
+
+Mark reconstructed build records as historical. Do not create a false active run, claim a gate passed without evidence, or fabricate plans that never existed.
+
+## Fourteen-stage lifecycle pass
+
+For each reconstructed intent, look for evidence of the configured EWAI stages:
+
+1. ideate;
+2. intent;
+3. reconcile;
+4. plan;
+5. pattern-validation;
+6. test-plan;
+7. validate-external-plan;
+8. validate-external-test-plan;
+9. build;
+10. standards-sweep;
+11. test-execute;
+12. validate-external-code;
+13. delivery;
+14. retro.
+
+Also inspect conditional UI design, fit-check, and manual-QA evidence. Record each stage as evidenced, partial, absent, not applicable, or unknown. Provider-gated validation is evidenced only when a real provider result survives; never infer it from code quality or a commit message.
+
+## Reconstruction ledger
+
+Give each candidate record an entry in `specs-reconstruction-ledger.yaml`:
+
+```yaml
+- id: REC-001
+  capability: Alert escalation
+  specs_area: 5.Strategy
+  record_type: adr
+  proposed_path: SPECS/5.Strategy/decisions/ADR-REC-alert-escalation.md
+  lifecycle_stages: [reconcile, plan, build, delivery]
+  reconstruction_state: proposed-observed
+  temporal_window:
+    first_evidence: 2024-02-10
+    last_confirmed: 2025-11-03
+  evidence: [ARC-021, ARC-034]
+  unknowns:
+    - Whether polling was formally compared with event-driven delivery.
+  review_owner: Technical owner
+  review_status: pending
+```
+
+Use these reconstruction states:
+
+- `existing-aligned`: a canonical record exists and agrees with current evidence;
+- `existing-drifted`: a canonical record exists but conflicts with current evidence;
+- `proposed-observed`: the candidate record describes directly observable or corroborated facts;
+- `proposed-inferred`: material purpose, rationale, chronology, or relationship still needs confirmation;
+- `blocked`: evidence or a qualified reviewer is unavailable;
+- `not-applicable`: the record type genuinely does not apply to this capability.
+
+## Completion check
+
+A deep whole-project reconstruction is not complete until:
+
+- every material capability has been checked against all six SPECS areas;
+- every reconstructed intent has a fourteen-stage lifecycle assessment;
+- architecture, patterns, ADRs, options, workflows, requirements, constraints, evidence, delivery history, and learning are present or have an explicit gap status;
+- proposed records link to evidence and retain uncertainty;
+- cross-capability records have been consolidated without erasing meaningful differences;
+- accountable reviewers have accepted, corrected, rejected, or explicitly deferred promotion.
+
+After curation, keep reconstructed historical records and remediation work separate from prospective work. Always make the explicit three-route prospective offer: interview the owner, ingest a roadmap/feature list/discovery folder, or generate EWAI's evidence-based recommendations. Record the choice or explicit decline in `future-work-transition.yaml`. Existing remediation intents do not satisfy this gate. Offer to turn user-supplied upcoming features, reviewed imported discovery material, or accepted AI recommendations into lightweight feature candidates. Promote a candidate to a full intent only after it meets the intent contract and the user approves it.
+
+Completeness means maximum-detail accounting and individual record production, not invented documentation and not an arbitrary target number of files. A small set of composite drafts is not complete accounting.

package/skills-src/ewai-archaeology/references/maximum-detail-reconstruction.md

@@ -0,0 +1,97 @@
+# Maximum-detail SPECS reconstruction
+
+Read this completely before producing Archaeology proposals. Its purpose is to prevent a broad analysis from being mistaken for a recreated project knowledge base.
+
+## Required outcome
+
+Recreate the maximum amount of detailed SPECS knowledge reasonably discernible from the available evidence. Produce the records EWAI would have accumulated while the project was discovered, designed, built, tested, delivered, operated, corrected, and improved.
+
+The output is not an executive summary, assessment, representative sample, awareness pack, or fixed quota. The target is every individually discernible record. More evidence should normally produce more records.
+
+## Enumerate capabilities first
+
+Create `capability-catalog.yaml` with schema `ewai.archaeology-capability-catalog/v1` before reconstructing records. Discover capabilities from:
+
+- user-visible routes, screens, navigation, commands, and APIs;
+- controllers, services, use cases, jobs, events, listeners, notifications, and workflows;
+- models, state machines, schemas, migrations, relationships, and lifecycle transitions;
+- administrative, operational, support, reporting, billing, security, and recovery functions;
+- integrations, providers, webhooks, protocols, imports, exports, scheduled work, and reconciliation;
+- tests, fixtures, feature flags, hidden routes, deleted documentation, branches, incidents, and historical commits.
+
+Do not merge capabilities merely because they share a controller, screen, service, or domain. Preserve different user outcomes, workflows, rules, risks, and decision histories.
+
+Each capability entry requires an identifier, substantive description, actors, entry points, dependencies, evidence references, first and latest observed dates where available, and current state.
+
+## Build the target inventory
+
+Create `archaeology-artifact-manifest.yaml` with:
+
+```yaml
+schema: ewai.archaeology-artifact-manifest/v1
+depth: maximum-discoverable-detail
+records:
+  - id: ART-0001
+    subject: alert-delivery
+    family: purpose.workflows
+    record_type: workflow
+    title: Multi-channel alert dispatch
+    status: created
+    proposed_path: proposals/SPECS/2.Purpose/journeys/alert-delivery/multi-channel-dispatch.md
+    evidence: [ARC-001, ARC-014]
+    review_owner: Product owner
+```
+
+Use `subject: project` for cross-cutting records. Use a capability identifier for capability-local records.
+
+The packaged `config/archaeology-record-families.yaml` and `ewai archaeology validate` command define the minimum families to account for. They are a floor, not a ceiling. Add multiple manifest rows whenever the evidence reveals multiple personas, intents, workflows, journeys, risks, requirements, constraints, patterns, ADRs, options, integrations, runbooks, incidents, or build histories in the same family.
+
+## Preserve record granularity
+
+Create an individual proposed file for each discernible record:
+
+- one project persona per materially different actor perspective;
+- one intent per independently valuable outcome or capability;
+- one workflow or journey per distinct route through the system, including exception and recovery paths;
+- one risk entry per risk with its own cause, impact, control, owner, and treatment;
+- one ADR per decision with distinct context, outcome, alternatives, and consequences;
+- one option record per actual decision space or trade-off;
+- one pattern per reusable observed convention;
+- one integration record per external system, boundary, protocol, ownership, failure, retry, reconciliation, and security contract;
+- one runbook per operational procedure, failure scenario, recovery activity, or maintenance responsibility;
+- one historical Build record per discernible intent or delivery episode.
+
+Create indexes, catalogs, registers, maps, ledgers, and analysis dossiers to navigate these records. They do not replace the underlying files and do not satisfy their manifest rows.
+
+Do not reuse one proposed path for multiple manifest rows. Do not place several unrelated ADRs, personas, workflows, risks, or runbooks into a composite draft to reduce output.
+
+## Account for the complete SPECS surface
+
+For every material capability, account for:
+
+- Scope: domain language, actors/personas, boundaries, interfaces, APIs, events, commands, data, and integrations;
+- Purpose: intent, workflows, journeys, functional and non-functional requirements, acceptance criteria, outcomes, and non-goals;
+- Evidence: tests, risks, incidents, operational evidence, technical debt, validation, contradictions, and learning;
+- Constraints: engineering, architecture, security, privacy, data, accessibility, testing, compliance, and operational rules;
+- Strategy: architecture, stack, patterns, anti-patterns, ADRs, decisions, options, SOPs, runbooks, observability, recovery, and continuity;
+- Build: prototypes, plans, tasks, dependencies, gates, tests, reviews, releases, deployment, manual QA, retrospectives, and iteration history.
+
+For the project as a whole, additionally populate the domain and system context, persona library, integration catalog, API/event/command catalog, journey and requirement indexes, risk register, test coverage, security review, code-quality review, incident catalog, technical-debt catalog, standards, architecture set, pattern library, ADR index, options register, SOP and runbook indexes, observability, recovery, deployment history, and lifecycle reconstruction.
+
+## Use exception states honestly
+
+Allowed terminal states are:
+
+- `created`: an individual detailed proposal exists and cites evidence;
+- `not-applicable`: investigation evidence and a substantive rationale show the family genuinely does not apply;
+- `blocked`: a named owner or unavailable evidence prevents reconstruction and a concrete next action is recorded.
+
+Do not use `not-applicable` because evidence was not inspected, time is short, the output would be large, or a dossier mentions the subject. Do not use `blocked` for ordinary uncertainty that can be represented in a detailed draft.
+
+## Validate before review
+
+Run the maximum-detail validator after all passes. It checks the required catalogs and ledgers, every capability/family combination, project-wide families, individual proposal paths, evidence references, artefact substance, and exception-state justification.
+
+Validation passing means `Investigation ready for review`; it does not mean Archaeology is complete. After review, promote accepted records throughout canonical SPECS, retain rejected and unresolved material with provenance, update indexes, and rerun consistency checks.
+
+Offer self-review/manual filing or an AI-guided walkthrough. Automatic curation requires explicit consent and must never overwrite a differing canonical record. After curation, prospective recommendations and feature candidates may be created from the accepted baseline, but they remain distinct from reconstructed historical records and become intents only with user approval.

package/skills-src/ewai-archaeology/references/model-routing.md

@@ -0,0 +1,26 @@
+# Archaeology model routing
+
+Read this before delegating a security or trust review. Keep model selection bounded to that pass; the user may continue the main Archaeology conversation with their chosen model.
+
+## Claude Code
+
+For the security and trust pass, invoke the installed `ewai-security-reviewer` subagent. Its definition sets `model: opus`, read-only tools, and `permissionMode: plan`. When invoking it dynamically, keep the per-invocation model set to `opus`; do not use `inherit`. The `opus` alias intentionally resolves through Claude Code's current model configuration, so a future EWAI release can change this policy without pinning every project to a dated model identifier.
+
+Use a defensive, read-only task description. State that the purpose is to document observable controls, gaps, risks, and test evidence in software the user is authorised to assess. Request no credential discovery, exploitation, persistence, evasion, destructive action, or access outside the agreed repository.
+
+If Opus is unavailable or returns a provider policy refusal:
+
+1. preserve its transcript and any completed evidence;
+2. retry the bounded pass once with per-invocation model `sonnet` and the same defensive scope;
+3. do not weaken safety wording, disguise the task, or repeatedly retry a refusal;
+4. if Sonnet also refuses or is unavailable, mark the security-review coverage surface and manifest records `blocked`, name the project owner as the validation owner, record the provider responses, and set the next action to an authorised manual or alternative-provider defensive review.
+
+Do not mark the security review complete based on a partial or refused pass. Continue unrelated Archaeology passes and preserve their completed results.
+
+## Other providers
+
+Use the strongest available model explicitly approved for defensive code review in that provider's project configuration. If no suitable model is configured, keep the security pass visible as blocked rather than silently substituting an unapproved external validator.
+
+## Evidence
+
+Record the provider, requested model alias or identifier, resolved model when visible, pass start and finish time, outcome, refusal or fallback reason, examined boundary, and evidence IDs. Model choice is operational evidence, not proof of review quality or security assurance.

package/skills-src/ewai-architecture/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: ewai-architecture
+description: Facilitate an evidence-led enterprise or solution architecture walkthrough and turn reviewed choices into project-local SPECS standards, patterns, ADRs, risks, options, diagrams, and architecture records. Use for a whole enterprise or solution, a bounded aspect, capability, or domain, one or more intents, or a cross-cutting concern such as data, integration, security, resilience, observability, identity, or deployment—especially when current state, target state, trade-offs, or technical direction need accountable human decisions before delivery.
+---
+
+# EWAI Architecture
+
+Shape architecture as a human-owned body of project knowledge, not as a one-off AI diagram. Separate what is **observed**, what is **proposed**, and what has been explicitly **accepted**. Architecture work changes no application code and never begins Build.
+
+Resolve the workspace and `specsRoot` from `.ewai-pipeline/project.json`. Read [the architecture contract](references/architecture-contract.md) completely before producing, reviewing, or filing records.
+
+## Establish the boundary
+
+Ask one question at a time. First establish:
+
+- whether the boundary is the whole enterprise or solution, a bounded aspect, capability, or domain, one or more intents, or a cross-cutting concern;
+- whether the user needs current-state understanding, a target state, a current-to-target transition, or a specific decision;
+- the business outcome, decision horizon, accountable owner, material constraints, and what is deliberately out of scope.
+
+For an existing system, read accepted SPECS, reviewed Archaeology or Context Import evidence, relevant code and tests, diagrams, configuration, runtime evidence, and Git history before asking the owner to repeat known facts. For a new system without confirmed purpose, hand off to `$ewai-project-discovery` first. A technology-stack choice is an architecture input, not a substitute for the architecture walkthrough.
+
+## Route useful personas
+
+Run `ewai persona index --project <path> --json` and query for enterprise and solution architecture, business capability, domain and data, integration, security, operations, resilience, and governance perspectives.
+
+- Prefer the installed premium `enterprise-architect` persona when access and installation make it available.
+- Select only the additional installed personas that materially improve the bounded review.
+- Explain the proposed ensemble and perspective gaps before using it.
+- Ask before synchronising or updating a premium library.
+- Never recreate, paraphrase, or simulate an unlicensed premium persona.
+- Treat personas as advisory lenses. Repository evidence and accountable humans outrank persona opinion.
+
+Record the selection and rationale in `persona-routing.yaml` inside the review bundle.
+
+## Build an evidence-led view
+
+Create a bundle at:
+
+```text
+SPECS/3.Evidence/architecture/<YYYY-MM-DD>-<scope-slug>/
+├── scope.yaml
+├── evidence-ledger.yaml
+├── viewpoint-matrix.yaml
+├── persona-routing.yaml
+├── current-state.md
+├── target-state.md
+├── transition-and-gaps.md
+├── open-questions.md
+├── review-ledger.yaml
+└── proposals/SPECS/
+```
+
+Tailor the work to the boundary, but explicitly assess the applicability of every contract viewpoint: business and capability, domain and information, application and service, integration, technology and deployment, security and trust, operations and resilience, and governance and evolution.
+
+For every material claim, record its source, classification, confidence, contradiction, and owner. Code can prove current implementation but not intended business policy. Do not describe an option as historically considered unless evidence or attributed testimony says it was.
+
+## Develop the architecture conversationally
+
+Explain discoveries in human language. Ask one focused question at a time, preferably one that resolves several linked records without conflating different decisions. Use the walkthrough to surface:
+
+- capabilities, boundaries, ownership, dependencies, and quality attributes;
+- domain concepts, information ownership, lifecycle, residency, and classification;
+- application responsibilities, service contracts, coupling, reuse, and buy/build choices;
+- integrations, protocols, trust boundaries, failure handling, and reconciliation;
+- technology, environments, deployment topology, scalability, portability, and lifecycle;
+- identity, authorization, privacy, threat assumptions, audit, and assurance;
+- availability, recovery, observability, support, change, incident, and capacity practices;
+- governance, principles, exceptions, roadmaps, deprecation, and decision review triggers.
+
+Record alternatives and trade-offs before recommending a direction. A recommendation remains proposed until an accountable person accepts it.
+
+## Produce individual SPECS proposals
+
+Mirror proposed destinations under `proposals/SPECS/`. Produce one individual record for each discernible ADR, option, standard, pattern, anti-pattern, risk, integration, architecture view, transition, runbook, or governance rule. Indexes and summaries help navigation but never replace the detailed records.
+
+Use the project’s SPECS form inside each record: Scope, Purpose, Evidence, Constraints, and Strategy. Give every diagram a text source such as Mermaid or PlantUML plus an accessible narrative; a rendered image alone is not durable architecture knowledge.
+
+Candidate binding rules stay proposed. Only reviewed architecture constraints and standards belong under `SPECS/4.Constraints/`; accepted architectural direction, views, patterns, options, decisions, and roadmaps belong under `SPECS/5.Strategy/architecture/` or the project’s existing more-specific Strategy folders.
+
+## Review and promote deliberately
+
+Offer either self-review/manual filing or an AI-guided walkthrough. For the guided route, present small coherent groups and let the user accept, correct, reject, or defer each proposal. Do not infer approval from silence, agreement with a summary, or acceptance of a related record.
+
+Before promotion:
+
+1. validate the proposal bundle against the architecture contract;
+2. show every canonical destination and conflict;
+3. require explicit approval for the records being filed;
+4. refuse to overwrite differing canonical knowledge without a resolved correction or supersession decision;
+5. copy only accepted records out of `proposals/SPECS/`;
+6. record destination, provenance, decision, owner, and timestamp in `review-ledger.yaml`;
+7. update applicable standards, decision, pattern, risk, and architecture indexes.
+
+When accepted architecture reveals delivery work, offer `$ewai-shape-intents` or `$ewai-intent`. Obtain separate approval before creating intents, and do not start their delivery automatically.
+
+## Coordinate with the EWAI lifecycle
+
+- **Discovery:** use this skill after purpose and material stack choices are understood, or to resolve them when they require a deeper architecture decision.
+- **Archaeology:** consume reviewed reconstructed current-state evidence; use this skill for accountable target-state and transition decisions rather than relabelling inference as accepted design.
+- **Delivery:** when an intent exposes an unresolved consequential architectural choice, pause the relevant Think phase, run this bounded walkthrough, file accepted records, then resume `$ewai-deliver` at the same phase.
+- **Standards Check:** use `$ewai-standards-check` later to validate implementation against accepted standards, patterns, ADRs, and constraints.
+- **Retro:** route accepted learning back into the architecture records and their review triggers.
+
+## Completion boundary
+
+The walkthrough is complete when the agreed boundary and viewpoints have evidence-backed current state, explicit target decisions or owned unknowns, individually reviewable proposals, a recorded human disposition, and a visible transition path where applicable.
+
+Do not write implementation code, silently make an architecture decision, or mark a delivery gate passed. Never begin Build.

package/skills-src/ewai-architecture/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EWAI Architecture"
+  short_description: "Shape solution architecture into SPECS"
+  default_prompt: "Use $ewai-architecture to walk through this solution architecture and prepare reviewable SPECS records."

package/skills-src/ewai-architecture/references/architecture-contract.md

@@ -0,0 +1,176 @@
+# EWAI Architecture Contract
+
+Use this contract to validate an architecture walkthrough and its SPECS proposals. It applies at enterprise, solution, capability, domain, intent, and cross-cutting-concern scope. Applicability may vary; silent omission is not allowed.
+
+## 1. Scope record
+
+`scope.yaml` must record:
+
+```yaml
+schema: ewai.architecture-scope/v1
+id: architecture-<date>-<slug>
+title: Human-readable title
+scope_type: enterprise | solution | capability | domain | intent | cross-cutting
+mode: current | target | current-to-target | decision
+scope_refs: []
+business_outcome: ""
+decision_horizon: ""
+accountable_owner: ""
+included: []
+excluded: []
+constraints_known: []
+status: proposed | in-review | reviewed
+```
+
+If the scope changes materially, update it and disclose which records need reassessment.
+
+## 2. Truth classifications
+
+Every material claim in `evidence-ledger.yaml` has an ID and exactly one classification:
+
+- `observed`: directly supported by a cited artefact, runtime observation, or attributed testimony;
+- `inferred`: the best explanation of evidence, but not confirmed intent;
+- `proposed`: a future choice, recommendation, standard, pattern, or target;
+- `accepted`: explicitly approved by the named accountable owner;
+- `rejected`: explicitly declined;
+- `superseded`: once valid but replaced by a cited later decision;
+- `contradicted`: credible sources disagree;
+- `unknown`: evidence is not currently sufficient.
+
+Each claim records source locations, capture date, confidence, contradictions, affected records, and validation owner. A file path without a relevant section, symbol, commit, test, or quoted human attribution is weak evidence. Repeated code is not automatically an accepted pattern.
+
+## 3. Architecture viewpoints
+
+Record each viewpoint as `applicable`, `not-applicable`, `unknown`, or `deferred`, with rationale and owner in `viewpoint-matrix.yaml`.
+
+### Business and capability
+
+Cover outcomes, capabilities, value streams, users and stakeholders, ownership, dependencies, organisational boundaries, service levels, and business change. Candidate outputs include capability maps, context views, principles, ownership decisions, and outcome measures.
+
+### Domain and information
+
+Cover bounded contexts, ubiquitous language, information ownership, authoritative sources, data movement, lifecycle, quality, classification, residency, retention, deletion, lineage, reporting, and analytics. Candidate outputs include domain models, data architecture, classification standards, lifecycle rules, and ADRs.
+
+### Application and service
+
+Cover application responsibilities, service boundaries, interfaces, shared capabilities, coupling, cohesion, state, workflows, buy/build/reuse, versioning, and retirement. Candidate outputs include system context, container/component views, service contracts, patterns, anti-patterns, and decisions.
+
+### Integration
+
+Cover internal and external systems, protocols, schemas, identity propagation, trust boundaries, synchronous/asynchronous choices, ordering, idempotency, retries, timeouts, reconciliation, rate limits, ownership, observability, and failure handling. Candidate outputs include an integration catalogue, sequence/data-flow diagrams, integration standards, ADRs, and runbooks.
+
+### Technology and deployment
+
+Cover languages, frameworks, runtimes, platforms, data stores, environments, topology, networking, tenancy, configuration, secrets, build and release, portability, scaling, cost, support status, licensing, end-of-life, and technology lifecycle. Candidate outputs include stack strategy, deployment views, technology standards, lifecycle risks, and options.
+
+### Security and trust
+
+Cover identity, authentication, authorization, least privilege, tenancy, threat assumptions, attack surfaces, data protection, encryption, secrets, audit, supply chain, privacy, abuse, incident response, and assurance ownership. Candidate outputs include trust-boundary diagrams, risks, constraints, controls, security ADRs, and verification requirements. This is architecture analysis, not penetration testing, legal advice, certification, or a compliance attestation.
+
+### Operations and resilience
+
+Cover availability, capacity, performance, failure modes, backup, recovery objectives, disaster recovery, observability, alerting, support ownership, deployments, rollback, maintenance, incidents, continuity, and operational readiness. Candidate outputs include quality-attribute scenarios, SLO proposals, runbooks, recovery architecture, observability standards, risks, and readiness criteria.
+
+### Governance and evolution
+
+Cover architecture principles, decision rights, standards ownership, exceptions, fitness functions, conformance, technical debt, roadmaps, transition states, migration, deprecation, review triggers, and learning. Candidate outputs include governance records, exception processes, transition roadmaps, decision and standards indexes, and fitness functions.
+
+## 4. Current state, target state, and transition
+
+Current state contains only observed facts and clearly labelled inferences. Target state contains proposed or accepted decisions, never retrospective claims about existing behaviour. `transition-and-gaps.md` maps each material gap to:
+
+- current evidence;
+- desired outcome or target decision;
+- affected capability and quality attribute;
+- dependency and sequencing;
+- risk of change and risk of no change;
+- migration, coexistence, rollback, and decommissioning considerations;
+- verification evidence and accountable owner;
+- related intent or explicitly unplanned work.
+
+A target-state diagram without a transition path is incomplete when a current system exists.
+
+## 5. Evidence ledger and review ledger
+
+The evidence ledger must make it possible to trace a proposal back to evidence and a canonical record back to its approval. `review-ledger.yaml` records, per individual proposal:
+
+```yaml
+- proposal: proposals/SPECS/5.Strategy/decisions/ADR-0001-example.md
+  disposition: accepted | accepted-with-corrections | rejected | deferred
+  owner: ""
+  decided_at: ""
+  rationale: ""
+  canonical_destination: ""
+  conflicts: []
+  supersedes: []
+```
+
+One answer may resolve several proposals only when the skill lists them first and confirms that the same decision genuinely applies to each. Clarification is not approval.
+
+## 6. Individual proposal contract
+
+Create one individual record per material decision, standard, pattern, risk, integration, view, or runbook. Composite reports and indexes cannot satisfy this requirement.
+
+Every proposal contains the SPECS headings:
+
+- **Scope:** boundary, applicability, owners, related capabilities and records;
+- **Purpose:** outcome, problem, or quality attribute served;
+- **Evidence:** claims and citations, confidence, contradictions, validation approach;
+- **Constraints:** binding inputs, limits, obligations, non-goals, and exceptions;
+- **Strategy:** proposal, alternatives, trade-offs, consequences, transition, and review triggers.
+
+### ADR minimums
+
+An ADR additionally records proposed/accepted/superseded status, context, decision drivers, options actually considered, decision, positive and negative consequences, validation, and revisit triggers. Do not invent historical alternatives.
+
+### Standard minimums
+
+A standard additionally records normative language, applicability, rationale, examples, enforcement or fitness functions, evidence expected, exception authority, and review cadence.
+
+### Pattern minimums
+
+A pattern additionally records problem/context, forces, solution, consequences, implementation guidance, known uses supported by evidence, anti-patterns, tests or conformance checks, and exceptions.
+
+### Integration minimums
+
+An integration record additionally covers owners, systems, purpose, direction, protocol, schema/contract, identity and trust, data classification, availability, retries/timeouts/idempotency, reconciliation, rate limits, observability, failure modes, test strategy, change/versioning, and support runbook.
+
+### Risk minimums
+
+A risk additionally records cause, event, impact, likelihood, severity, affected assets/capabilities, current controls, proposed treatment, owner, evidence, review date, and residual risk decision.
+
+## 7. Diagram contract
+
+Every diagram has an editable text source, preferably Mermaid or PlantUML, stored beside or inside its record. It also has an accessible narrative explaining actors, boundaries, flows, trust transitions, and important omissions. Rendered images are derived evidence, never the sole source.
+
+Use the smallest views that answer the decision. A single enormous system diagram is not a substitute for context, container/service, integration/data-flow, deployment, trust-boundary, and transition views when those are applicable.
+
+## 8. SPECS routing
+
+Use the project’s existing taxonomy when it is more specific. Otherwise route proposals as follows:
+
+| Record | Proposed destination |
+|---|---|
+| Context, capabilities, actors, domain language, system boundaries | `SPECS/1.Scope/` |
+| Outcomes, journeys, workflows, requirements, intent relationships | `SPECS/2.Purpose/` |
+| Evidence ledger, assessments, risk, quality-attribute evidence | `SPECS/3.Evidence/` |
+| Binding architecture, security, data, integration, operational, or engineering standards | `SPECS/4.Constraints/` |
+| Architecture views, stack, patterns, options, roadmaps, ADRs, governance, runbooks | `SPECS/5.Strategy/architecture/` or the established Strategy subfolder |
+
+Update relevant standards, ADR, pattern, integration, risk, and architecture indexes when promoting accepted records. Never overwrite a differing canonical record without explicit correction or supersession.
+
+## 9. Completion checks
+
+Before review, confirm:
+
+- scope, mode, owner, and exclusions are explicit;
+- every viewpoint has a status and rationale;
+- current state and target state are not conflated;
+- material claims have evidence classifications and owners;
+- each material proposal has its own record;
+- options and trade-offs precede recommendations;
+- every diagram has text source and narrative;
+- open questions and contradictions remain visible;
+- risks, operations, security, integration, governance, and transition have not been silently skipped.
+
+Before promotion, confirm explicit record-level decisions, canonical destination preflight, conflict handling, provenance, and index updates. Promotion does not approve an intent, pass a delivery phase, or authorize Build.