Skip to content

Commit 2ec31bb

Browse files
codexclaude
codex
and
claude
committed
docs: add journey-traceability + iconography
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent 9d1ee2c commit 2ec31bb

24 files changed

Lines changed: 332 additions & 0 deletions

‎.github/workflows/journey-gate.yml‎

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
1+
# =============================================================================
2+
# Journey Gate — Reusable Workflow
3+
# =============================================================================
4+
# Canonical source: phenotype-infra/docs/governance/ci-journey-gate.yml
5+
# Usage: copy to .github/workflows/journey-gate.yml in the consuming repo.
6+
# Do not modify the logic; extend via workflow_dispatch inputs for
7+
# repo-specific paths or thresholds.
8+
#
9+
# Requirements:
10+
# - phenotype-journey CLI installed in the runner PATH
11+
# - tesseract OCR installed (brew install tesseract / apt-get install tesseract-ocr)
12+
# - ANTHROPIC_API_KEY secret (optional — enables --live mode)
13+
#
14+
# Behaviour:
15+
# - FAILS if no manifest.verified.json files are found (stub mode).
16+
# - FAILS if any manifest fails validation against the JSON schema.
17+
# - FAILS if any assertion is violated in --strict mode.
18+
# - PASSES only when all manifests pass validation AND all assertions pass.
19+
# =============================================================================
20+
21+
name: Journey Gate
22+
23+
on:
24+
push:
25+
branches: [main]
26+
pull_request:
27+
branches: [main]
28+
29+
# Allow manual triggering from the Actions tab.
30+
workflow_dispatch:
31+
inputs:
32+
manifest_path:
33+
description: 'Glob pattern for manifests (default: "**/manifest.verified.json")'
34+
required: false
35+
default: '**/manifest.verified.json'
36+
strict_mode:
37+
description: 'Run assertions in --strict mode (fail on violations)'
38+
required: false
39+
default: 'true'
40+
type: boolean
41+
live_verification:
42+
description: 'Use --live mode (requires ANTHROPIC_API_KEY secret)'
43+
required: false
44+
default: 'false'
45+
type: boolean
46+
47+
env:
48+
PHENOTYPE_JOURNEY_STRICT: ${{ inputs.strict_mode || 'true' }}
49+
50+
jobs:
51+
journey-gate:
52+
name: Journey Verification
53+
runs-on: ubuntu-latest
54+
timeout-minutes: 15
55+
56+
steps:
57+
- name: Checkout
58+
uses: actions/checkout@v4
59+
60+
# ---------------------------------------------------------------------
61+
# 1. Install runtime dependencies
62+
# ---------------------------------------------------------------------
63+
- name: Install tesseract OCR
64+
run: |
65+
sudo apt-get update -qq
66+
sudo apt-get install -y -qq tesseract-ocr \
67+
|| { echo "WARNING: tesseract install failed — assertions will skip"; }
68+
69+
- name: Check tesseract availability
70+
run: |
71+
if command -v tesseract &>/dev/null; then
72+
echo "tesseract: $(tesseract --version | head -1)"
73+
else
74+
echo "tesseract: NOT FOUND — OCR assertions will be skipped"
75+
fi
76+
77+
# ---------------------------------------------------------------------
78+
# 2. Install phenotype-journey CLI
79+
# ---------------------------------------------------------------------
80+
- name: Install phenotype-journey
81+
run: |
82+
if command -v phenotype-journey &>/dev/null; then
83+
echo "phenotype-journey: $(phenotype-journey --version 2>/dev/null || phenotype-journey --help 2>&1 | head -1)"
84+
else
85+
echo "Installing phenotype-journey..."
86+
# Install via cargo if available, else download binary
87+
if command -v cargo &>/dev/null; then
88+
cargo install phenotype-journey --locked \
89+
|| { echo "ERROR: phenotype-journey install failed"; exit 1; }
90+
else
91+
# Download latest release binary (adjust URL as needed)
92+
curl -fsSL https://github.com/KooshaPari/phenotype-journeys/releases/latest/download/phenotype-journey-x86_64-unknown-linux-gnu \
93+
-o /usr/local/bin/phenotype-journey \
94+
&& chmod +x /usr/local/bin/phenotype-journey \
95+
|| { echo "ERROR: phenotype-journey download failed"; exit 1; }
96+
fi
97+
fi
98+
99+
# ---------------------------------------------------------------------
100+
# 3. Find all manifest.verified.json files
101+
# ---------------------------------------------------------------------
102+
- name: Discover manifests
103+
id: discover
104+
run: |
105+
GLOB="${MANIFEST_PATH:-**/manifest.verified.json}"
106+
echo "Glob pattern: $GLOB"
107+
108+
MANIFESTS=$(find . \
109+
-name "manifest.verified.json" \
110+
-not -path "*/node_modules/*" \
111+
-not -path "*/target/*" \
112+
-not -path "*/.git/*" \
113+
-not -path "*/vendor/*" \
114+
2>/dev/null | sort)
115+
116+
if [ -z "$MANIFESTS" ]; then
117+
echo "MANIFEST_COUNT=0" >> $GITHUB_OUTPUT
118+
echo "No manifest.verified.json files found."
119+
echo "::warning::No journey manifests found. Add docs/journeys/manifests/<spec>/manifest.verified.json"
120+
echo ""
121+
echo "To create a stub manifest run:"
122+
echo " phenotype-journey init <journey-name>"
123+
echo ""
124+
echo "Once manifests exist, remove the exit 1 below to enable the gate."
125+
# STUB MODE: fail until manifests exist
126+
exit 1
127+
fi
128+
129+
COUNT=$(echo "$MANIFESTS" | grep -c . || true)
130+
echo "MANIFEST_COUNT=$COUNT" >> $GITHUB_OUTPUT
131+
echo "MANIFEST_LIST<<EOF" >> $GITHUB_OUTPUT
132+
echo "$MANIFESTS" >> $GITHUB_OUTPUT
133+
echo "EOF" >> $GITHUB_OUTPUT
134+
135+
echo "Found $COUNT manifest(s):"
136+
echo "$MANIFESTS"
137+
138+
# ---------------------------------------------------------------------
139+
# 4. Validate each manifest against the JSON schema
140+
# ---------------------------------------------------------------------
141+
- name: Validate manifests
142+
run: |
143+
MANIFESTS="${{ steps.discover.outputs.MANIFEST_LIST }}"
144+
145+
for manifest in $MANIFESTS; do
146+
echo ""
147+
echo "━━━ Validating $manifest ━━━"
148+
if phenotype-journey validate "$manifest"; then
149+
echo "✓ $manifest: valid"
150+
else
151+
echo "✗ $manifest: INVALID"
152+
exit 1
153+
fi
154+
done
155+
156+
# ---------------------------------------------------------------------
157+
# 5. Run assertions in --strict mode
158+
# ---------------------------------------------------------------------
159+
- name: Run assertions
160+
env:
161+
MANIFEST_LIST: ${{ steps.discover.outputs.MANIFEST_LIST }}
162+
PHENOTYPE_JOURNEY_STRICT: ${{ inputs.strict_mode && 'true' || 'false' }}
163+
run: |
164+
# Require strict mode for gated specs
165+
STRICT="${PHENOTYPE_JOURNEY_STRICT:-true}"
166+
MANIFESTS="$MANIFEST_LIST"
167+
168+
for manifest in $MANIFESTS; do
169+
echo ""
170+
echo "━━━ Asserting $manifest ━━━"
171+
172+
if [ "$STRICT" = "true" ]; then
173+
if phenotype-journey assert "$manifest" --strict; then
174+
echo "✓ $manifest: all assertions passed"
175+
else
176+
echo "✗ $manifest: assertion violated"
177+
exit 1
178+
fi
179+
else
180+
phenotype-journey assert "$manifest" || true
181+
echo "(non-strict run — violations do not fail the build)"
182+
fi
183+
done
184+
185+
# ---------------------------------------------------------------------
186+
# 6. Live verification (optional, requires ANTHROPIC_API_KEY)
187+
# ---------------------------------------------------------------------
188+
- name: Live verification
189+
if: inputs.live_verification && github.event.inputs.live_verification != 'false'
190+
env:
191+
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
192+
MANIFEST_LIST: ${{ steps.discover.outputs.MANIFEST_LIST }}
193+
run: |
194+
if [ -z "$ANTHROPIC_API_KEY" ]; then
195+
echo "::warning::ANTHROPIC_API_KEY secret not set — skipping live verification"
196+
exit 0
197+
fi
198+
199+
echo "Running live (API) verification..."
200+
MANIFESTS="$MANIFEST_LIST"
201+
202+
for manifest in $MANIFESTS; do
203+
echo ""
204+
echo "━━━ Live verifying $manifest ━━━"
205+
if phenotype-journey verify "$manifest" --live; then
206+
echo "✓ $manifest: live verification passed"
207+
else
208+
echo "✗ $manifest: live verification failed"
209+
exit 1
210+
fi
211+
done
212+
213+
# ---------------------------------------------------------------------
214+
# 7. Summary
215+
# ---------------------------------------------------------------------
216+
- name: Journey Gate Summary
217+
run: |
218+
COUNT="${{ steps.discover.outputs.MANIFEST_COUNT }}"
219+
echo ""
220+
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
221+
echo " Journey Gate — Summary"
222+
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
223+
echo " Manifests checked: $COUNT"
224+
echo " Strict mode: ${{ inputs.strict_mode || 'true' }}"
225+
echo " Live mode: ${{ inputs.live_verification && 'enabled' || 'disabled' }}"
226+
echo ""
227+
echo "All manifests passed validation and assertions."
228+
echo "::notice::Journey gate PASSED"
229+
230+
# --------------------------------------------------------------------------
231+
# Stub-mode job: fires only when no manifests are found.
232+
# Prevents a silent pass when a repo has no journey coverage yet.
233+
# --------------------------------------------------------------------------
234+
stub-mode:
235+
name: Journey Gate — No Manifests Found
236+
runs-on: ubuntu-latest
237+
needs: journey-gate
238+
if: needs.journey-gate.result == 'failure' && needs.journey-gate.outputs.MANIFEST_COUNT == '0'
239+
steps:
240+
- name: Stub notice
241+
run: |
242+
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
243+
echo " Journey Gate — STUB MODE"
244+
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
245+
echo ""
246+
echo "No manifest.verified.json files were found in this repository."
247+
echo ""
248+
echo "To add journey traceability:"
249+
echo ""
250+
echo " 1. Install the CLI:"
251+
echo " brew install phenotype-journey"
252+
echo " # or: cargo install phenotype-journey"
253+
echo ""
254+
echo " 2. Initialise a journey manifest:"
255+
echo " phenotype-journey init docs/journeys/manifests/<spec-id>"
256+
echo ""
257+
echo " 3. Record a tape and extract keyframes:"
258+
echo " phenotype-journey record --tape <path> --out docs/journeys/"
259+
echo ""
260+
echo " 4. Verify and commit:"
261+
echo " phenotype-journey verify docs/journeys/manifests/<spec-id>/manifest.json"
262+
echo " # produces manifest.verified.json"
263+
echo ""
264+
echo "Once manifest.verified.json files exist, the gate will enforce"
265+
echo "validation and assertion checks on every push and PR."
266+
echo ""
267+
echo "See: phenotype-infra/docs/governance/journey-traceability-standard.md"
268+
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

‎docs/journeys/manifests/main-flow.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"id": "helios-cli-main",
3+
"intent": "Primary usage: helios-cli: CLI framework (precursor to HeliosCLI)",
4+
"recording": null,
5+
"recording_gif": null,
6+
"keyframe_count": 0,
7+
"passed": false,
8+
"steps": []
9+
}

‎docs/operations/iconography/SPEC.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Iconography Specification
2+
3+
Three styles: Fluent (stroke), Material (filled), Liquid Glass (iOS 25).
4+
All icons: 24x24 viewBox, currentColor, role=img, aria-label, focusable=false.
5+
6+
Canonical: phenotype-infra/docs/governance/iconography-standard.md

‎docs/operations/iconography/fluent/branch.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs/operations/iconography/fluent/dashboard.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs/operations/iconography/fluent/home.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs/operations/iconography/fluent/package.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs/operations/iconography/fluent/plugin.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs/operations/iconography/fluent/search.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs/operations/iconography/fluent/settings.svg‎

Lines changed: 1 addition & 0 deletions
Loading

0 commit comments

Comments
 (0)