chore: make template/validator phase checks task-generic and CI-clean

Author: zh1peng

ChangLog.md

@@ -1,5 +1,19 @@
 # psyflow change log
 
+## 0.1.13 (2026-02-18)
+
+### Summary
+- Updated responder context contract/validator to support truly generic, task-specific phase labels via phase-token checks instead of fixed phase values.
+- Extended template compliance so CI validation passes on the cookiecutter task scaffold:
+  - README now includes required section heading `## 4. Methods (for academic publication)` and `Language` metadata row.
+  - Template `.gitignore` now includes recommended housekeeping ignores (`.pytest_cache`, `.mypy_cache`, virtualenv dirs).
+  - Template `CHANGELOG.md` now includes recommended `Changed` and `Fixed` sections.
+  - Template run-trial phase labels updated to generic task-ready names (`pre_response_fixation`, `response_window`).
+  - Added template `outputs/.gitkeep` to satisfy recommended path checks.
+
+### Validation
+- `python -m psyflow.validate 'psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}'` now passes with `FAIL=0`.
+
 ## 0.1.12 (2026-02-18)
 
 ### Summary

psyflow/contracts/v0.1.0/responder_context.yaml

@@ -14,15 +14,17 @@ required_context_fields_any:
   - phase=
   - deadline_s=
   - valid_keys=
-required_context_phase_values_any:
+required_context_phase_tokens_any:
   - choice
   - response
   - decision
   - offer
   - probe
   - selection
-  - anticipation
-  - target
+  - signal
+  - reveal
+  - playback
+  - rest
 recommended_context_fields_any:
   - condition_id=
   - block_id=

psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/.gitignore

@@ -4,3 +4,7 @@
 __pycache__/
 *.pyc
 src/__pycache__/
+.pytest_cache/
+.mypy_cache/
+.venv/
+venv/

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

@@ -10,3 +10,8 @@ All notable development changes for `{{cookiecutter.project_name}}` are document
 - Base configs under `config/` and trial logic under `src/`.
 - Contract adoption metadata in `taskbeacon.yaml` (`contracts.psyflow_taps: v0.1.0`).
 
+### Changed
+- None yet.
+
+### Fixed
+- None yet.

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

@@ -11,6 +11,7 @@
 | PsyFlow Version      |0.1.0                     |
 | PsychoPy Version     |2025.1.1                  |
 | Modality     |Behavior/EEG                  |
+| Language | Chinese |
 
 
 ## 1. Task Overview
@@ -51,7 +52,7 @@ The Monetary Incentive Delay (MID) Task is designed to assess reward processing
 | Feature             | Description                                                                 |
 |---------------------|-----------------------------------------------------------------------------|
 | Adaptive Duration   | Target duration adjusts between 0.04 and 0.37 seconds                       |
-| Step Size           | ±0.03 seconds                                                               |
+| Step Size           | ±0.03 seconds                                                               |
 | Accuracy Target     | 66% accuracy threshold                                                      |
 | Condition Specific  | Tracks performance separately by condition (win/lose/neutral)               |
 | Logging             | Performance logs are printed to PsychoPy console                            |
@@ -62,9 +63,9 @@ The Monetary Incentive Delay (MID) Task is designed to assess reward processing
 
 | Field       | Meaning                    |
 |-------------|----------------------------|
-| subject_id  | Unique participant number (101�99, 3 digits) |
+| subject_id  | Unique participant number (101�99, 3 digits) |
 | subname     | Participant name (pinyin)  |
-| age         | Participant age (5�0)     |
+| age         | Participant age (5�0)     |
 | gender      | Participant gender (Male/Female) |
 
 ### b. Window Settings
@@ -90,12 +91,12 @@ The Monetary Incentive Delay (MID) Task is designed to assess reward processing
 | win_target               | circle    | Black circle target                                   |
 | lose_target              | rect      | Black square target                                   |
 | neut_target              | triangle  | Black triangle target                                 |
