# Software Profile

Status: v0.8; optional filesystem example for software Projects
Author: Franz Bruckhoff

This profile helps a software Project apply the [Normative Structural Specification](https://think-bigger.org/framework/guides/v1.0/specification.md), version 1.0. It offers one filesystem arrangement for the required records. The Specification determines their content, multiplicity, relationships, and authority. This profile adds no framework requirements and does not override the Specification.

The paths, formats, and record conventions below are choices for this example. A Project can choose other bindings that satisfy the Specification. Markdown and `REGISTRY.json` are not required by the framework. The exception is the Entry Point: §14.3 requires the name `INDEX` at the root of the Project Record, with an extension appropriate to its format.

## Adoption

For the working procedure, read the Software Engineering Guide.

For agent instructions, use the [Framework Adoption and Execution Guide for AI Agents](https://think-bigger.org/framework/guides/v1.0/software.md).

Prepare a complete Path Map in the Project's Entry Point. Use the example below as a starting point, adapt it to the Project, and include all binding rules and format definitions needed for local resolution. Naming this profile and recording only overrides does not meet §14.8. The Project may record the profile version as provenance, but no binding may depend on fetching it.

Keep one binding rule for each required Entity, including Entities with no current instances where that multiplicity is permitted. Record additional artifact types when needed. Resolve every record without ambiguous matches. A valid choice of location or format needs no deviation; omission of a required Entity or departure from another binding clause requires the Deviation Matrix process (§1.5).

Before use, complete the Realization layout, the Project-specific format details, and the Entry Point declarations listed below. Creating the directories alone does not establish compliance.

## Optional filesystem example

The example places the Project Record in `record/` and the software Realization in a sibling `realization/`, under the same version control. All paths below are relative to the Project Record root. This is an example arrangement, not a required repository structure.

Patterns use case-sensitive, slash-separated paths. `*` matches within one path segment and never crosses `/`; `**` matches zero or more directory levels. An exact filename matches only that file. The example uses one directory segment for each Component identifier. If a Project chooses deeper nesting, it must change its local patterns and check them. Directory groups carry no Component dependency authority (§6.11).

### Required Entity bindings

Each row is one binding rule. Interface declarations have the two placements allowed by Appendix A: embedded declarations and standalone declarations. The embedded declarations are identified inside their containing Specification as described below; they do not give that whole file a second record type.

| Entity (Specification, Appendix A) | Multiplicity | Example location pattern | Example format |
| --- | --- | --- | --- |
| Vision Document | one | `VISION.md` | Markdown with metadata |
| Governing Principles | one | `PRINCIPLES.md` | Markdown with metadata |
| Entry Point | one | `INDEX.md` | Markdown with metadata |
| Registry | one | `REGISTRY.json` | JSON identity register |
| Component Specification | one per Component | `components/*/SPEC.md` | Markdown with metadata |
| Top-level System Specification | one | `system/SPEC.md` | Markdown with metadata |
| Interface declarations | one per interface; embedded or standalone | identified declarations within `components/*/SPEC.md` and `system/SPEC.md`; standalone declarations at `interfaces/*.md` | Markdown with metadata and stable declaration identifiers |
| Decision Records | one per binding decision | `decisions/*.md` | Markdown with metadata |
| Records of Exploratory Work Units | one per Exploratory Work Unit; none if none run | `experiments/records/*.json` | JSON experimental records |
| Work Record | one | `work/record.json` | JSON Work Unit and relation records |
| Plan Documents | one per Work Unit | `plans/units/*.md` | Markdown with metadata |
| Phase artifacts | at least one per Phase | `phases/*.md` | Markdown descriptions of Phase outputs |
| Design and planning documents | one per effort spanning more than one Work Unit; none if no such effort exists | `plans/designs/*.md` | Markdown with metadata |
| Verification Plan | one | `verification/PLAN.md` | Markdown with metadata |
| Verification Artifacts (Gate records, drift reports, quality record chain, Verification Reference State records, etc.) | one per verification event; element-local Verification Procedures live on the governed artifact | `verification/events/*.json` | JSON event records with evidence references |
| Baseline Ledger | one | `registers/baselines.json` | JSON register |
| Risk Register | one | `registers/risks.json` | JSON register |
| Status Ledger | one | `registers/status.json` | JSON register |
| Deviation Matrix | one | `registers/deviations.json` | JSON register |
| Key Design Parameter register | one | `registers/parameters.json` | JSON register |
| Criticality Record | one | `registers/criticality.json` | JSON register |
| Executor scope declarations | one per Executor | `scopes/*.md` | Markdown with metadata |
| Reusable task definitions | one per recurring kind of work | `procedures/*.md` | Markdown with metadata |
| Realization and its local documentation | one Realization; internal layout declared | `../realization/` | source, configuration, deployment material, and local documentation in declared native formats |

### Supporting bindings for this example

These rows supply homes for the example's supporting artifacts. They do not extend the Specification's required Entity set. A Project copies the rows it uses into its own Path Map and adds bindings for any other artifacts it retains.

| Supporting artifact | Example location pattern | Example format and use |
| --- | --- | --- |
| Component Governance Documents | `components/*/GOVERNANCE.md` | Markdown with metadata; binds to the named Component |
| Verification Procedures | `components/*/checks/*.py` and `verification/procedures/*.py` | Python source; Component-local and cross-Component procedures respectively |
| Normative Checks | `checks/*.py` | Python source; resolves record locations through the Path Map |
| Experimental data | `experiments/data/**/*.json`, `experiments/data/**/*.csv`, and `experiments/data/**/*.png` | JSON, CSV, and PNG; referenced by the experimental record |
| Verification evidence attachments | `verification/data/**/*.json`, `verification/data/**/*.txt`, and `verification/data/**/*.png` | JSON, UTF-8 text, and PNG; referenced by the event record |

The example Realization has `src/` for implementation and tests beside the code they check, `config/` for configuration, `deploy/` for build and deployment material, and `docs/` for documentation spanning the Realization. Documentation for a single element stays on or beside that element. The Project must replace or complete these subdivisions with its actual languages, formats, locations, and local Verification Procedures. The standing procedure corpus stays versioned with the System description (§7.6); test results belong to Verification Artifacts, not to the procedure corpus.

Add patterns for other retained formats before using them. A directory name alone does not identify its contents' formats. Temporary execution workspaces are separate from durable experimental records and are not a second canonical Project Record.

## Record and serialization conventions

The following conventions make the example checkable. They remain example choices. A Project may use other parseable formats, including structured Markdown tables, while preserving the content and controls required by the Specification (§§4.1–4.4). JSON below is a default for relational records, not a closed list of permitted formats.

### Identity and canonical content

Markdown records use a YAML metadata block with `id` and `entity` fields, followed by their required sections. JSON records use an object with `id`, `entity`, and `schema_version` fields. A register also has an `entries` array. Each record identifier is stable across moves and unique in the Project Record. The Project declares its parser, schema versions, field types, and link syntax in the Entry Point's format definitions. Technical attachments use an intrinsic identifier or a content digest resolved from their containing record; their current locations are derived from the stored artifacts.

An identifier inside a record does not replace its Path Map binding. Checks first locate files through the map, then check their identifiers, content, and links. Declare required fields for each record type from its governing clauses. In particular, retain Obligation attributes and Constraint provenance (§§6.5–6.9), Criticality Record rationales (§7.10), Baseline fields (§9.1), Status Ledger approval and change fields (§9.3), waiver fields (§9.4), and the two distinct risk closure routes (§12.1).

The top-level System Specification holds System-level commitments and the Operational Concept. Component Specifications hold the corresponding Component commitments and refer to their parent Obligations. Do not copy the System Contract into another file for the same concern. A Subsystem has its own Component Specification under its identifier and refers to the Specifications of its contained Components.

For an embedded interface, use a stable heading identifier, such as an explicit `id="IF-001"` anchor, within Dependencies & Interfaces. Its address is the containing Specification plus that fragment. Keep one canonical declaration for each interface and refer to it from the connected Specifications. A standalone declaration at `interfaces/*.md` has the same identifier convention. Each declaration retains the four elements and named change authority required by §6.10. Checks distinguish an embedded declaration from its containing Specification; they do not count references as new declarations.

A Phase artifact in this example describes what the Phase produced and links to the exact versions of its outputs and verification evidence. It does not repeat their Contracts or claim their authority. This gives the Phase its own durable description without making duplicate governing copies of existing Specifications (§§4.3, 8.1).

### Registry and derived locations

The example Registry's `entries` contain `id` and `entity` for each registered Component and content item. Component identities resolve through their Component Specifications. The resolver obtains current locations from identifiers embedded in the artifacts found through the Path Map. It checks uniqueness and rejects missing or ambiguous identities. It returns a location or fragment when queried; no manually maintained location column is stored in the Registry (§14.7).

Additions and removals update Registry identities in the same change. A move preserves identity and requires no Registry edit. Any saved location index, traceability view, or dependency graph is generated from canonical records and has its own supporting binding. It is not edited in parallel with those records (§§4.3, 10.1). Human decisions and approvals remain authored content. Baseline snapshot identifiers come from version control and resolve inside the Project Record (§9.1).

### Work, experiments, and verification

The singleton Work Record contains `units`, `relations`, and `discoveries` arrays in addition to its common metadata. Each unit has a stable identifier, scope, assigned Executor, Acceptance Criteria references, Plan Document reference, and status. Each relation names its source, type, and target, including `blocks`, `part-of`, and `supersedes` where applicable. Discoveries identify the Work Unit that produced them and their evidence. Query logic derives eligibility from unresolved blocking relations and releases dependents when those relations are resolved (§4.5). Unstructured prose lists are not an alternative Work Record.

Plan Documents retain their own scope, Acceptance Criteria, progress, and decisions under §4.6. Corresponding Work Record fields refer to that content or are derived from it rather than separately edited. Experimental records retain the approved question, resource limits, stopping criteria, run references, findings, and exact input versions (§§5.7, 6.13, 10.3).

Each verification event record identifies the procedure and version executed, criteria checked, exact input versions, outcome, verifying Executor or context, and evidence references. Records of a reference state include pre-existing failures or the absence of verification. Drift and quality-chain records link the related events and measurements. Normative Check runs also produce durable event records (§16.3). Attachments preserve the tool output needed to inspect each outcome.

A Gate closes through its Decision Record (§8.4). Verification event records link to that decision and its discrepancy disposition; they do not constitute a second approval. The Verification Plan names responsibilities, resources, completion criteria, and any Reference Realization designations, rationales, and comparison intervals (§§7.9, 7.17).

### Decision identity and status

Assign a stable number when a Decision Record is first created, including when it is proposed. Sequential allocation is one possible convention; acceptance order does not determine identity. Never renumber a record on acceptance or reuse its number. Use the statuses `proposed`, `accepted`, `deprecated`, and `superseded` (§11.2).

Preserve the recorded decision and its history. A later reversal is a new numbered record that points to the old one. A Project's status mechanism must retain the immutable prior record: for example, append a status event to the Status Ledger and derive the current status displayed with the Decision Record. Store and bind any generated view separately from the canonical decision. Check that every record resolves to a valid status and every supersession pointer resolves. A changed status must never silently replace the earlier decision, rationale, or approval.

## Access and authority

A filesystem layout does not enforce an Executor's scope. Before execution, configure permissions and the work interface so each Executor receives its Component's full Specification and only the Contracts of related Components (§6.3). For a Specification that contains private Design, the interface can generate a Contract-only view. Do not give that Executor unrestricted read access to the source file containing another Component's Design. Generated views remain derived and do not become editable Contracts.

Enforce declared write boundaries, human approval of Production Work Unit plans, and isolation of exploratory work (§§6.13, 13.1–13.3). Use a controlled recording process to retain exploratory results in the Project Record without giving exploratory Executors write access to the canonical System description or Realization. Record the independent verification outcome before acceptance. Local Governance Documents remain human-authored and controlled, apply at their Component boundary, and obey the declared size ceiling (§§4.9, 14.2, 14.4).

## Completion and verification checklist

1. Put the full resolved Path Map, supporting bindings, pattern rules, and format definitions in the Entry Point. Keep it short by stating bindings and linking to content rather than copying that content. No check may need this external profile to resolve a binding.
2. Declare Stability Classes and their order; the Decision Record significance test; Baseline levels and their lock Gates; and change classification dimensions (§14.3). Include the minimum Baseline levels and change dimensions required by §§9.1–9.2. Record permitted tailoring and non-applicable levels in the Criticality Record.
3. Complete the Realization's internal layout and formats. Give every retained artifact a resolvable binding. Confirm one instance for each singleton and the required counts for Components, Work Units, Phases, interfaces, Executors, and recurring work. Keep zero-instance bindings where permitted.
4. Check a representative file and a nested attachment for every pattern. Reject an unknown file type, duplicate identity, ambiguous match, unresolved link, or invalid schema. Confirm that moving an artifact within its binding preserves its identity and updates its derived location without a Registry edit.
5. Verify the required content and links, including the dependency graph, Obligation traceability, procedure links, human authorities, immutable decisions, Baseline snapshots, and separation of verification from acceptance. Check scope enforcement and Contract-only access as well as the declarations that describe them.
6. Run the mechanically applicable Normative Checks continuously and retain their outcomes. Use human review for requirements that need judgment. Record every accepted deviation explicitly. Passing a filename check alone is not acceptance of a Project's structure.

The Hardware Profile gives a second example, for physical systems. Further domain examples are planned; see TODO. This profile supplies an optional software layout, not an implementation of the checks or a substitute for the Specification.