feat: support optional architecture.md as fifth spec artifact

[mickume]

Context

The spec format specification (docs/spec-format.md in af-spec) has been updated from v1.0 to v1.1 to introduce architecture.md as an optional fifth artifact in a spec package. Previously, architectural content (module responsibilities, components/interfaces, data models, technology stack) was dumped into prd.md optional sections, making the PRD a grab-bag mixing intent with architecture. The new format cleanly separates "why/what" (prd.md) from "how" (architecture.md).

What Changed in the Spec Format

• architecture.md is an optional free-form markdown file (no frontmatter, no JSON schema, no machine validation)
• A spec remains valid with four files; architecture.md is recognized when present
• The file can be created, modified, or deleted at any lifecycle stage
• Both operators and coordinators have write access (archetypes do not)
• It is exempt from schema validation and cross-file integrity checks
• In combined rendering, it appears between prd.md and the rendered JSON artifacts

Required Library Changes

File recognition

• architecture.md must be recognized as a valid file in a spec directory (not flagged as unknown)
• Its absence must NOT cause validation failures or incomplete-spec errors

Copy / move / archive operations

• When a spec is superseded, archived, or moved, architecture.md must move with the rest of the directory

Validation

• architecture.md must be excluded from schema validation (it has no schema)
• architecture.md must be excluded from cross-file integrity checks
• The completeness check must continue to require only the four JSON/markdown files (prd.md, requirements.json, test_spec.json, tasks.json)

Rendering

• Combined render must include architecture.md content (as-is) between prd.md and the rendered JSON artifacts, when present
• Per-file render is not applicable (the file is already markdown)

Spec type / model

• The Spec model should gain an optional field for the architecture content (e.g., architecture: str | None = None)
• I/O functions (load_spec, save_spec) should read/write architecture.md when present

Reference

• Spec format v1.1: docs/spec-format.md §5 in af-spec
• Key sections: §1 (scope/artifact table), §3.2 (completeness), §5 (architecture.md), §10 (validation), §11.3 (permissions), §12.1 (rendering)

[mickume]

Finalized PRD

This PRD was generated from this issue using the af-spec skill.
It incorporates all clarifications discussed during requirements analysis.

Support Optional architecture.md as Fifth Spec Artifact

Intent

Add support for architecture.md as an optional fifth artifact in a spec
package, as defined in spec-format.md v1.1. The library must recognize,
load, save, and render the file without requiring it for validity.

Background

The spec format specification (docs/spec-format.md) was updated from v1.0
to v1.1 to introduce architecture.md as an optional fifth artifact.
Previously, architectural content (module responsibilities, components and
interfaces, data models, technology stack) was placed in prd.md optional
sections, making the PRD a grab-bag mixing intent with architecture. The new
format cleanly separates "why/what" (prd.md) from "how" (architecture.md).

Goals

• Recognize architecture.md as a valid file in a spec directory
• Load its content into the Spec model when present
• Write it to disk when content is provided
• Include it in combined rendering at the correct position
• Exclude it from all validation (schema and cross-file)
• Ensure it moves with the rest of the directory during archive/supersede

Non-Goals

• Adding schema validation for architecture.md (it is free-form markdown)
• Adding frontmatter parsing for architecture.md
• Making architecture.md required for spec completeness
• Adding a dedicated render_architecture function (the file is already markdown)

Required Changes

Model

The Spec model gains an optional architecture field (str | None, default None).

I/O

• load_spec: Read architecture.md when present; leave as None when absent.
• save / _save_internal: Write architecture.md when non-None; don't touch disk when None.

Validation

• No changes needed — validation already only validates the four known artifacts.

Rendering

• render_combined: Include architecture content (as-is) between PRD body and rendered requirements when present.

Bootstrap

• BootstrapSpec gains set_architecture() method; finalize() passes it through.

Lifecycle / Archive / Discovery

• No changes needed — directory-level operations already handle all files.

Design Decisions

1. Save when architecture is None: Don't touch the file on disk — avoids surprising deletion.
2. Both save paths handle architecture: save() and _save_internal() both write architecture.md when present.
3. Same atomic write pattern: Uses _atomic_write helper, same as other artifacts.
4. BootstrapSpec gets set_architecture: For API consistency.
5. create_spec does NOT gain a parameter: Architecture defaults to None on Spec, which is sufficient.
6. No new public exports: Spec.architecture field is the only new API surface.
7. UTF-8 encoding: Same pattern as all other file operations.

Source

Source: #1