-| win_hit_feedback         | textbox   | “击�+10 分�(black text, SimHei)                    |
-| win_miss_feedback        | textbox   | “未击中 +0 分�                                      |
-| lose_hit_feedback        | textbox   | “击�-0 分�                                        |
-| lose_miss_feedback       | textbox   | “未击中 -10 分�                                     |
-| neut_hit_feedback        | textbox   | “击�+0 分�                                        |
-| neut_miss_feedback       | textbox   | “未击中 -0 分�                                      |
+| win_hit_feedback         | textbox   | “击�+10 分�(black text, SimHei)                    |
+| win_miss_feedback        | textbox   | “未击中 +0 分�                                      |
+| lose_hit_feedback        | textbox   | “击�-0 分�                                        |
+| lose_miss_feedback       | textbox   | “未击中 -10 分�                                     |
+| neut_hit_feedback        | textbox   | “击�+0 分�                                        |
+| neut_miss_feedback       | textbox   | “未击中 -0 分�                                      |
 | instruction_text         | textbox   | Multi-line Chinese instructions (includes scoring rules) |
 | block_break              | text      | Inter-block message showing block, accuracy, and score |
 | good_bye                 | text      | End screen showing final score                        |
@@ -105,9 +106,9 @@ The Monetary Incentive Delay (MID) Task is designed to assess reward processing
 | Phase                 | Duration (s)        |
 |------------------------|--------------------|
 | cue                   | 0.3                |
-| anticipation          | random 1.0�.2     |
-| target                | adaptive (0.04�.37)|
-| prefeedback fixation  | random 0.6�.8     |
+| anticipation          | random 1.0�.2     |
+| target                | adaptive (0.04�.37)|
+| prefeedback fixation  | random 0.6�.8     |
 | feedback              | 1.0                |
 
 ### e. Triggers
@@ -152,13 +153,13 @@ The Monetary Incentive Delay (MID) Task is designed to assess reward processing
 | target_accuracy    | 0.66     |
 | condition_specific | true     |
 
-## 4. Methods
+## 4. Methods (for academic publication)
 
-Participants performed a computerized Monetary Incentive Delay (MID) task to assess motivational processing under different reward contingencies. The task consisted of **3 blocks**, each comprising **60 trials**, totaling **180 trials**. Each trial began with a cue, a colored shape (circle, square, or triangle), signaling whether the trial was a reward, punishment, or neutral condition. Following a variable anticipation phase (1.0�.2 s), a black target appeared briefly. Participants were instructed to press the spacebar as quickly as possible upon target onset.
+Participants performed a computerized Monetary Incentive Delay (MID) task to assess motivational processing under different reward contingencies. The task consisted of **3 blocks**, each comprising **60 trials**, totaling **180 trials**. Each trial began with a cue, a colored shape (circle, square, or triangle), signaling whether the trial was a reward, punishment, or neutral condition. Following a variable anticipation phase (1.0�.2 s), a black target appeared briefly. Participants were instructed to press the spacebar as quickly as possible upon target onset.
 
-The target's presentation duration was controlled by an adaptive algorithm that updated the duration after each trial based on performance. Initial target duration was set to 0.2 s and was adjusted between 0.04 and 0.37 s using ±0.03 s increments to stabilize performance at a target accuracy of 66%, tracked separately by condition.
+The target's presentation duration was controlled by an adaptive algorithm that updated the duration after each trial based on performance. Initial target duration was set to 0.2 s and was adjusted between 0.04 and 0.37 s using ±0.03 s increments to stabilize performance at a target accuracy of 66%, tracked separately by condition.
 
