You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Jan 31, 2026. It is now read-only.
Rationale: PATCH version bump - Reorganized principle ordering by moving Specification-Driven Development (formerly XIII) to position XI, renumbering subsequent principles for better logical flow
4
+
Version Change: 1.7.1 → 1.8.0
5
+
Rationale: MINOR version bump - Added new Principle XIII: Jupyter Notebook Discipline to govern exploratory data science workflows in government AI projects, and swapped positions of Streamlit-to-Production Bridge (now XIV) and Jupyter Notebook Discipline (now XIII)
6
6
7
-
Modified Principles:
8
-
- Principle XI: Now "Specification-Driven Development with SpecKit" (formerly Principle XIII)
9
-
- Principle XII: Now "French Government AI Stack Integration" (formerly Principle XI)
10
-
- Principle XIII: Now "Streamlit-to-Production Bridge" (formerly Principle XII)
7
+
Added Sections:
8
+
- Principle XIII: Jupyter Notebook Discipline - Establishes governance for notebooks in top-level notebooks/ folder
- Specification-Driven Development (new XI) logically follows Python-First Development (X) as both are foundational development practices
14
-
- French Government AI Stack Integration (new XII) and Streamlit-to-Production Bridge (new XIII) are more specific implementation concerns that build on the foundational principles
15
+
Modified Principles:
16
+
- Principle XIII: Now "Jupyter Notebook Discipline" (new principle)
17
+
- Principle XIV: Now "Streamlit-to-Production Bridge" (formerly Principle XIII)
15
18
16
19
Removed Sections: N/A
17
20
18
21
Templates Requiring Updates:
19
-
- ✅ plan-template.md: Updated principle numbers in Constitution Check
22
+
- ✅ plan-template.md: Updated - Added Principle XIV checkbox to Constitution Check section
20
23
- ✅ spec-template.md: Already aligned (no principle-specific references)
21
24
- ✅ tasks-template.md: Already aligned (no principle-specific references)
22
25
23
26
Follow-up TODOs:
27
+
- Create feature spec for notebooks/ folder infrastructure (002-jupyter-notebook-support)
28
+
- Add nbstripout to pre-commit hooks
29
+
- Add notebooks/ to .gitignore patterns for output files
- Consider adding risk assessment template aligned with ANSSI requirements
@@ -384,7 +393,97 @@ ai-kit MUST provide first-class integrations with the emerging French Government
384
393
385
394
**Rationale**: Standardizing on government-approved AI infrastructure ensures compliance, reduces duplication, and enables teams to focus on domain-specific value rather than infrastructure.
386
395
387
-
### XIII. Streamlit-to-Production Bridge
396
+
### XIII. Jupyter Notebook Discipline
397
+
398
+
ai-kit projects MUST maintain Jupyter notebooks in a top-level `notebooks/` directory with clear governance to balance exploratory data science workflows with security, reproducibility, and compliance requirements.
399
+
400
+
**Notebook Categories**:
401
+
402
+
Notebooks MUST be organized by purpose to clarify their role in the development lifecycle:
403
+
404
+
-**Exploratory** (`notebooks/exploratory/`): Rapid experimentation, hypothesis testing, data exploration
405
+
- Not subject to SpecKit workflow requirements
406
+
- May contain incomplete or experimental code
407
+
- MUST NOT contain production credentials or sensitive data
408
+
- Should be cleaned up or archived when insights are productionized
- Conduct security review before publishing notebooks to public repositories
429
+
- Document data sources and ensure compliance with GDPR and data protection regulations
430
+
431
+
**Quality Standards**:
432
+
433
+
-**Reproducibility**: Notebooks MUST include dependency specifications (requirements.txt, environment.yml, or uv workspace)
434
+
-**Documentation**: Each notebook MUST include:
435
+
- Purpose and context (what question does this answer?)
436
+
- Author and date
437
+
- Data sources and versions
438
+
- Expected runtime and resource requirements
439
+
- Known limitations or assumptions
440
+
-**Version Control**: Notebooks MUST be committed with outputs stripped (use `nbstripout` pre-commit hook)
441
+
-**Code Quality**: Notebook code SHOULD follow Python standards (ruff linting where practical)
442
+
-**Cell Organization**: Use markdown cells to structure narrative, avoid monolithic code cells
443
+
444
+
**Integration with SpecKit Workflow**:
445
+
446
+
-**Exploratory notebooks**: Not required to follow SpecKit workflow, but insights MUST be captured in specifications when productionized
447
+
-**Documentation notebooks**: Should be referenced in feature specifications (spec.md) and quickstart guides
448
+
-**Production-adjacent notebooks**: MUST be documented in `plan.md` research section and referenced in compliance documentation
449
+
450
+
**EU AI Act Compliance**:
451
+
452
+
For high-risk AI systems, production-adjacent notebooks MUST:
453
+
454
+
- Document model training data characteristics (representativeness, quality, completeness)
455
+
- Record model evaluation metrics and validation results
456
+
- Capture risk assessment findings and mitigation strategies
457
+
- Provide audit trail for model selection and hyperparameter tuning decisions
458
+
- Support technical documentation requirements for homologation dossier
459
+
460
+
**Tooling Standards**:
461
+
462
+
-**nbstripout**: Pre-commit hook to remove outputs before commit
463
+
-**nbconvert**: Convert notebooks to scripts or documentation formats
464
+
-**papermill**: Parameterize and execute notebooks programmatically for reproducible reporting
465
+
-**ruff**: Lint notebook code cells (via `nbqa` or similar)
466
+
-**uv**: Manage notebook dependencies within monorepo workspace
467
+
468
+
**Migration to Production**:
469
+
470
+
When notebook insights become production features:
471
+
472
+
1. Extract reusable code into `packages/` or `apps/` with proper testing
473
+
2. Document the notebook-to-production migration in feature specification
474
+
3. Archive or move exploratory notebooks to `notebooks/archive/` to reduce clutter
475
+
4. Retain production-adjacent notebooks for compliance and audit purposes
476
+
5. Follow Principle XI (Specification-Driven Development) for production implementation
477
+
478
+
**Rationale**: Jupyter notebooks are essential for AI/ML experimentation and data science workflows, but without governance they become security risks, compliance liabilities, and sources of technical debt. This principle acknowledges the exploratory nature of notebooks while establishing guardrails that prevent common pitfalls: credential leakage, irreproducible results, and undocumented model decisions. By categorizing notebooks and integrating them with SpecKit workflow, we enable rapid innovation while maintaining traceability for compliance and production migration.
ai-kit MUST provide a clear migration path from Streamlit prototypes to production-ready applications. This principle addresses the common pattern where:
390
489
@@ -575,7 +674,8 @@ All feature specifications and implementation plans MUST include a Constitution
575
674
- Python-first development (Principle X)
576
675
- Specification-driven development with SpecKit workflows (Principle XI)
577
676
- Government AI stack integration requirements (Principle XII)
578
-
- Streamlit-to-production support if applicable (Principle XIII)
677
+
- Jupyter notebook discipline and governance if applicable (Principle XIII)
678
+
- Streamlit-to-production support if applicable (Principle XIV)
579
679
580
680
### Complexity Justification
581
681
@@ -586,4 +686,4 @@ Any deviation from these principles MUST be documented with:
Copy file name to clipboardExpand all lines: .specify/templates/plan-template.md
+2-1Lines changed: 2 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -45,7 +45,8 @@ Verify compliance with ai-kit constitution principles:
45
45
-[ ]**Python-First Development (Principle X)**: Is Python the primary language? Are non-Python components justified?
46
46
-[ ]**Specification-Driven Development (Principle XI)**: Does this feature follow the SpecKit workflow (specify → plan → tasks → implement)? Are all design artifacts present in specs/[###-feature-name]/? Is traceability maintained from spec to implementation?
47
47
-[ ]**French Government AI Stack Integration (Principle XII)**: Does the feature integrate with OpenGateLLM, EvalAP, or other government AI services where applicable?
48
-
-[ ]**Streamlit-to-Production Bridge (Principle XIII)**: If using Streamlit, is there a migration path to Reflex? Are ProConnect and DSFR integrations planned?
48
+
-[ ]**Jupyter Notebook Discipline (Principle XIII)**: If using notebooks, are they organized in notebooks/ with proper categorization (exploratory/documentation/production-adjacent)? Are security requirements met (no credentials, nbstripout configured)? Are quality standards followed (reproducibility, documentation)?
49
+
-[ ]**Streamlit-to-Production Bridge (Principle XIV)**: If using Streamlit, is there a migration path to Reflex? Are ProConnect and DSFR integrations planned?
49
50
50
51
**Violations Requiring Justification**: [List any principle violations with rationale, or state "None"]
- Documentation: purpose, author, data sources, runtime requirements
39
+
- Version control: outputs stripped before commit
40
+
- Code quality: ruff linting where practical
41
+
- Cell organization: structured narrative with markdown
42
+
43
+
### 4. Integration with SpecKit Workflow
44
+
45
+
-**Exploratory**: Not required to follow SpecKit, but insights must be captured when productionized
46
+
-**Documentation**: Referenced in spec.md and quickstart guides
47
+
-**Production-adjacent**: Documented in plan.md research section
48
+
49
+
### 5. EU AI Act Compliance
50
+
51
+
Production-adjacent notebooks for high-risk AI systems must document:
52
+
- Model training data characteristics
53
+
- Evaluation metrics and validation results
54
+
- Risk assessment findings
55
+
- Model selection audit trail
56
+
- Technical documentation for homologation dossier
57
+
58
+
### 6. Tooling Standards
59
+
60
+
-**nbstripout**: Remove outputs before commit
61
+
-**nbconvert**: Convert to scripts/docs
62
+
-**papermill**: Parameterize and execute programmatically
63
+
-**ruff**: Lint notebook code (via nbqa)
64
+
-**uv**: Manage dependencies in monorepo
65
+
66
+
### 7. Migration to Production
67
+
68
+
Clear 5-step process:
69
+
1. Extract code to `packages/` or `apps/`
70
+
2. Document migration in feature spec
71
+
3. Archive exploratory notebooks
72
+
4. Retain production-adjacent for compliance
73
+
5. Follow Principle XI for production implementation
74
+
75
+
## Why This Matters
76
+
77
+
### Problems Solved
78
+
79
+
1.**Security Risk**: Prevents accidental credential commits in notebooks
80
+
2.**Compliance Liability**: Ensures notebooks support EU AI Act documentation requirements
81
+
3.**Technical Debt**: Provides clear migration path from exploration to production
82
+
4.**Irreproducibility**: Mandates dependency management and documentation
83
+
5.**Audit Trail**: Establishes governance for model decisions and evaluations
84
+
85
+
### Alignment with Existing Principles
86
+
87
+
-**Principle I (EU AI Act)**: Production-adjacent notebooks support compliance documentation
88
+
-**Principle III (Security Homologation)**: Security requirements prevent credential leakage
89
+
-**Principle IV (Open Source)**: Guidance on what can be published publicly
90
+
-**Principle X (Python-First)**: Notebooks align with Python-first culture
91
+
-**Principle XI (SpecKit)**: Integration with specification-driven workflow
92
+
93
+
## Template Updates
94
+
95
+
### ✅ Completed
96
+
97
+
-**constitution.md**: Added Principle XIII (Jupyter Notebook Discipline) with full governance framework, swapped with Streamlit-to-Production Bridge (now XIV)
0 commit comments