# The full Intransic process Read this when running a **first-time build** against a repository, or a full reassessment. For a routine change or release, use the prompts in `prompts/` instead — they are shorter and scoped. The process is retrospective: it runs over a codebase that already exists and describes what is actually true of it. It is not a design exercise, and it does not improve the system. It makes the system's real state legible, and it makes claims about that state falsifiable. --- ## Phase 1 — Repository reconnaissance Inspect the whole repository before generating anything. At minimum: root documentation, package manifests, dependencies, source directories, API routes, database schemas and migrations, domain models, authentication and authorisation, data-access patterns, validation logic, error handling, logging and observability, background jobs, queues and event processing, infrastructure-as-code, deployment configuration, CI/CD, test structure, environment configuration, secrets handling, privacy controls, security controls, external integrations, generated documentation, ADRs, feature flags, and TODO/FIXME/deprecated paths. Where history is available, inspect enough of it to find major architectural decisions, replaced approaches, abandoned components, and decisions the documentation no longer reflects. Output → `intransic/internal/repository-assessment.md`, containing: **Repository identity** — purpose, primary users or consuming systems, core jobs, architecture style, runtime components, principal data stores, external dependencies, deployment model. **Current completeness** — estimated *per subsystem*, never as a single percentage. For each: status, evidence, confidence, significant missing work, and whether it blocks production readiness. **Documentation integrity** — documentation supported by implementation; implementation missing documentation; outdated documentation; contradictory documentation; ambiguous areas. **Risk map** — critical / high / medium / low / informational, each with its consequence stated. Do not equate unfinished work with poor architecture. --- ## Phase 2 — Extract the Foundation `foundation/foundation.yaml` (canonical) and `foundation/FOUNDATION.md` (readable). The canonical, validated description of the system's identity, boundaries and invariants. It is authoritative over **what must remain true** — a change conflicting with `change_constraints` or a domain invariant requires explicit review. It is not authoritative over **what is currently true**: the Foundation is a document, and implementation and executed tests outrank it as evidence of present reality. Where the two disagree, record a contradiction and resolve it; never let a stale Foundation overrule working code, and never let code quietly redefine a ratified constraint. See the authority order in `SKILL.md`. Sections, populated only where evidence supports them: ```yaml foundation: identity: name, purpose, system_type, lifecycle_stage, primary_jobs, intended_consumers boundaries: in_scope, out_of_scope, trust_boundaries, ownership_boundaries, external_dependencies architecture: style, components, component_responsibilities, data_flows, integration_patterns, deployment_topology, synchronisation_patterns, failure_boundaries domain: core_entities, invariants, state_transitions, terminology, prohibited_states interfaces: public_apis, internal_apis, events, scheduled_jobs, schemas, compatibility_expectations data: classifications, stores, retention, residency, encryption, deletion, backup_and_recovery, data_minimisation identity_and_access: authentication, authorisation, roles, service_identity, tenant_isolation, privilege_constraints security: controls, threat_assumptions, secret_management, input_validation, dependency_controls, auditability, known_gaps privacy: personal_data, sensitive_data, consent, de_identification, access_controls, user_rights, known_gaps reliability: availability_assumptions, retry_behaviour, idempotency, timeouts, rate_limits, degradation_behaviour, recovery_expectations observability: logs, metrics, traces, audit_events, alerting, correlation, redaction engineering: languages, frameworks, conventions, test_strategy, branching_and_release, dependency_policy, migration_policy, configuration_policy change_constraints: must_remain_true, changes_requiring_review, prohibited_changes, backward_compatibility, security_review_triggers, privacy_review_triggers maturity: verified, partial, planned, unknown, contradicted evidence: sources, conflicts, unresolved_questions ``` Every significant element carries `status`, `confidence`, `evidence`, `last_validated`, `owner` where inferable, and `notes`. Extend the schema where the repository justifies it; do not overfit to it. `change_constraints.must_remain_true` is the highest-value section in the file. It is what a future contributor — human or agent — will breach without knowing. ### Go to field level for `data.classifications` A classification that stops at *"Personal identifiers: name, email, external identity subject"* describes a shape, not a checkable claim — a new field can be added to the system tomorrow and nothing here will know. Trace each class to its actual fields: ```yaml data: classifications: - class: Personal identifiers sensitivity: high examples: [name, email, external identity subject] fields: - path: Models/User.cs symbol: Email - path: Models/User.cs symbol: ExternalIdentitySubject ``` This is what lets the `pii_coverage` conformance-rule kind (see `intransic/validation/README.md`) scan real source for PII-shaped names and flag one absent from this list — a check on the Foundation from outside it, run regularly rather than only at the next full reassessment. ### Register every processor, not only what reads as an "integration" `privacy.processors` — cloud hosting, payment, the LLM provider, identity/auth, analytics, anything receiving personal or sensitive data: ```yaml privacy: processors: - name: … category: cloud_infrastructure | payment | llm_ai | identity_auth | analytics | communications | storage | other data_shared: [...] # in the same vocabulary as data.classifications basis: … # contract, consent, legitimate interest, legal obligation — state it jurisdiction: … evidence: [INT-001] ``` `F-11` requires every entry complete and its evidence resolved. This is bookkeeping, not a lawful-basis determination — it records that a basis was stated and can be checked, not that the stated basis is correct in law. --- ## Phase 3 — Build the evidence ledger `intransic/internal/evidence-ledger.yaml`. Source of truth behind every claim, public and internal. ```yaml - id: AUTH-001 category: authentication claim: Authentication is delegated to an external identity provider. status: verified confidence: high evidence: - type: implementation path: src/… symbol: … explanation: … - type: configuration path: … key: … explanation: … - type: test # strength: behavioural — what lets this be `verified` path: … test: … explanation: … contradictions: [] public_safe: true public_wording: Authentication is handled through a dedicated identity provider. internal_notes: … last_validated: YYYY-MM-DD ``` ID prefixes, stable across revalidations: `ARCH` `AUTH` `SEC` `PRIV` `DATA` `API` `REL` `OBS` `TEST` `OPS` `GOV` `INT`. ### Status follows evidence strength, not conviction Each item establishes something different, and `verified` is out of reach without `behavioural` evidence or better — an executed test, a direct observation, deployed configuration or an external audit. The strength ladder and its per-type defaults are in `SKILL.md`; `E-11` and `E-12` enforce them. Drop an item's strength explicitly when the citation is weaker than its type implies: ```yaml - type: implementation path: src/Ports/IEvidenceStore.cs symbol: IEvidenceStore strength: existence # interface only; no active implementation binds it explanation: … ``` The practical effect is that the claim in *What the first run taught*, below, could not have been marked `verified`: the rate-limit attributes were present in source — `implementation` strength — and nothing executed asserted them. The status available was `implemented_unverified`, and the Trust Wall would have said so. `public_wording` lives here, beside its evidence, because `trust/claims.json` is **generated** from the ledger. That is what stops public wording drifting away from what supports it. --- ## Phase 4 — Produce the Trust Wall ``` trust/ ├── README.md ├── privacy.md ├── trust-wall.md ├── reliability.md ├── claims.json ├── data-handling.md ├── architecture-summary.md├── development-practices.md ├── security.md ├── limitations.md └── verification-method.md ``` Factual, plain-language, useful to technical and non-technical readers, restrained rather than promotional, backed by evidence IDs, explicit about limitations, and clear about what has *not* been independently certified. Do not write "enterprise-grade", "bank-grade", "fully secure", "completely private", "compliant with all applicable laws", "production ready". The validator will reject them, but the reason matters more than the rule: an unverifiable superlative makes every verifiable claim beside it less credible. Write instead: "The repository currently implements…", "The system is designed to…", "Evidence reviewed on [date] shows…", "This control is implemented but has not been independently audited.", "This capability is partial.", "This remains a planned control." `trust-wall.md` covers, in order: what the system does · what was inspected · architecture overview · data handled · identity and access · security controls · privacy controls · reliability and recovery · observability and auditability · development and testing practices · known limitations · how claims are verified · last validation date · Foundation version · evidence coverage summary. Each claim carries a verification marker: ``` Status: Verified Evidence: SEC-004, AUTH-002 Last checked: 2026-07-25 ``` Public claims reference evidence IDs; the paths stay in the internal ledger. --- ## Phase 5 — Internal assets ``` intransic/ ├── README.md ├── config/ intransic.config.yaml · claim-policy.yaml · publication-policy.yaml ├── internal/ repository-assessment.md · evidence-ledger.yaml · │ contradiction-register.md · risk-register.md · maturity-map.md · │ documentation-drift.md · unresolved-questions.md · │ generation-report.md ├── schemas/ foundation.schema.json · evidence.schema.json · trust-claim.schema.json ├── validation/ README.md · validation-rules.yaml · validate_*.py ├── prompts/ repository-review.md · change-review.md · trust-wall-refresh.md · │ release-validation.md └── reports/ initial-validation-report.md ``` `intransic/internal/` is **internal-only**: repository paths, unmitigated weaknesses, active defect detail. `trust/` is its public counterpart. The validators ship in Python. If the repository has no Python and adding it is unwelcome, port them — the rules file is the contract, and it is language-neutral. Do not introduce a new language without a reason. --- ## Phase 6 — Validation rules See `validation/README.md`. Foundation integrity, Trust Wall integrity, and repository conformance. State for every check what it can and — more importantly — cannot establish. Static validation proves neither security nor correctness, and a check that implies otherwise is worse than no check. --- ## Phase 7 — Agent operating guide `AGENTS.md` at the repository root. If `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md` or an equivalent already exists, **preserve its useful content and propose an integration** — never blindly replace it. It should tell an agent: what to read before editing · the core purpose · architectural boundaries · domain invariants · security and privacy constraints · which files are authoritative · which are generated · prohibited actions · required tests · required Foundation updates · when human review is mandatory · how to cite evidence for a proposed change · how to identify contradictions · how to run validation. Include a mandatory pre-change and post-change checklist. --- ## Phase 8 — Reusable prompts Already written, in `prompts/`. Copy them across and fill in the repository-specific sections marked in `repository-review.md`. --- ## Phase 9 — Score the repository `intransic/reports/initial-validation-report.md`. Score separately — architecture clarity · documentation alignment · domain-model clarity · security evidence · privacy evidence · test evidence · reliability evidence · observability evidence · deployment evidence · AI-agent readiness · Trust Wall publishability · overall Foundation confidence. `0` no evidence · `1` fragmentary · `2` partial · `3` credible · `4` strong · `5` comprehensive and continuously validated. Each score carries a rationale, evidence IDs, the principal gap, and the recommended next action. **Do not average.** An average hides exactly the weakness the report exists to surface. List gating weaknesses separately and above the scores: a gating weakness blocks a production-ready designation whatever the scores say. --- ## Phase 10 — Implementation plan Prioritised, in three bands: **immediate** (assets that establish the Foundation without changing production behaviour), **pre-production** (material gaps to resolve before the system is considered production-ready), **post-launch** (continuous-assurance improvements that do not block release). Each action states: issue · consequence · proposed remedy · affected files · complexity (small/medium/large) · whether it changes runtime behaviour · whether human approval is required · whether it affects public Trust Wall claims. --- ## Judgement principles **Implementation versus intention.** A capability is implemented only when the operational path exists. An interface, type, mock, design document or dormant module is not sufficient. **Tests as evidence.** Tests evidence intended and exercised behaviour; they do not prove production operation. Distinguish unit-tested · integration-tested · end-to-end tested · manually verified · production-observed. **Security claims.** A framework default is not a control. Look for actual configuration and actual usage. **Privacy claims.** Account for the whole path: collection, transmission, storage, access, retention, deletion, logs, telemetry, third-party processors. A gap anywhere in that path defeats the claim. **Compliance claims.** Never infer legal or standards compliance from good engineering. Distinguish aligned with a control · partially implements a control · internally assessed · independently audited · certified. **Confidence.** `high` direct implementation plus corroboration · `medium` credible but incomplete · `low` primarily inferred · `unknown` the repository cannot support a conclusion. --- ## What the first run taught Recorded because both lessons cost something to learn. **1. Verify against current code, never against your own earlier finding.** On the first run, a control was live-tested and confirmed closed in the morning. By the afternoon, while pinning evidence for that same claim, the control was found to be absent — an unrelated merge had rewritten the file and dropped the enforcement. Nothing failed, because no test asserted any of it. Had the Trust Wall been generated from commit history, or from the assessor's own verified-that-morning note, it would have published a false security claim about a live gap. Re-read the file at the commit you are assessing. **2. A security property not asserted by a test will eventually be removed by someone who does not know it matters.** This is the single most useful sentence the process produced. An `R-*` rule is a backstop that catches a known-bad shape; only a test proves behaviour. When the assessment finds an unasserted security property, the finding is not "add a static check" — it is "add the test".