584 lines
22 KiB
YAML
584 lines
22 KiB
YAML
schema-version: 1
|
|
repository-snapshot-hash: sha256:d65d7446cad11d46dabd2080c8393059f36fab426f4d62f18183b2c144c3de29
|
|
project-name: Content Harness
|
|
languages: [Python, YAML, JSON, Markdown]
|
|
facts:
|
|
- id: F-IDENTITY
|
|
category: identity
|
|
key: project-purpose
|
|
value:
|
|
name: Content Harness
|
|
purpose: provider-neutral technical-document planning, exact technical visualization, organic image generation, and accepted-asset publication
|
|
assertion-type: derived
|
|
confidence: high
|
|
evidence:
|
|
- path: README.md
|
|
line-start: 1
|
|
line-end: 14
|
|
source-kind: project-documentation
|
|
- path: packages/workflow-runtime/handlers.yaml
|
|
line-start: 1
|
|
line-end: 8
|
|
source-kind: handler-registry
|
|
|
|
- id: F-REPOSITORY-LAYERS
|
|
category: architecture
|
|
key: canonical-layer-ownership
|
|
value:
|
|
.agents-and-.codex: thin provider discovery adapters
|
|
harnesses: capability policy and implementation canon
|
|
packages: contracts and runtime canon
|
|
integrations: publication target adapters
|
|
tests: repository-wide validation and golden artifacts
|
|
examples: versioned executable examples
|
|
benchmarks: evaluation suites and failure corpora
|
|
runs: ignored local workflow data
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: ARCHITECTURE.md
|
|
line-start: 3
|
|
line-end: 28
|
|
source-kind: architecture-documentation
|
|
- path: .codex/agents/natural-prose-reviewer.toml
|
|
line-start: 1
|
|
line-end: 9
|
|
source-kind: thin-provider-adapter
|
|
|
|
- id: F-SIBLING-HARNESSES
|
|
category: architecture
|
|
key: sibling-harness-runtime-boundary
|
|
value:
|
|
handlers: [document-writing, technical-visualization, image-generation]
|
|
rule: sibling harnesses return plans or results and do not call one another
|
|
runtime-responsibility: validation, routing, DAG execution, retries, result transfer, integration, and events
|
|
execution-boundary: workflow-runtime -> handlers.yaml -> HarnessHandler -> immutable JobResult
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: ARCHITECTURE.md
|
|
line-start: 30
|
|
line-end: 53
|
|
source-kind: architecture-documentation
|
|
- path: packages/workflow-runtime/handlers.yaml
|
|
line-start: 1
|
|
line-end: 8
|
|
source-kind: handler-registry
|
|
- path: tests/conformance/test_repository_layout.py
|
|
line-start: 43
|
|
line-end: 51
|
|
source-kind: conformance-test
|
|
|
|
- id: F-CAPABILITY-DOCUMENT
|
|
category: capability
|
|
key: document-writing
|
|
value:
|
|
owns: [narrative, audience, evidence linkage, visual-opportunity detection, figure context]
|
|
operations: [document-writing.intake, document-writing.analyze, document-writing.plan, document-writing.revise, document-writing.draft]
|
|
outputs: [content-job-request, publication-draft, content-manifest, narrative-plan, narrative-analysis, reviews, visual-requests]
|
|
boundary: never edits the source document in place and does not select renderers or generate imagery
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: harnesses/document-writing/README.md
|
|
line-start: 3
|
|
line-end: 29
|
|
source-kind: capability-documentation
|
|
- path: harnesses/document-writing/capability.yaml
|
|
line-start: 1
|
|
line-end: 22
|
|
source-kind: capability-declaration
|
|
- path: harnesses/document-writing/handler.py
|
|
line-start: 253
|
|
line-end: 345
|
|
symbol: DocumentWritingHandler
|
|
source-kind: implementation
|
|
|
|
- id: F-CAPABILITY-TECHNICAL
|
|
category: capability
|
|
key: technical-visualization
|
|
value:
|
|
owns: [evidence-grounded semantic models, visual grammar, deterministic rendering, target-specific renditions]
|
|
executable-visual-types: [dependency-graph, runtime-sequence]
|
|
renderer: d2
|
|
output-profiles: [document, presentation]
|
|
acceptance-boundary: separate exact-input technical-semantic and technical-visual expert reviews are required
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: harnesses/technical-visualization/README.md
|
|
line-start: 3
|
|
line-end: 23
|
|
source-kind: capability-documentation
|
|
- path: harnesses/technical-visualization/capability.yaml
|
|
line-start: 1
|
|
line-end: 23
|
|
source-kind: capability-declaration
|
|
- path: harnesses/technical-visualization/handler.py
|
|
line-start: 904
|
|
line-end: 962
|
|
symbol: TechnicalVisualizationHandler
|
|
source-kind: implementation
|
|
|
|
- id: F-CAPABILITY-IMAGE
|
|
category: capability
|
|
key: image-generation
|
|
value:
|
|
owns: [organic raster imagery, photography, illustration, bounded candidate search, local repair]
|
|
operations: [image-generation.generate, image-generation.generate-component]
|
|
production-model: three hashed candidates, pairwise comparison, explicit selection, and at most one bounded repair
|
|
excluded: [exact architecture relations, charts, state transitions, long exact text, evidence-derived technical geometry]
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: harnesses/image-generation/README.md
|
|
line-start: 3
|
|
line-end: 26
|
|
source-kind: capability-documentation
|
|
- path: harnesses/image-generation/capability.yaml
|
|
line-start: 1
|
|
line-end: 24
|
|
source-kind: capability-declaration
|
|
- path: harnesses/image-generation/handler.py
|
|
line-start: 246
|
|
line-end: 301
|
|
symbol: ImageGenerationHandler
|
|
source-kind: implementation
|
|
|
|
- id: F-ROUTING
|
|
category: architecture
|
|
key: visual-routing-policy
|
|
value:
|
|
technical-only: technical-visualization
|
|
image-only: image-generation
|
|
both: hybrid DAG
|
|
neither: BLOCKED_UNRESOLVED
|
|
explicit-conflict: ROUTING_CONFLICT
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: ARCHITECTURE.md
|
|
line-start: 100
|
|
line-end: 118
|
|
source-kind: architecture-documentation
|
|
- path: packages/workflow-runtime/policies/routing.yaml
|
|
line-start: 27
|
|
line-end: 31
|
|
source-kind: runtime-policy
|
|
|
|
- id: F-CONTRACT-CHAIN
|
|
category: architecture
|
|
key: content-to-publication-contract-chain
|
|
value:
|
|
- ContentJobRequest
|
|
- Content Manifest
|
|
- Narrative Plan
|
|
- Visual Request
|
|
- ArtifactSet
|
|
- frozen publication projection
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: ARCHITECTURE.md
|
|
line-start: 69
|
|
line-end: 98
|
|
source-kind: architecture-documentation
|
|
|
|
- id: F-INTEGRATIONS
|
|
category: capability
|
|
key: publication-adapters
|
|
value:
|
|
targets: [Markdown, Slides, HTML]
|
|
input: one runtime-selected frozen publication projection
|
|
boundary: adapters do not choose content, route, renderer, provider, or visual grammar
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: integrations/README.md
|
|
line-start: 1
|
|
line-end: 11
|
|
source-kind: integration-documentation
|
|
|
|
- id: F-EXAMPLE-CHAIN
|
|
category: examples
|
|
key: checked-in-clean-architecture-chain
|
|
value:
|
|
root: examples/clean-architecture
|
|
contracts: [content-job-request.yaml, content-manifest.yaml, narrative-plan.yaml, reference-registry.yaml, visual-request.yaml, workflow-request.content-job.yaml, workflow-request.visual.yaml, artifact/attempt-01/artifact-set.yaml]
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: tests/conformance/test_repository_layout.py
|
|
line-start: 480
|
|
line-end: 496
|
|
source-kind: conformance-test
|
|
- path: examples/clean-architecture/content-job-request.yaml
|
|
source-kind: versioned-example
|
|
|
|
- id: F-VERSIONED-VISUALS
|
|
category: artifacts
|
|
key: checked-in-technical-visual-contract-fixture
|
|
value:
|
|
artifact-status: accepted
|
|
integration-status: ready
|
|
scope: contract-only fixture rather than renderer-backed golden comparison
|
|
renditions:
|
|
- {path: examples/clean-architecture/artifact/attempt-01/dependency-directions.svg, target: document, dimensions: 820x460}
|
|
- {path: examples/clean-architecture/artifact/attempt-01/dependency-directions.presentation.svg, target: presentation, dimensions: 1600x900}
|
|
- {path: examples/clean-architecture/artifact/attempt-01/dependency-directions.presentation-step-1.svg, target: presentation-reveal-step, dimensions: 1600x900}
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: examples/clean-architecture/artifact/attempt-01/artifact-set.yaml
|
|
line-start: 2
|
|
line-end: 78
|
|
source-kind: artifact-manifest
|
|
- path: tests/golden/dependency-directions/README.md
|
|
line-start: 1
|
|
line-end: 7
|
|
source-kind: golden-fixture-documentation
|
|
|
|
- id: F-RUN-WORKSPACE
|
|
category: runtime
|
|
key: fresh-run-allocation
|
|
value:
|
|
path: runs/<purpose>/run-<YYYYMMDDTHHMMSSZ>-NNN/
|
|
semantics: each valid fresh intake or execution creates a new immutable workspace; matching request or workflow ids do not authorize reuse
|
|
optional-output: <run-root>/output/
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: runs/README.md
|
|
line-start: 1
|
|
line-end: 32
|
|
source-kind: runtime-workspace-policy
|
|
- path: packages/workflow-runtime/README.md
|
|
line-start: 86
|
|
line-end: 98
|
|
source-kind: runtime-documentation
|
|
|
|
- id: F-PORTABLE-OUTPUT
|
|
category: artifacts
|
|
key: reviewed-output-bundle
|
|
value:
|
|
location: <run-root>/output/
|
|
entrypoint: index.html
|
|
manifest: manifest.yaml
|
|
condition: reviewed publication draft or accepted integration-ready ArtifactSet
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: packages/workflow-runtime/README.md
|
|
line-start: 216
|
|
line-end: 221
|
|
source-kind: runtime-documentation
|
|
- path: tests/runtime/test_output_bundle.py
|
|
line-start: 176
|
|
line-end: 204
|
|
symbol: test_bundle_is_portable_and_manifest_hashes_match
|
|
source-kind: runtime-test
|
|
|
|
- id: F-LOCAL-CROSS-HARNESS-OUTPUT
|
|
category: artifacts
|
|
key: local-cross-harness-test-output
|
|
value:
|
|
root: runs/p6-all-harness-quality-executable-clean-architecture-20260717/output
|
|
generated-document: [README.md, final-document.md, index.html, preview.png]
|
|
technical-visualization: [assets/dependency-directions.document.svg, assets/dependency-directions.presentation.svg]
|
|
image-generation: [assets/editorial-workbench.document.png, assets/editorial-workbench.presentation.png, assets/image-candidates.png]
|
|
validation: validation-summary.yaml
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: runs/p6-all-harness-quality-executable-clean-architecture-20260717/output/manifest.yaml
|
|
line-start: 1
|
|
line-end: 35
|
|
source-kind: local-generated-output-manifest
|
|
- path: runs/p6-all-harness-quality-executable-clean-architecture-20260717/output/README.md
|
|
line-start: 1
|
|
line-end: 12
|
|
source-kind: local-generated-document
|
|
- path: runs/p6-all-harness-quality-executable-clean-architecture-20260717/output/preview.png
|
|
source-kind: local-generated-preview
|
|
|
|
- id: F-LOCAL-DOCUMENT-VISUALIZATION
|
|
category: artifacts
|
|
key: local-document-visualization-test-output
|
|
value:
|
|
root: runs/docvis-20260716-executable-clean-architecture-part1
|
|
document-output: document/part1-integrated.html
|
|
figures: [fig-invisible-shortcut, fig-enforcement-gradient]
|
|
formats: [desktop-SVG, mobile-SVG, PNG-fallback]
|
|
previews: [integrated-previews/part1-desktop.png, integrated-previews/part1-mobile-v2.png]
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: runs/docvis-20260716-executable-clean-architecture-part1/delivery/delivery-manifest.yaml
|
|
line-start: 1
|
|
line-end: 24
|
|
source-kind: local-delivery-manifest
|
|
- path: runs/docvis-20260716-executable-clean-architecture-part1/figures/fig-enforcement-gradient/asset-manifest.yaml
|
|
line-start: 1
|
|
line-end: 30
|
|
source-kind: local-figure-manifest
|
|
|
|
- id: F-LOCAL-IMAGE-OUTPUT
|
|
category: artifacts
|
|
key: local-best-of-three-image-test-output
|
|
value:
|
|
root: runs/img-20260716-japanese-animation-test
|
|
generation-candidates: 3
|
|
selected-attempt: 2
|
|
selected-output: outputs/final-selected.png
|
|
selection-label: BEST_OF_N_PASS
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: runs/img-20260716-japanese-animation-test/selection.json
|
|
line-start: 1
|
|
line-end: 64
|
|
source-kind: local-selection-record
|
|
- path: runs/img-20260716-japanese-animation-test/outputs/final-selected.png
|
|
source-kind: local-generated-image
|
|
|
|
- id: F-RUNS-NONCANONICAL
|
|
category: limitation
|
|
key: local-run-durability
|
|
value: runs/** is ignored local operational data, not a cache or source of truth; reusable examples belong under examples, regression oracles under tests/golden, and evaluation corpora under benchmarks
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: .gitignore
|
|
line-start: 5
|
|
line-end: 7
|
|
source-kind: ignore-policy
|
|
- path: runs/README.md
|
|
line-start: 1
|
|
line-end: 7
|
|
source-kind: runtime-workspace-policy
|
|
- path: docs/README.md
|
|
line-start: 23
|
|
line-end: 35
|
|
source-kind: documentation-policy
|
|
|
|
- id: F-PREREQUISITES
|
|
category: prerequisites
|
|
key: runtime-tools
|
|
value:
|
|
language: Python 3
|
|
python-packages: [PyYAML, jsonschema, Pillow]
|
|
feature-specific-tools:
|
|
technical-rendering: D2
|
|
SVG-preview: Chrome or Chromium
|
|
version-pins: not declared
|
|
assertion-type: derived
|
|
confidence: high
|
|
evidence:
|
|
- path: README.md
|
|
line-start: 151
|
|
line-end: 153
|
|
source-kind: project-documentation
|
|
- path: packages/schema-support/src/contract_support.py
|
|
line-start: 13
|
|
line-end: 14
|
|
source-kind: dependency-import
|
|
- path: packages/export-validator/src/validate_export.py
|
|
line-start: 1
|
|
line-end: 14
|
|
source-kind: dependency-import
|
|
- path: harnesses/technical-visualization/renderers/d2/renderer.py
|
|
line-start: 206
|
|
line-end: 213
|
|
source-kind: renderer-implementation
|
|
- path: harnesses/image-generation/scripts/render_svg_preview.py
|
|
line-start: 18
|
|
line-end: 31
|
|
source-kind: preview-implementation
|
|
|
|
- id: F-NO-PACKAGE-MANIFEST
|
|
category: limitation
|
|
key: dependency-installation-metadata
|
|
value: no pyproject.toml, requirements.txt, setup.py, setup.cfg, Pipfile, poetry.lock, or uv.lock is present; dependency versions and one canonical installation command cannot be evidenced
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: .
|
|
source-kind: repository-file-scan
|
|
|
|
- id: F-TEST-INVENTORY
|
|
category: tests
|
|
key: unittest-suite
|
|
value:
|
|
framework: unittest
|
|
observed-test-methods: 300
|
|
groups: [conformance, contracts, failure_injection, harnesses, integrations, runtime]
|
|
declared-latest-full-run: 300 tests passed in repository refactoring review
|
|
current-readme-run-check: repository-layout module passed 18 tests
|
|
assertion-type: derived
|
|
confidence: high
|
|
evidence:
|
|
- path: tests
|
|
source-kind: test-directory-scan
|
|
- path: docs/refactoring-review.md
|
|
line-start: 76
|
|
line-end: 91
|
|
source-kind: declared-verification-report
|
|
- path: tests/conformance/test_repository_layout.py
|
|
source-kind: executed-test-module
|
|
|
|
- id: F-EXECUTED-QUICK-CHECKS
|
|
category: verification
|
|
key: readme-authoring-session-executions
|
|
value:
|
|
date: 2026-07-18
|
|
content-job-request-validation: {exit-code: 0}
|
|
content-manifest-validation: {exit-code: 0, output: VALID}
|
|
front-door-content-plan: {exit-code: 0, primary-capability: document-writing}
|
|
artifact-set-validation: {exit-code: 0, output: VALID}
|
|
repository-layout-tests: {tests: 18, result: PASS}
|
|
assertion-type: executed
|
|
confidence: high
|
|
evidence:
|
|
- path: packages/content-job-contract/src/validate_content_job.py
|
|
source-kind: executed-entrypoint
|
|
- path: packages/content-contract/src/validate_content.py
|
|
source-kind: executed-entrypoint
|
|
- path: packages/workflow-runtime/src/content_runtime.py
|
|
source-kind: executed-entrypoint
|
|
- path: packages/artifact-contract/src/validate_artifact_set.py
|
|
source-kind: executed-entrypoint
|
|
- path: tests/conformance/test_repository_layout.py
|
|
source-kind: executed-test-module
|
|
|
|
- id: F-E2E-INPUTS
|
|
category: prerequisites
|
|
key: end-to-end-external-inputs
|
|
value:
|
|
dependency-directions: [external Java/Gradle evidence repository, completed technical review file, completed narrative review file]
|
|
part1-redraw: [external source document, completed expert review file]
|
|
all-harness-quality: [external Java/Gradle evidence repository, stage-specific review files]
|
|
assertion-type: declared
|
|
confidence: high
|
|
evidence:
|
|
- path: tests/end-to-end/README.md
|
|
line-start: 68
|
|
line-end: 139
|
|
source-kind: end-to-end-documentation
|
|
|
|
- id: F-HYBRID-PENDING
|
|
category: limitation
|
|
key: d2-svg-layer-compositor-status
|
|
value:
|
|
automated-evidence: PASS
|
|
human-qualification: PENDING
|
|
production-status: qualification candidate, not qualified renderer
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: packages/workflow-runtime/policies/qualification.yaml
|
|
line-start: 29
|
|
line-end: 33
|
|
source-kind: qualification-policy
|
|
- path: benchmarks/hybrid-composition/results/d2-svg-layer-compositor-qualification.yaml
|
|
line-start: 1
|
|
line-end: 9
|
|
source-kind: automated-qualification-result
|
|
- path: benchmarks/hybrid-composition/results/d2-svg-layer-compositor-qualification.yaml
|
|
line-start: 65
|
|
line-end: 72
|
|
source-kind: human-qualification-result
|
|
|
|
- id: F-BENCHMARK-MATURITY
|
|
category: limitation
|
|
key: qualification-corpus-status
|
|
value:
|
|
document-writing: corpus-defined-results-pending
|
|
image-generation: corpus-defined-results-pending
|
|
technical-visualization: dependency-directions comparison has unexecuted conditions and pending human preference
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: benchmarks/document-writing/suite.yaml
|
|
line-start: 1
|
|
line-end: 32
|
|
source-kind: benchmark-suite
|
|
- path: benchmarks/image-quality/suite.yaml
|
|
line-start: 1
|
|
line-end: 41
|
|
source-kind: benchmark-suite
|
|
- path: benchmarks/technical-visualization/results/dependency-directions-qualification.yaml
|
|
line-start: 1
|
|
line-end: 25
|
|
source-kind: benchmark-result
|
|
|
|
- id: F-NO-GIT-METADATA
|
|
category: limitation
|
|
key: repository-snapshot
|
|
value: the supplied directory has an empty .git directory, so no commit SHA or clean/dirty Git state can be established; the README run uses a repository content hash instead
|
|
assertion-type: observed
|
|
confidence: high
|
|
evidence:
|
|
- path: .
|
|
source-kind: filesystem-and-git-probe
|
|
|
|
commands:
|
|
- id: CMD-001
|
|
command: python3 -m packages.content_job_contract.validate_content_job examples/clean-architecture/content-job-request.yaml --repo-root .
|
|
cwd: .
|
|
source: {path: packages/content-job-contract/README.md, line-start: 21, line-end: 25}
|
|
verification:
|
|
status: executed
|
|
method: executed from the repository root on 2026-07-18; exit code 0
|
|
level: isolated-execution
|
|
limitations: [validates the checked-in ContentJobRequest only]
|
|
|
|
- id: CMD-002
|
|
command: python3 -m packages.workflow_runtime.content_runtime front-door --workflow-request examples/clean-architecture/workflow-request.content-job.yaml --repo-root .
|
|
cwd: .
|
|
source: {path: README.md, line-start: 93, line-end: 96}
|
|
verification:
|
|
status: executed
|
|
method: executed from the repository root on 2026-07-18; exit code 0 and a document-writing plan was emitted
|
|
level: isolated-execution
|
|
limitations: [plans the checked-in request but does not execute production providers]
|
|
|
|
- id: CMD-003
|
|
command: python3 -m packages.content_contract.validate_content examples/clean-architecture/content-manifest.yaml --repo-root .
|
|
cwd: .
|
|
source: {path: README.md, line-start: 99, line-end: 102}
|
|
verification:
|
|
status: executed
|
|
method: executed from the repository root on 2026-07-18; exit code 0 and output VALID
|
|
level: isolated-execution
|
|
limitations: [validates the checked-in Content Manifest only]
|
|
|
|
- id: CMD-004
|
|
command: python3 -m packages.artifact_contract.validate_artifact_set examples/clean-architecture/artifact/attempt-01/artifact-set.yaml --request examples/clean-architecture/visual-request.yaml
|
|
cwd: .
|
|
source: {path: README.md, line-start: 114, line-end: 116}
|
|
verification:
|
|
status: executed
|
|
method: executed from the repository root on 2026-07-18; exit code 0 and output VALID
|
|
level: isolated-execution
|
|
limitations: [validates the checked-in contract fixture rather than a fresh renderer run]
|
|
|
|
- id: CMD-005
|
|
command: python3 -m unittest tests.conformance.test_repository_layout
|
|
cwd: .
|
|
source: {path: tests/conformance/test_repository_layout.py}
|
|
verification:
|
|
status: executed
|
|
method: executed from the repository root on 2026-07-18; 18 tests passed
|
|
level: isolated-execution
|
|
limitations: [covers repository layout only, not the full suite]
|
|
|
|
- id: CMD-006
|
|
command: python3 -m unittest discover -s tests -p 'test_*.py'
|
|
cwd: .
|
|
source: {path: README.md, line-start: 145, line-end: 149}
|
|
verification:
|
|
status: discovered
|
|
method: located in the current root README and unittest tree
|
|
level: static
|
|
limitations: [not executed during this README rewrite; the refactoring review separately declares an earlier 300-test pass]
|