fix: add template reference artifacts for contract validation

Author: zh1peng

ChangLog.md

@@ -1,5 +1,20 @@
 # psyflow change log
 
+## 0.1.18 (2026-03-02)
+
+### Summary
+- Fixed CI contract validation failure on the cookiecutter template by adding required reference artifacts under:
+  - `psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/references/`
+    - `references.yaml`
+    - `references.md`
+    - `parameter_mapping.md`
+    - `stimulus_mapping.md`
+    - `task_logic_audit.md`
+- All added template files follow the `reference_artifacts` contract headings/table-column requirements and avoid forbidden unresolved markers.
+
+### Validation
+- `python -m psyflow.validate 'psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}'` now passes with `FAIL=0`.
+
 ## 0.1.17 (2026-03-02)
 
 ### Summary

psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/references/parameter_mapping.md

@@ -0,0 +1,7 @@
+# Parameter Mapping
+
+## Mapping Table
+
+| Parameter ID | Config Path | Implemented Value | Source Paper ID | Evidence (quote/figure/table) | Decision Type | Notes |
+|---|---|---|---|---|---|---|
+| `cue_duration` | `timing.cue_duration` | `0.5` | `template_paper_001` | `Example table entry` | `inferred` | Replace with task-specific citation mapping. |

psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/references/references.md

@@ -0,0 +1,9 @@
+# References
+
+This template file should be replaced with task-specific literature before release.
+
+## Selected Papers
+
+| ID | Year | Citations | Journal | High Impact | Open Access | Title |
+|---|---:|---:|---|---|---|---|
+| template_paper_001 | 2020 | 100 | Template Journal | no | yes | Template Reference Paper |

psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/references/references.yaml

@@ -0,0 +1,16 @@
+task_id: "{{cookiecutter.project_name}}"
+generated_at: "2026-03-02T00:00:00Z"
+selection_policy: template_seed
+citation_threshold: 100
+papers:
+  - id: template_paper_001
+    title: "Template Reference Paper"
+    year: 2020
+    journal: "Template Journal"
+    doi_or_url: "https://example.org/template-paper"
+    citation_count: 100
+    open_access: true
+    is_high_impact: false
+    used_for:
+      - task_workflow
+      - timing_parameters

psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/references/stimulus_mapping.md

@@ -0,0 +1,9 @@
+# Stimulus Mapping
+
+## Mapping Table
+
+| Condition | Stage/Phase | Stimulus IDs | Participant-Facing Content | Source Paper ID | Evidence (quote/figure/table) | Implementation Mode | Asset References | Notes |
+|---|---|---|---|---|---|---|---|---|
+| `win` | `cue` | `win_cue` | `WIN` | `template_paper_001` | `Example table entry` | `psychopy_builtin` | `n/a` | Replace with task-specific mapping. |
+| `lose` | `cue` | `lose_cue` | `LOSE` | `template_paper_001` | `Example table entry` | `psychopy_builtin` | `n/a` | Replace with task-specific mapping. |
+| `neutral` | `cue` | `neutral_cue` | `NEUTRAL` | `template_paper_001` | `Example table entry` | `psychopy_builtin` | `n/a` | Replace with task-specific mapping. |

psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/references/task_logic_audit.md

@@ -0,0 +1,33 @@
+# Task Logic Audit
+
+## 1. Paradigm Intent
+
+- Template placeholder. Replace with task-specific paradigm intent.
+
+## 2. Block/Trial Workflow
+
+- Template placeholder. Replace with task-specific state machine and timing.
+
+## 3. Condition Semantics
+
+- Template placeholder. Replace with task-specific condition semantics.
+
+## 4. Response and Scoring Rules
+
+- Template placeholder. Replace with task-specific response and scoring rules.
+
+## 5. Stimulus Layout Plan
+
+- Template placeholder. Replace with task-specific layout plan.
+
+## 6. Trigger Plan
+
+- Template placeholder. Replace with task-specific trigger plan.
+
+## 7. Architecture Decisions (Auditability)
+
+- Template placeholder. Replace with task-specific architecture decisions.
+
+## 8. Inference Log
+
+- Template placeholder. Replace with task-specific inference entries.