-Feedback followed the target phase, based on whether participants responded within the target duration. “击中�(“hit� and “未击中�(“miss� messages were shown with point gain/loss specific to the cue type. After each block, a break screen summarized the participant's accuracy and cumulative score. The task began with audio-visual instructions and ended with a final message displaying total score. 
+Feedback followed the target phase, based on whether participants responded within the target duration. “击中�(“hit� and “未击中�(“miss� messages were shown with point gain/loss specific to the cue type. After each block, a break screen summarized the participant's accuracy and cumulative score. The task began with audio-visual instructions and ended with a final message displaying total score. 
 
 ## 5. References
 The task is originally developed by Knutson 2000:

psyflow/templates/cookiecutter-psyflow/{{cookiecutter.project_name}}/src/run_trial.py

@@ -49,17 +49,17 @@ def run_trial(
         onset_trigger=settings.triggers.get(f"{condition}_cue_onset"),
     ).to_dict(trial_data)
 
-    # --- Anticipation ---
+    # phase: pre_response_fixation
     anti = make_unit(unit_label="anticipation").add_stim(stim_bank.get("fixation"))
     set_trial_context(
         anti,
         trial_id=trial_id,
-        phase="anticipation",
+        phase="pre_response_fixation",
         deadline_s=_deadline_s(settings.anticipation_duration),
         valid_keys=list(settings.key_list),
         block_id=block_id,
         condition_id=str(condition),
-        task_factors={"condition": str(condition), "stage": "anticipation", "block_idx": block_idx},
+        task_factors={"condition": str(condition), "stage": "pre_response_fixation", "block_idx": block_idx},
         stim_id="fixation",
     )
     anti.capture_response(
@@ -73,20 +73,20 @@ def run_trial(
     anti.set_state(early_response=early_response)
     anti.to_dict(trial_data)
 
-    # --- Target ---
+    # phase: response_window
     duration = controller.get_duration(condition)
     target = make_unit(unit_label="target").add_stim(stim_bank.get(f"{condition}_target"))
     set_trial_context(
         target,
         trial_id=trial_id,
-        phase="target",
+        phase="response_window",
         deadline_s=_deadline_s(duration),
         valid_keys=list(settings.key_list),
         block_id=block_id,
         condition_id=str(condition),
         task_factors={
             "condition": str(condition),
-            "stage": "target",
+            "stage": "response_window",
             "block_idx": block_idx,
             "target_duration_s": float(duration),
         },

psyflow/validate.py

@@ -906,6 +906,22 @@ def _check_responder_context(task_dir: Path, cfg: dict[str, Any]) -> ContractRes
             f"expected one of {sorted(required_phase_any)}, got {sorted(phase_values) or 'none'}"
         )
 
+    required_phase_tokens_any = [
+        str(x or "").strip().lower()
+        for x in list(cfg.get("required_context_phase_tokens_any") or [])
+        if str(x or "").strip()
+    ]
+    if required_phase_tokens_any:
+        has_required_token = any(
+            any(tok in phase for tok in required_phase_tokens_any)
+            for phase in phase_values
+        )
+        if not has_required_token:
+            fails.append(
+                "Missing required context phase token (any): "
+                f"expected one of {sorted(required_phase_tokens_any)}, got {sorted(phase_values) or 'none'}"
+            )
+
     forbidden_phase = {
         str(x or "").strip().lower()
         for x in list(cfg.get("forbidden_context_phase_values") or [])
@@ -945,6 +961,22 @@ def _check_responder_context(task_dir: Path, cfg: dict[str, Any]) -> ContractRes
             f"{sorted(recommended_phase_any)}; got {sorted(phase_values) or 'none'}"
         )
 
+    recommended_phase_tokens_any = [
+        str(x or "").strip().lower()
+        for x in list(cfg.get("recommended_context_phase_tokens_any") or [])
+        if str(x or "").strip()
+    ]
+    if recommended_phase_tokens_any:
+        has_recommended_token = any(
+            any(tok in phase for tok in recommended_phase_tokens_any)
+            for phase in phase_values
+        )
+        if not has_recommended_token:
+            warns.append(
+                "No recommended phase tokens found (any): "
+                f"{sorted(recommended_phase_tokens_any)}; got {sorted(phase_values) or 'none'}"
+            )
+
     required_stage_any = [str(x).strip().lower() for x in list(cfg.get("required_stage_tokens_any") or []) if str(x).strip()]
     if required_stage_any and not any(tok in low for tok in required_stage_any):
         fails.append(f"Missing required trial stage token (any): {required_stage_any}")