docs: journey-traceability + iconography implementation #51
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,268 @@ | ||
| # ============================================================================= | ||
| # Journey Gate — Reusable Workflow | ||
| # ============================================================================= | ||
| # Canonical source: phenotype-infra/docs/governance/ci-journey-gate.yml | ||
| # Usage: copy to .github/workflows/journey-gate.yml in the consuming repo. | ||
| # Do not modify the logic; extend via workflow_dispatch inputs for | ||
| # repo-specific paths or thresholds. | ||
| # | ||
| # Requirements: | ||
| # - phenotype-journey CLI installed in the runner PATH | ||
| # - tesseract OCR installed (brew install tesseract / apt-get install tesseract-ocr) | ||
| # - ANTHROPIC_API_KEY secret (optional — enables --live mode) | ||
| # | ||
| # Behaviour: | ||
| # - FAILS if no manifest.verified.json files are found (stub mode). | ||
| # - FAILS if any manifest fails validation against the JSON schema. | ||
| # - FAILS if any assertion is violated in --strict mode. | ||
| # - PASSES only when all manifests pass validation AND all assertions pass. | ||
| # ============================================================================= | ||
|
|
||
| name: Journey Gate | ||
|
|
||
| on: | ||
| push: | ||
| branches: [main] | ||
| pull_request: | ||
| branches: [main] | ||
|
|
||
| # Allow manual triggering from the Actions tab. | ||
| workflow_dispatch: | ||
| inputs: | ||
| manifest_path: | ||
| description: 'Glob pattern for manifests (default: "**/manifest.verified.json")' | ||
| required: false | ||
| default: '**/manifest.verified.json' | ||
| strict_mode: | ||
| description: 'Run assertions in --strict mode (fail on violations)' | ||
| required: false | ||
| default: 'true' | ||
| type: boolean | ||
| live_verification: | ||
| description: 'Use --live mode (requires ANTHROPIC_API_KEY secret)' | ||
| required: false | ||
| default: 'false' | ||
| type: boolean | ||
|
|
||
| env: | ||
| PHENOTYPE_JOURNEY_STRICT: ${{ inputs.strict_mode || 'true' }} | ||
|
|
||
| jobs: | ||
| journey-gate: | ||
| name: Journey Verification | ||
| runs-on: ubuntu-latest | ||
| timeout-minutes: 15 | ||
|
|
||
| steps: | ||
| - name: Checkout | ||
| uses: actions/checkout@v4 | ||
|
|
||
| # --------------------------------------------------------------------- | ||
| # 1. Install runtime dependencies | ||
| # --------------------------------------------------------------------- | ||
| - name: Install tesseract OCR | ||
| run: | | ||
| sudo apt-get update -qq | ||
| sudo apt-get install -y -qq tesseract-ocr \ | ||
| || { echo "WARNING: tesseract install failed — assertions will skip"; } | ||
|
|
||
| - name: Check tesseract availability | ||
| run: | | ||
| if command -v tesseract &>/dev/null; then | ||
| echo "tesseract: $(tesseract --version | head -1)" | ||
| else | ||
| echo "tesseract: NOT FOUND — OCR assertions will be skipped" | ||
| fi | ||
|
|
||
| # --------------------------------------------------------------------- | ||
| # 2. Install phenotype-journey CLI | ||
| # --------------------------------------------------------------------- | ||
| - name: Install phenotype-journey | ||
| run: | | ||
| if command -v phenotype-journey &>/dev/null; then | ||
| echo "phenotype-journey: $(phenotype-journey --version 2>/dev/null || phenotype-journey --help 2>&1 | head -1)" | ||
| else | ||
| echo "Installing phenotype-journey..." | ||
| # Install via cargo if available, else download binary | ||
| if command -v cargo &>/dev/null; then | ||
| cargo install phenotype-journey --locked \ | ||
| || { echo "ERROR: phenotype-journey install failed"; exit 1; } | ||
| else | ||
| # Download latest release binary (adjust URL as needed) | ||
| curl -fsSL https://github.com/KooshaPari/phenotype-journeys/releases/latest/download/phenotype-journey-x86_64-unknown-linux-gnu \ | ||
| -o /usr/local/bin/phenotype-journey \ | ||
| && chmod +x /usr/local/bin/phenotype-journey \ | ||
| || { echo "ERROR: phenotype-journey download failed"; exit 1; } | ||
| fi | ||
| fi | ||
|
|
||
| # --------------------------------------------------------------------- | ||
| # 3. Find all manifest.verified.json files | ||
| # --------------------------------------------------------------------- | ||
| - name: Discover manifests | ||
| id: discover | ||
| run: | | ||
| GLOB="${MANIFEST_PATH:-**/manifest.verified.json}" | ||
| echo "Glob pattern: $GLOB" | ||
|
|
||
| MANIFESTS=$(find . \ | ||
| -name "manifest.verified.json" \ | ||
| -not -path "*/node_modules/*" \ | ||
|
Comment on lines
+32
to
+110
There was a problem hiding this comment. 🟠 Architect Review — HIGH The workflow defines a Suggestion: Map the Fix in Cursor | Fix in VSCode Claude (Use Cmd/Ctrl + Click for best experience) Prompt for AI Agent 🤖This is an **Architect / Logical Review** comment left during a code review. These reviews are first-class, important findings — not optional suggestions. Do NOT dismiss this as a 'big architectural change' just because the title says architect review; most of these can be resolved with a small, localized fix once the intent is understood.
**Path:** .github/workflows/journey-gate.yml
**Line:** 32:110
**Comment:**
*HIGH: The workflow defines a `manifest_path` workflow_dispatch input but the discovery step ignores it, instead always running `find . -name "manifest.verified.json"`, so configuring a custom manifest location has no effect.
Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
If a suggested approach is provided above, use it as the authoritative instruction. If no explicit code suggestion is given, you MUST still draft and apply your own minimal, localized fix — do not punt back with 'no suggestion provided, review manually'. Keep the change as small as possible: add a guard clause, gate on a loading state, reorder an await, wrap in a conditional, etc. Do not refactor surrounding code or expand scope beyond the finding.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
Comment on lines
+32
to
+110
There was a problem hiding this comment. 🟠 Architect Review — HIGH The Suggestion: Wire the Fix in Cursor | Fix in VSCode Claude (Use Cmd/Ctrl + Click for best experience) Prompt for AI Agent 🤖This is an **Architect / Logical Review** comment left during a code review. These reviews are first-class, important findings — not optional suggestions. Do NOT dismiss this as a 'big architectural change' just because the title says architect review; most of these can be resolved with a small, localized fix once the intent is understood.
**Path:** .github/workflows/journey-gate.yml
**Line:** 32:110
**Comment:**
*HIGH: The `workflow_dispatch.inputs.manifest_path` input is declared but never used: the Discover manifests step builds `GLOB` from `MANIFEST_PATH` (which is never set) and immediately ignores it by hard-coding `find . -name "manifest.verified.json"`, so callers cannot override manifest discovery as documented.
Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
If a suggested approach is provided above, use it as the authoritative instruction. If no explicit code suggestion is given, you MUST still draft and apply your own minimal, localized fix — do not punt back with 'no suggestion provided, review manually'. Keep the change as small as possible: add a guard clause, gate on a loading state, reorder an await, wrap in a conditional, etc. Do not refactor surrounding code or expand scope beyond the finding.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix |
||
| -not -path "*/target/*" \ | ||
| -not -path "*/.git/*" \ | ||
| -not -path "*/vendor/*" \ | ||
| 2>/dev/null | sort) | ||
|
There was a problem hiding this comment. Workflow dispatch
|
||
|
|
||
| if [ -z "$MANIFESTS" ]; then | ||
| echo "MANIFEST_COUNT=0" >> $GITHUB_OUTPUT | ||
| echo "No manifest.verified.json files found." | ||
| echo "::warning::No journey manifests found. Add docs/journeys/manifests/<spec>/manifest.verified.json" | ||
| echo "" | ||
| echo "To create a stub manifest run:" | ||
| echo " phenotype-journey init <journey-name>" | ||
| echo "" | ||
| echo "Once manifests exist, remove the exit 1 below to enable the gate." | ||
| # STUB MODE: fail until manifests exist | ||
| exit 1 | ||
| fi | ||
|
|
||
| COUNT=$(echo "$MANIFESTS" | grep -c . || true) | ||
| echo "MANIFEST_COUNT=$COUNT" >> $GITHUB_OUTPUT | ||
| echo "MANIFEST_LIST<<EOF" >> $GITHUB_OUTPUT | ||
| echo "$MANIFESTS" >> $GITHUB_OUTPUT | ||
| echo "EOF" >> $GITHUB_OUTPUT | ||
|
|
||
| echo "Found $COUNT manifest(s):" | ||
| echo "$MANIFESTS" | ||
|
|
||
| # --------------------------------------------------------------------- | ||
| # 4. Validate each manifest against the JSON schema | ||
| # --------------------------------------------------------------------- | ||
| - name: Validate manifests | ||
| run: | | ||
| MANIFESTS="${{ steps.discover.outputs.MANIFEST_LIST }}" | ||
|
|
||
| for manifest in $MANIFESTS; do | ||
| echo "" | ||
| echo "━━━ Validating $manifest ━━━" | ||
| if phenotype-journey validate "$manifest"; then | ||
| echo "✓ $manifest: valid" | ||
| else | ||
| echo "✗ $manifest: INVALID" | ||
| exit 1 | ||
| fi | ||
| done | ||
|
|
||
| # --------------------------------------------------------------------- | ||
| # 5. Run assertions in --strict mode | ||
| # --------------------------------------------------------------------- | ||
| - name: Run assertions | ||
| env: | ||
| MANIFEST_LIST: ${{ steps.discover.outputs.MANIFEST_LIST }} | ||
| PHENOTYPE_JOURNEY_STRICT: ${{ inputs.strict_mode && 'true' || 'false' }} | ||
|
There was a problem hiding this comment. Strict mode silently disabled on push/PR triggersHigh Severity The step-level Additional Locations (1)  Reviewed by Cursor Bugbot for commit 3918eb0. Configure here. |
||
| run: | | ||
| # Require strict mode for gated specs | ||
| STRICT="${PHENOTYPE_JOURNEY_STRICT:-true}" | ||
| MANIFESTS="$MANIFEST_LIST" | ||
|
|
||
| for manifest in $MANIFESTS; do | ||
| echo "" | ||
| echo "━━━ Asserting $manifest ━━━" | ||
|
|
||
| if [ "$STRICT" = "true" ]; then | ||
| if phenotype-journey assert "$manifest" --strict; then | ||
| echo "✓ $manifest: all assertions passed" | ||
| else | ||
| echo "✗ $manifest: assertion violated" | ||
| exit 1 | ||
| fi | ||
| else | ||
| phenotype-journey assert "$manifest" || true | ||
| echo "(non-strict run — violations do not fail the build)" | ||
| fi | ||
| done | ||
|
|
||
| # --------------------------------------------------------------------- | ||
| # 6. Live verification (optional, requires ANTHROPIC_API_KEY) | ||
| # --------------------------------------------------------------------- | ||
| - name: Live verification | ||
| if: inputs.live_verification && github.event.inputs.live_verification != 'false' | ||
| env: | ||
| ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} | ||
| MANIFEST_LIST: ${{ steps.discover.outputs.MANIFEST_LIST }} | ||
| run: | | ||
| if [ -z "$ANTHROPIC_API_KEY" ]; then | ||
| echo "::warning::ANTHROPIC_API_KEY secret not set — skipping live verification" | ||
| exit 0 | ||
| fi | ||
|
|
||
| echo "Running live (API) verification..." | ||
| MANIFESTS="$MANIFEST_LIST" | ||
|
|
||
| for manifest in $MANIFESTS; do | ||
| echo "" | ||
| echo "━━━ Live verifying $manifest ━━━" | ||
| if phenotype-journey verify "$manifest" --live; then | ||
| echo "✓ $manifest: live verification passed" | ||
| else | ||
| echo "✗ $manifest: live verification failed" | ||
| exit 1 | ||
| fi | ||
| done | ||
|
|
||
| # --------------------------------------------------------------------- | ||
| # 7. Summary | ||
| # --------------------------------------------------------------------- | ||
| - name: Journey Gate Summary | ||
| run: | | ||
| COUNT="${{ steps.discover.outputs.MANIFEST_COUNT }}" | ||
| echo "" | ||
| echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" | ||
| echo " Journey Gate — Summary" | ||
| echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" | ||
| echo " Manifests checked: $COUNT" | ||
| echo " Strict mode: ${{ inputs.strict_mode || 'true' }}" | ||
| echo " Live mode: ${{ inputs.live_verification && 'enabled' || 'disabled' }}" | ||
| echo "" | ||
| echo "All manifests passed validation and assertions." | ||
| echo "::notice::Journey gate PASSED" | ||
|
|
||
| # -------------------------------------------------------------------------- | ||
| # Stub-mode job: fires only when no manifests are found. | ||
| # Prevents a silent pass when a repo has no journey coverage yet. | ||
| # -------------------------------------------------------------------------- | ||
| stub-mode: | ||
| name: Journey Gate — No Manifests Found | ||
| runs-on: ubuntu-latest | ||
| needs: journey-gate | ||
| if: needs.journey-gate.result == 'failure' && needs.journey-gate.outputs.MANIFEST_COUNT == '0' | ||
|
There was a problem hiding this comment. Missing job outputs makes stub-mode job unreachableMedium Severity The Reviewed by Cursor Bugbot for commit 3918eb0. Configure here.
Comment on lines
+237
to
+238
There was a problem hiding this comment. 🟠 Architect Review — HIGH The Suggestion: Define Fix in Cursor | Fix in VSCode Claude (Use Cmd/Ctrl + Click for best experience) Prompt for AI Agent 🤖This is an **Architect / Logical Review** comment left during a code review. These reviews are first-class, important findings — not optional suggestions. Do NOT dismiss this as a 'big architectural change' just because the title says architect review; most of these can be resolved with a small, localized fix once the intent is understood.
**Path:** .github/workflows/journey-gate.yml
**Line:** 237:238
**Comment:**
*HIGH: The `stub-mode` job's condition references `needs.journey-gate.outputs.MANIFEST_COUNT`, but the `journey-gate` job never defines any outputs, so the stub-mode "no manifests found" branch will never run even when there are zero manifests.
Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
If a suggested approach is provided above, use it as the authoritative instruction. If no explicit code suggestion is given, you MUST still draft and apply your own minimal, localized fix — do not punt back with 'no suggestion provided, review manually'. Keep the change as small as possible: add a guard clause, gate on a loading state, reorder an await, wrap in a conditional, etc. Do not refactor surrounding code or expand scope beyond the finding.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix |
||
| steps: | ||
| - name: Stub notice | ||
| run: | | ||
| echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" | ||
| echo " Journey Gate — STUB MODE" | ||
| echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" | ||
| echo "" | ||
| echo "No manifest.verified.json files were found in this repository." | ||
| echo "" | ||
| echo "To add journey traceability:" | ||
| echo "" | ||
| echo " 1. Install the CLI:" | ||
| echo " brew install phenotype-journey" | ||
| echo " # or: cargo install phenotype-journey" | ||
| echo "" | ||
| echo " 2. Initialise a journey manifest:" | ||
| echo " phenotype-journey init docs/journeys/manifests/<spec-id>" | ||
| echo "" | ||
| echo " 3. Record a tape and extract keyframes:" | ||
| echo " phenotype-journey record --tape <path> --out docs/journeys/" | ||
| echo "" | ||
| echo " 4. Verify and commit:" | ||
| echo " phenotype-journey verify docs/journeys/manifests/<spec-id>/manifest.json" | ||
| echo " # produces manifest.verified.json" | ||
| echo "" | ||
| echo "Once manifest.verified.json files exist, the gate will enforce" | ||
| echo "validation and assertion checks on every push and PR." | ||
| echo "" | ||
| echo "See: phenotype-infra/docs/governance/journey-traceability-standard.md" | ||
| echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| { | ||
| "id": "testingkit-main", | ||
| "intent": "Demonstrate primary user interaction: TestingKit: testing utilities", | ||
| "recording": null, | ||
| "recording_gif": null, | ||
| "keyframe_count": 0, | ||
| "passed": false, | ||
| "steps": [] | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| # Iconography Specification | ||
|
|
||
| Three styles: Fluent (stroke, macOS), Material (filled, Android), Liquid Glass (iOS 25). | ||
|
|
||
| All icons: 24x24 viewBox, currentColor, role=img, aria-label, focusable=false. | ||
|
|
||
| Fluent: stroke=currentColor stroke-width=1.5 stroke-linecap=round stroke-linejoin=round fill=none | ||
| Material: fill=currentColor stroke=none | ||
|
|
||
| Canonical standard: phenotype-infra/docs/governance/iconography-standard.md |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🟠 Architect Review — HIGH
The
workflow_dispatchinputmanifest_pathis defined but never used in the discovery step, which always searches formanifest.verified.jsonvia a hardcodedfindcommand, so manually providing a custom manifest path has no effect.Suggestion: Wire the
manifest_pathworkflow input into the discovery logic (for example by mapping it to an environment variable and using it in thefind/glob expression), or remove the input entirely to avoid exposing a non-functional configuration option.Fix in Cursor | Fix in VSCode Claude
(Use Cmd/Ctrl + Click for best experience)
Prompt for AI Agent 🤖