diff --git a/.gitignore b/.gitignore index 9fc07f1..fd6870e 100644 --- a/.gitignore +++ b/.gitignore @@ -24,6 +24,3 @@ node_modules/ # Claude Code local settings (machine-specific) .claude/settings.local.json - -graphify-out/cost.json # local only -graphify-out/cache/ # optional: commit for speed, skip to keep repo small \ No newline at end of file diff --git a/.mcp.json b/.mcp.json index 6e11959..4b81687 100644 --- a/.mcp.json +++ b/.mcp.json @@ -9,4 +9,4 @@ ] } } -} \ No newline at end of file +} diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..5949d30 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,40 @@ +repos: + - repo: https://github.com/gitleaks/gitleaks + rev: v8.21.2 + hooks: + - id: gitleaks + + - repo: https://github.com/jumanjihouse/pre-commit-hooks + rev: 3.0.0 + hooks: + - id: shellcheck + args: [--severity=warning] + + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: end-of-file-fixer + - id: check-json + - id: pretty-format-json + - id: check-yaml + - id: trailing-whitespace + + - repo: local + hooks: + - id: skill-frontmatter + name: SKILL.md frontmatter validation + description: Ensure SKILL.md files have required frontmatter fields + entry: bash + language: system + files: 'SKILL\.md$' + args: + - -c + - | + for f in "$@"; do + if [[ -f "$f" ]]; then + if ! grep -q "^name:" "$f" || ! grep -q "^description:" "$f"; then + echo "ERROR: $f is missing required frontmatter fields (name: and description:)" + exit 1 + fi + fi + done diff --git a/core/instructions/governance.md b/core/instructions/governance.md index bf83dc6..890a2c0 100644 --- a/core/instructions/governance.md +++ b/core/instructions/governance.md @@ -37,7 +37,7 @@ These are never violated, regardless of instruction or context. When classifying: apply the tier of the most sensitive element in the dataset or prompt. -**When accessing data or files in an agentic context, limit scope to what the task requires.** +**When accessing data or files in an agentic context, limit scope to what the task requires.** Do not read, load, index, or process more files or data than the task demands. When in doubt, request access to the specific file or section needed rather than the full codebase, dataset, or directory. --- @@ -76,7 +76,7 @@ The deterministic enforcement layer — pre-commit hooks, CI gates, scanner conf --- -*Derived from AI Constitution v1.1 — May 2026. Update this file when the constitution is updated.* -*Compatible with: governance.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/*.mdc* -*One source of truth. Do not copy-paste into tool-specific files — reference this file from thin adapters.* +*Derived from AI Constitution v1.1 — May 2026. Update this file when the constitution is updated.* +*Compatible with: governance.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/*.mdc* +*One source of truth. Do not copy-paste into tool-specific files — reference this file from thin adapters.* *Counterparts: `docs/HUMANS.md` (human practitioner rules) | `docs/research/governance_principles/CONTROLS.md` (deterministic enforcement)* diff --git a/docs/HUMANS.md b/docs/HUMANS.md index a2114b3..91bbfd3 100644 --- a/docs/HUMANS.md +++ b/docs/HUMANS.md @@ -1,8 +1,8 @@ # Human Practitioner Instructions -Applies to: anyone using AI tools in software development, infrastructure, or technical decision-making. -Full governance context: `docs/ai-constitution.md` — read it when a situation isn't covered here. -Agent counterpart: `core/instructions/governance.md` — the operative rules for AI agents in the same context. +Applies to: anyone using AI tools in software development, infrastructure, or technical decision-making. +Full governance context: `docs/ai-constitution.md` — read it when a situation isn't covered here. +Agent counterpart: `core/instructions/governance.md` — the operative rules for AI agents in the same context. This file is the human-actionable distillation: what you, as the practitioner, are responsible for. --- @@ -21,89 +21,89 @@ These are never compromised, regardless of deadline, convenience, or context. ## Before: Starting an AI-Assisted Task -**Classify the data you're about to share.** +**Classify the data you're about to share.** Ask: what tier is this? Public, Internal, Confidential, or Restricted? Apply the tier of the most sensitive element. If it's Confidential, confirm you're using a tool with contractual data-not-trained guarantees. If it's Restricted, stop — it doesn't enter AI context. -**Send only what the task requires.** +**Send only what the task requires.** Do not share full codebases, entire logs, or complete datasets when a relevant excerpt would serve equally well. Anonymise or pseudonymise personal data before AI input wherever feasible. More context than necessary increases exposure without improving the output. -**Use the right tool for the data tier.** +**Use the right tool for the data tier.** Consumer and free-tier AI products handle Public data only. Everything else requires enterprise tooling with an explicit contractual commitment. Verify per provider; do not assume. -**Define what success looks like before you start.** +**Define what success looks like before you start.** AI usage without a success criterion is unjustifiable — the environmental and operational costs are real. What does a good outcome look like? How will you know if the AI helped or misled you? -**Know what scope you're granting.** +**Know what scope you're granting.** If you're running an agentic workflow, be explicit about what the agent may and may not do before it starts. Ambiguous scope means the agent will make judgment calls you didn't authorise. --- ## During: Working with the AI -**Don't trust confident output — especially fluent, well-formatted confident output.** +**Don't trust confident output — especially fluent, well-formatted confident output.** Linguistic fluency and factual accuracy are unrelated. Confident language is a sycophancy signal. The more certain and complete an AI response sounds, the more carefully you should validate it. -**On high-stakes questions, don't prompt for brevity.** +**On high-stakes questions, don't prompt for brevity.** Conciseness instructions demonstrably degrade factual reliability. Where accuracy matters, prompt for accuracy. Ask the AI to show its reasoning. -**On contested, values-laden, or complex technical questions, prompt explicitly for dissenting views.** +**On contested, values-laden, or complex technical questions, prompt explicitly for dissenting views.** AI outputs are majority-weighted, not neutral. A single response on an architectural decision, risk assessment, or ethical question reflects the dominant training-data perspective. Ask: "What are the strongest arguments against this?" before treating the first output as balanced. -**Cross-validate any output that informs a consequential decision.** +**Cross-validate any output that informs a consequential decision.** Architecture, security configuration, deployment, legal, financial — validate against an independent source or a second model. AI agreement with itself is not validation. -**Review AI-generated code before accepting it.** +**Review AI-generated code before accepting it.** Check specifically for: hardcoded credentials; insecure patterns (injection vulnerabilities, overly permissive access); copyleft-licensed fragments (GPL, AGPL) without licence headers; missing or incorrect dependencies. This review is not optional and is not the AI's job. -**Apply a human checkpoint before any production, architecture, or infrastructure change.** +**Apply a human checkpoint before any production, architecture, or infrastructure change.** No AI-initiated change to production systems, security configuration, or infrastructure is applied without explicit human review and approval of the specific change. This is a hard rule, not a guideline. -**For repeatable tasks, ask AI to generate a script — not to do the task repeatedly.** +**For repeatable tasks, ask AI to generate a script — not to do the task repeatedly.** If a task has a correct answer that does not depend on context or judgement, use AI once to write a script that runs it deterministically. The script goes in version control; the script is the governed artefact. Invoking AI inference each time a repeatable task runs adds cost, unreliability, and attack surface for no benefit. The break-even is roughly 17 invocations — anything recurring beyond that should be codified. -**Manage the volume of AI-generated output to what you can genuinely evaluate.** -When an agentic workflow generates large quantities of code or changes, approving them as a batch is not review — it is rubber-stamping. If throughput exceeds your verification capacity, reduce it. Output volume is a governance variable, not just a productivity one. +**Manage the volume of AI-generated output to what you can genuinely evaluate.** +When an agentic workflow generates large quantities of code or changes, approving them as a batch is not review — it is rubber-stamping. If throughput exceeds your verification capacity, reduce it. Output volume is a governance variable, not just a productivity one. Over-reliance on AI for tasks that build critical skills creates cognitive dependency — measurably. If you couldn't do this task without AI and that matters for your ability to audit, debug, or override the AI, that's a governance risk, not just a personal one. Rotate AI-free approaches periodically on skill-critical work. --- ## After: Completing AI-Assisted Work -**Verify you own the output.** +**Verify you own the output.** Before committing AI-generated code: can you explain what it does and why? Can you modify it at the intent and architecture level? Can you verify its behaviour? If not, you have not reviewed it — you have approved it. These are not the same thing. -**Licence-scan AI-generated code before committing.** +**Licence-scan AI-generated code before committing.** Copyleft-licensed fragments can appear in AI output without licence headers. Manifest-based scanners don't catch them. Run a dedicated licence scan on AI-assisted contributions. -**Document your human contribution.** +**Document your human contribution.** Version control history, code review records, and prompt logs together constitute evidence of authorship and accountability. Where IP protection or accountability matters, the human contribution must be substantive and traceable. -**Disclose AI involvement where it affects others.** +**Disclose AI involvement where it affects others.** If an AI-assisted output informs a decision that affects other people — a report, recommendation, architecture review, or policy — disclose the AI involvement. This is an ethical obligation regardless of legal requirement. -**Log AI-agent actions that produce effects.** +**Log AI-agent actions that produce effects.** Any agent action that changes state must leave a human-readable trace: what was the prompt, what model, what action was taken, what was the outcome. Isolated timestamps are not sufficient. -**Version prompts used in production.** +**Version prompts used in production.** Production prompts are code. They need version control, a change log recording what changed and why, and human review before deployment. Unversioned prompts are unauditable. -**If using AI output commercially, verify the provider's IP terms.** +**If using AI output commercially, verify the provider's IP terms.** Rights to AI-generated outputs vary significantly by provider and tier. Review the terms of service specifically for output ownership clauses, IP indemnification, and restrictions before using AI-assisted code or content in commercial software. Enterprise agreements must address these explicitly — do not assume standard terms provide coverage. -**Measure value delivered.** +**Measure value delivered.** Did this AI integration do what it was supposed to do? If you defined success before you started, check it now. Deployments that haven't crossed into measurable value delivery must be time-bounded and reviewed, not left running indefinitely. --- ## When Things Go Wrong -**Diagnose first; remediate with human approval.** +**Diagnose first; remediate with human approval.** AI-assisted diagnosis and root cause analysis can run. Applying remediation to production — rollback, config change, scaling decision — requires explicit human approval unless the action is pre-defined, bounded, and reversible. -**Post-mortem every AI-involved incident.** +**Post-mortem every AI-involved incident.** Cover: what instructions the agent operated under, what decision it made, what the failure mode was, and what governance change prevents recurrence. AI incidents are not a different category from service incidents — same rigour applies. -**Regulatory notification obligations don't pause because AI was involved.** +**Regulatory notification obligations don't pause because AI was involved.** GDPR Article 33/34 timelines and thresholds apply regardless of whether an AI system caused or contributed to the incident. --- @@ -116,5 +116,5 @@ Controls that run mechanically — pre-commit hooks, CI gates, scanner configura --- -*Derived from AI Constitution v1.1 — May 2026.* +*Derived from AI Constitution v1.1 — May 2026.* *Counterpart to: `core/instructions/governance.md` (agent rules) | `docs/research/governance_principles/CONTROLS.md` (deterministic enforcement) | Full context: `docs/ai-constitution.md`* diff --git a/docs/ai-constitution.md b/docs/ai-constitution.md index 5aa9ecb..b236f69 100644 --- a/docs/ai-constitution.md +++ b/docs/ai-constitution.md @@ -1,52 +1,52 @@ # AI Constitution -**Version:** 1.1 (corrections from deep research pass applied May 2026) -**Scope:** All AI-assisted software development, deployment, and infrastructure management -**Audience:** Humans and AI agents operating in this context -**Inheritance:** Solo-authored; designed to be inherited by future collaborators and AI agents without requiring the author present -**Derivation:** Derived from sourced research across ten governance topics. Principles are evidence-based, not aspirational. +**Version:** 1.1 (corrections from deep research pass applied May 2026) +**Scope:** All AI-assisted software development, deployment, and infrastructure management +**Audience:** Humans and AI agents operating in this context +**Inheritance:** Solo-authored; designed to be inherited by future collaborators and AI agents without requiring the author present +**Derivation:** Derived from sourced research across ten governance topics. Principles are evidence-based, not aspirational. **Operative agent instructions:** See `core/instructions/governance.md` — the concise, agent-actionable distillation of this document for global context use. --- ## 1. Accountability -**Accountability is non-transferable.** +**Accountability is non-transferable.** Every AI-generated output that enters a system, codebase, or production environment is owned by the human who accepted it. AI assistance does not reduce or distribute responsibility. "The model produced it" is not a defence — legally, ethically, or operationally. -**Ethics commitments must be concrete and auditable.** +**Ethics commitments must be concrete and auditable.** Any principle in this document that cannot be tested or verified is not a principle — it is a claim. If compliance cannot be demonstrated, the commitment does not exist. --- ## 2. Security -**Secrets must never enter AI context.** +**Secrets must never enter AI context.** Credentials, API keys, tokens, passwords, and certificates must not appear in prompts, context files, RAG pipelines, or any input to an AI system. This is an architectural constraint, not a reminder. Scan context before it reaches a model. -**Never use AI-generated secrets, passwords, or cryptographic material.** +**Never use AI-generated secrets, passwords, or cryptographic material.** LLM-generated passwords have demonstrably insufficient entropy and exhibit predictable patterns. Use cryptographically secure random sources for all credential generation. -**AI-generated code is untrusted by default.** +**AI-generated code is untrusted by default.** Review AI-generated code with more scrutiny than human-written code — specifically for hardcoded credentials, insecure patterns, and licence-encumbered fragments — before any commit. -**Apply least-privilege to all AI agents.** +**Apply least-privilege to all AI agents.** Agents receive only the permissions required for their specific, current task. Long-lived, broad-scope tokens for AI agents are prohibited. Scope credentials tightly; rotate frequently. -**Apply OWASP LLM Top 10 and Agentic AI Top 10 as baseline security requirements.** +**Apply OWASP LLM Top 10 and Agentic AI Top 10 as baseline security requirements.** Prompt injection, supply chain risks, excessive agency, sensitive information disclosure, and system prompt leakage require explicit controls. Traditional AppSec frameworks do not cover these attack surfaces. -**AI pipelines must surface uncertainty; never treat confident AI output as accurate output.** +**AI pipelines must surface uncertainty; never treat confident AI output as accurate output.** Chaining AI subsystems without propagating confidence levels creates compounding, invisible error. Uncertain outputs require human review before consequential action. --- ## 3. Data Protection & Classification -**Sending personal data to an AI system is data processing under GDPR.** +**Sending personal data to an AI system is data processing under GDPR.** It requires a lawful basis, a defined purpose, and appropriate safeguards. This applies to prompts, RAG pipelines, and fine-tuning data equally. There is no "just testing" exemption. -**The context window is a data store. Classify it accordingly.** +**The context window is a data store. Classify it accordingly.** Everything that enters an AI prompt is subject to the same classification obligations as any other data store. Apply the classification framework below. ### Data Classification for AI Systems @@ -58,168 +58,168 @@ Everything that enters an AI prompt is subject to the same classification obliga | 3 | **Confidential** | Proprietary source code, system architecture, IP, identifiable personal data | Enterprise AI with explicit data-not-used-for-training contractual commitment; GDPR legal basis required for personal data | | 4 | **Restricted** | GDPR Article 9 special categories (health, biometrics, ethnicity, religion, sexual orientation, political views), credentials, regulated financial data, data under professional secrecy | Never enters any AI context. Hard architectural prohibition. | -**Consumer and free-tier AI products are incompatible with processing organisational or personal data.** +**Consumer and free-tier AI products are incompatible with processing organisational or personal data.** Enterprise contracts with explicit data-not-used-for-training commitments are the minimum bar. Verify per provider; do not assume. -**Data minimisation applies to AI prompts.** +**Data minimisation applies to AI prompts.** Send only what is necessary for the task. Anonymise or pseudonymise personal data before AI input wherever feasible. -**Personal data must not enter AI fine-tuning or RAG pipelines without a GDPR legal basis and a completed DPIA.** +**Personal data must not enter AI fine-tuning or RAG pipelines without a GDPR legal basis and a completed DPIA.** Right-to-erasure obligations under Article 17 cannot be fulfilled once data is encoded in model weights. This decision is irreversible. --- ## 4. Behaviour & Sycophancy -**Sycophancy is a first-class reliability and ethical risk.** +**Sycophancy is a first-class reliability and ethical risk.** AI systems trained via RLHF systematically prioritise approval over accuracy. This is the most tractable cause of hallucination and must be explicitly designed against — through prompting standards, model selection, and evaluation criteria. -**Never interpret AI agreement as AI accuracy.** +**Never interpret AI agreement as AI accuracy.** Models change correct answers to wrong ones under user pressure in a majority of observed cases, then persist in the wrong answer. Challenge AI outputs before trusting them; agreement is not confirmation. -**In high-stakes contexts, never prompt for brevity at the expense of accuracy.** +**In high-stakes contexts, never prompt for brevity at the expense of accuracy.** Conciseness instructions demonstrably degrade factual reliability. Where accuracy matters, prompt for accuracy. -**Cross-validate consequential AI outputs.** +**Cross-validate consequential AI outputs.** Any AI-generated output that informs a significant decision — architecture, security configuration, deployment, legal or financial — must be validated against an independent source or a second model before acting on it. -**Select models partly on sycophancy resistance.** +**Select models partly on sycophancy resistance.** Model selection for professional use must include evaluation of sycophancy behaviour alongside capability benchmarks. Use a portfolio of benchmarks (MASK, SYCON-Bench, SycEval) — rankings flip across evaluations and no single benchmark is reliable. Run your own deployment-stage test for your specific task context; do not rely on vendor or single-study claims about which model family is most resistant. -**In domains where diverse perspectives matter, prompt explicitly for multiple viewpoints and dissenting positions.** +**In domains where diverse perspectives matter, prompt explicitly for multiple viewpoints and dissenting positions.** AI systems are trained in ways that systematically suppress annotator disagreements, producing outputs weighted toward dominant viewpoints at the expense of minority or dissenting positions (arxiv 2505.07772). A single AI output on a contested, values-laden, or socially complex question is not a neutral summary — it is a majority-weighted perspective. In architecture decisions, risk assessments, ethical questions, and any domain with genuine expert disagreement, prompt for counterarguments and dissenting views explicitly; do not treat the first output as balanced. -**In domains where diverse perspectives matter, prompt explicitly for dissent.** +**In domains where diverse perspectives matter, prompt explicitly for dissent.** AI systems trained to suppress annotator disagreement produce outputs that systematically underrepresent non-dominant viewpoints (arxiv 2505.07772). In architecture decisions, ethics reviews, risk assessments, and anything affecting underrepresented groups — explicitly prompt for minority positions, dissenting analysis, and counterarguments. Cross-validation against independent sources partially compensates for homogenisation; active prompting for dissent addresses it more directly. --- ## 5. Human Oversight & Automation Boundaries -**Human oversight must be genuine, not symbolic.** +**Human oversight must be genuine, not symbolic.** Assigning a reviewer does not constitute oversight unless they have the information, time, agency, and intent to evaluate the output meaningfully. Review processes must make genuine evaluation possible. -**Production systems require a human checkpoint before any AI-initiated change.** +**Production systems require a human checkpoint before any AI-initiated change.** This is a hard rule. No architecture change, infrastructure modification, security configuration, or production deployment may be applied by an AI agent without explicit human review and approval of the specific change. -**Humans must own the code — not just approve it.** +**Humans must own the code — not just approve it.** The required comprehension standard (ACM/IEEE-CS Software Engineering Code of Ethics) is: intent-level understanding of what the code does and why; architectural understanding of how it fits the system; and verifiable behaviour via tests or traceable reasoning. Line-by-line comprehension of every implementation detail is not required and not the professional standard. What is required: a developer cannot commit AI-generated code they cannot explain, modify at the intent-and-architecture level, or verify against defined behaviour — with or without AI assistance for the verification step itself. -**Limit AI output volume to what reviewers can genuinely evaluate.** +**Limit AI output volume to what reviewers can genuinely evaluate.** When AI-generated change throughput exceeds human verification capacity, approvals become rubber-stamps. Output rates must be managed to preserve the possibility of genuine review. -**Distinguish HITL from HOTL deliberately.** +**Distinguish HITL from HOTL deliberately.** Human-in-the-loop (HITL) pauses before consequential action. Human-on-the-loop (HOTL) monitors after the fact. HITL is required for irreversible or high-stakes actions. HOTL is acceptable for low-stakes, bounded, reversible actions. The distinction must be explicit and documented. -**AI assistance must augment human capability, not replace it.** +**AI assistance must augment human capability, not replace it.** Over-reliance on AI for tasks that require and develop critical skills is a governance risk, not just a quality risk. Kosmyna et al. (2025) found measurable neural disengagement in AI-assisted work; domain evidence shows skill atrophy when AI support is removed; ACM FAccT 2026 identifies cognitive offloading as a systematically overlooked safety risk. When AI takes over a capability entirely, the human's ability to catch AI errors in that domain is also lost. Governance must include periodic assessment of whether AI-assisted roles retain the baseline capability required to operate, audit, and override the AI without it. -**AI assistance must augment human capability, not replace it.** +**AI assistance must augment human capability, not replace it.** Over-reliance on AI for tasks that require critical thinking, system comprehension, or skilled judgement creates cognitive dependency that degrades organisational resilience over time (Kosmyna et al. 2025; Chalkidis & Søgaard, ACM FAccT 2026). Governance must include mechanisms to detect skill atrophy in AI-assisted roles — periodic AI-free practice, comprehension checks, and capability baselines that do not depend on AI availability. --- ## 6. Sustainability & Societal Cost -**Governance is an obligation to those who bear the costs, not just those who use the tools.** +**Governance is an obligation to those who bear the costs, not just those who use the tools.** AI's primary costs — environmental, epistemic, and distributional — fall predominantly on people who are not its users: communities bearing grid and water stress from data centres, workers displaced faster than they can upskill, and societies absorbing the epistemic effects of large-scale AI-generated content at scale (IEA Energy and AI 2025; de Vries-Gao, ScienceDirect 2025; Chalkidis & Søgaard, ACM FAccT 2026). Those who benefit from AI use have an obligation to those who bear its costs — whether or not those costs are currently priced or legally required to be accounted for. -**Unmeasured AI usage is unjustifiable.** +**Unmeasured AI usage is unjustifiable.** Every AI integration must have defined success metrics before deployment. The environmental and societal costs are real and externally borne; they cannot be justified without evidence of value delivered. 42% of enterprises have abandoned most AI initiatives; only 5% of GenAI pilots show measurable P&L impact (S&P Global n=1,006; MIT NANDA lab). If value cannot be articulated, the costs on others cannot be defended. -**Match model capability to task complexity.** +**Match model capability to task complexity.** Using frontier models for tasks a smaller model handles is not just economically wasteful — it imposes unnecessary environmental and infrastructure costs on others. Model selection is a governance decision with externalities. -**Token efficiency is a sustainability metric, not just a cost metric.** +**Token efficiency is a sustainability metric, not just a cost metric.** Tokens per unit of value delivered simultaneously tracks cost, carbon intensity, and whether AI is doing genuine work. Per-task energy use is falling rapidly; aggregate consumption rises faster because adoption scale outpaces efficiency gains — the Jevons paradox applied to AI (IEA 2025/2026). -**Apply the J-Curve honestly.** +**Apply the J-Curve honestly.** AI deployments not yet delivering measurable value must be time-bounded. DORA 2025 confirms the J-Curve pattern: short-term costs precede long-term gains, but the curve must actually turn. If a deployment has not reached value delivery within a defined review period, it must be redesigned or discontinued. -**Treat provider sustainability claims sceptically.** +**Treat provider sustainability claims sceptically.** Corporate environmental disclosure does not currently distinguish AI from non-AI workloads; independent verification of AI-specific footprint is not possible without regulatory mandates. Source claims only from independently verifiable data (IEA, peer-reviewed studies). --- ## 7. Transparency & Auditability -**Every AI agent action that produces an effect must generate a tamper-evident, human-readable trace.** +**Every AI agent action that produces an effect must generate a tamper-evident, human-readable trace.** Minimum content: prompt input, model version, output, tool invocations, actor identity, timestamp. Isolated timestamps are not sufficient. -**Prompts are code and must be versioned accordingly.** +**Prompts are code and must be versioned accordingly.** Every prompt used in a production AI system must be under version control with change logs recording what changed, why, and who approved the change. Unversioned prompts are unauditable prompts. -**AI involvement must be disclosed to anyone affected by its outputs.** +**AI involvement must be disclosed to anyone affected by its outputs.** This is an ethical obligation regardless of jurisdiction. Under the EU AI Act (post-Omnibus May 2026 agreement): Article 50 transparency obligations apply from **December 2, 2026**, and only to providers of certain AI system types (chatbots, deepfake generators, high-risk systems) — not to deployers using coding assistants internally. Developers using tools like Copilot, Claude Code, or Cursor currently face only **Article 4 (AI literacy)** obligations, which have been live since February 2025. Consult legal counsel for jurisdiction-specific obligations. -**Logging must not create new data protection exposures.** +**Logging must not create new data protection exposures.** PII in logs must be redacted at ingestion. Log retention periods must align with data protection obligations — retain only what is necessary for the defined audit purpose. --- ## 8. Intellectual Property -**AI-generated code without meaningful human authorship is unprotectable and simultaneously liable.** +**AI-generated code without meaningful human authorship is unprotectable and simultaneously liable.** It may infringe third-party IP while being ineligible for copyright protection itself. Substantial human review, editing, and integration is required for both IP protection and licence compliance. -**Run licence-scanning on all AI-generated code before committing.** +**Run licence-scanning on all AI-generated code before committing.** Copyleft-licensed fragments can appear in AI output without licence headers. Manifest-based scanning tools do not catch AI-generated code. Dedicated licence scanning must cover AI-assisted contributions explicitly. -**Review AI provider terms of service specifically for IP provisions.** +**Review AI provider terms of service specifically for IP provisions.** Rights to AI-generated outputs vary significantly by provider and tier. Enterprise agreements must be reviewed for IP indemnification, output ownership clauses, and restrictions before using AI output in commercial software. -**Document human contributions to AI-assisted code.** +**Document human contributions to AI-assisted code.** Version control history, code review records, and prompt logs together constitute evidence of human authorship. Where IP protection matters, the human contribution must be substantive and documentable. --- ## 9. Incident Response -**Extend existing IR frameworks for AI-specific failure modes; do not replace them.** +**Extend existing IR frameworks for AI-specific failure modes; do not replace them.** NIST SP 800-61 and ISO/IEC 27035 remain the required foundation. Extend with specific playbooks covering: prompt injection attacks, agentic scope violations, AI-caused data exposure, and auditability failures. Each requires a distinct detection and response procedure. -**Design for error containment, not error prevention.** +**Design for error containment, not error prevention.** AI systems will produce erroneous outputs. The primary design obligation is to prevent errors from propagating to consequential, irreversible action — through permission envelopes, scope constraints, and HITL gates. -**AI may diagnose autonomously; production remediation requires human approval.** +**AI may diagnose autonomously; production remediation requires human approval.** AI-assisted detection and root cause analysis can run without human intervention. Applying remediation to production systems — rollback, configuration change, scaling decision — requires explicit human approval unless the action is pre-defined, bounded, and reversible. -**Post-mortems must cover AI and automation failures explicitly.** +**Post-mortems must cover AI and automation failures explicitly.** Every AI-involved incident must be post-mortemed with the same rigour as service outages. The post-mortem must address: what instructions the agent operated under, what decision it made, what the failure mode was, and what governance change prevents recurrence. -**Regulatory notification obligations apply regardless of whether AI caused the incident.** +**Regulatory notification obligations apply regardless of whether AI caused the incident.** GDPR Article 33/34 and EU AI Act incident reporting obligations are not suspended because an AI system caused or contributed to the incident. The notification timeline and threshold are unchanged. -**Test incident response for AI-specific scenarios proactively.** +**Test incident response for AI-specific scenarios proactively.** Standard chaos engineering and resilience drills must include AI-specific scenarios: prompt injection, agent scope violation, agentic hallucination triggering a downstream action. Untested playbooks do not work under pressure. --- ## 10. Deterministic Execution -**Prefer deterministic code over repeated AI inference for repeatable, well-specified tasks.** +**Prefer deterministic code over repeated AI inference for repeatable, well-specified tasks.** If a task has a correct answer that does not depend on context or judgement, encode it as a script. Use AI once to generate and review the script; run the script in production. Repeated AI inference for a deterministic task adds cost, unreliability, and attack surface without benefit. -**Use AI inference at execution time only for tasks that are genuinely ambiguous or context-dependent.** +**Use AI inference at execution time only for tasks that are genuinely ambiguous or context-dependent.** Applying probabilistic AI to deterministic problems is a documented anti-pattern. If you can draw a complete flowchart of the process with no "it depends" branches, the task does not need AI at execution time. -**AI-generated scripts are first drafts, not finished artefacts.** +**AI-generated scripts are first drafts, not finished artefacts.** Review AI-generated code for correctness, missing dependencies, and performance before production deployment. EffiBench (2024) found measurable execution overhead in unreviewed AI-generated code; human review substantially closes that gap. The review step is not optional. -**Deterministic enforcement must sit outside the AI, not inside it.** +**Deterministic enforcement must sit outside the AI, not inside it.** Linters, CI gates, unit tests, and schema validation must run on AI-generated code as hard constraints. AI instructions alone are probabilistic and cannot serve as enforcement mechanisms. -**The script is the governed artefact; version and review it accordingly.** +**The script is the governed artefact; version and review it accordingly.** When a repeatable task changes enough to invalidate the existing script, that is the trigger to re-engage AI — not a reason to revert to repeated inference. The script lives in version control, is human-reviewable, and is the authoritative record of how the task is performed. --- ## Governance -**This document is a living artifact.** +**This document is a living artifact.** It must be reviewed after any significant AI incident, at each major addition of AI tooling, and at minimum annually. Research that contradicts current principles must be incorporated. -**Principles without enforcement are claims.** +**Principles without enforcement are claims.** Each principle above must map to at least one verifiable behaviour, automated check, or documented review process. Where that mapping does not exist, the principle is aspirational — label it as such and set a deadline for operationalisation. `core/instructions/governance.md` provides the agent-actionable distillation of this document; deterministic tooling (linters, CI gates, secret scanners, licence scanners) provides the enforcement layer that agent instructions alone cannot. *Example mapping — Section 2, "Secrets must never enter AI context":* @@ -228,11 +228,11 @@ Each principle above must map to at least one verifiable behaviour, automated ch - CI gate: secret scanning step in pipeline rejects commits containing high-entropy strings - Review checklist item: confirm no secrets in prompt logs before any session transcript is stored or shared -**This constitution does not replace legal advice.** +**This constitution does not replace legal advice.** It operationalises current regulatory and research consensus for practitioners. For jurisdiction-specific obligations, regulatory filings, or IP disputes, consult qualified legal counsel. --- -*Derived from: AI Governance Research Session (May 2026).* -*Research documentation: `docs/research/governance_principles/ai-governance-research.md` | Open challenges: `docs/research/governance_principles/ai-governance-research-challenges.md`* +*Derived from: AI Governance Research Session (May 2026).* +*Research documentation: `docs/research/governance_principles/ai-governance-research.md` | Open challenges: `docs/research/governance_principles/ai-governance-research-challenges.md`* *Operative files: `core/instructions/governance.md` (agent instructions) | `docs/HUMANS.md` (human practitioner rules) | `docs/research/governance_principles/CONTROLS.md` (deterministic enforcement)* diff --git a/docs/issues/0015-agents-md-refactor.md b/docs/issues/0015-agents-md-refactor.md index aa8f7ff..e921d94 100644 --- a/docs/issues/0015-agents-md-refactor.md +++ b/docs/issues/0015-agents-md-refactor.md @@ -1,6 +1,6 @@ # 0015 — AGENTS.md refactor (prerequisite) -**Type:** HITL +**Type:** HITL **Parent PRD:** `docs/prd/chunk-3-skills-library.md` ## What to build diff --git a/docs/issues/0016-skill-workflow-grill.md b/docs/issues/0016-skill-workflow-grill.md index 225217a..0a604ec 100644 --- a/docs/issues/0016-skill-workflow-grill.md +++ b/docs/issues/0016-skill-workflow-grill.md @@ -1,6 +1,6 @@ # 0016 — Second grill: skill implementation workflow -**Type:** HITL +**Type:** HITL **Parent PRD:** `docs/prd/chunk-3-skills-library.md` ## What to build @@ -29,7 +29,7 @@ HITL: requires human participation in the grill session. ## Handoff -**Status:** complete +**Status:** complete **Files produced:** - `docs/notes/skill-implementation-workflow.md` diff --git a/docs/issues/0017-factory-write-eval.md b/docs/issues/0017-factory-write-eval.md index 9e99bf2..c6fbc3b 100644 --- a/docs/issues/0017-factory-write-eval.md +++ b/docs/issues/0017-factory-write-eval.md @@ -1,6 +1,6 @@ # 0017 — factory/write-eval (bootstrap skill) -**Type:** HITL +**Type:** HITL **Parent PRD:** `docs/prd/chunk-3-skills-library.md` ## What to build diff --git a/docs/issues/0018-factory-write-skill.md b/docs/issues/0018-factory-write-skill.md index 415179f..fad8732 100644 --- a/docs/issues/0018-factory-write-skill.md +++ b/docs/issues/0018-factory-write-skill.md @@ -1,6 +1,6 @@ # 0018 — factory/write-skill (bootstrap skill) -**Type:** HITL +**Type:** HITL **Parent PRD:** `docs/prd/chunk-3-skills-library.md` ## What to build diff --git a/docs/issues/0019-factory-skills-remaining.md b/docs/issues/0019-factory-skills-remaining.md index 6feeed1..82c956f 100644 --- a/docs/issues/0019-factory-skills-remaining.md +++ b/docs/issues/0019-factory-skills-remaining.md @@ -1,6 +1,6 @@ # 0019 — Factory skills: write-adr, write-issue-spec, write-workflow, upgrade-skill, validate-skill -**Type:** HITL +**Type:** HITL **Parent PRD:** `docs/prd/chunk-3-skills-library.md` ## What to build diff --git a/docs/issues/0020-design-skills.md b/docs/issues/0020-design-skills.md index e54a2fb..4763fdf 100644 --- a/docs/issues/0020-design-skills.md +++ b/docs/issues/0020-design-skills.md @@ -1,6 +1,6 @@ # 0020 — Design skills: grill-lean, grill-me, write-prd, architecture-review, break-into-issues, prototype -**Type:** HITL +**Type:** HITL **Parent PRD:** `docs/prd/chunk-3-skills-library.md` ## What to build diff --git a/docs/issues/0021-implement-skills.md b/docs/issues/0021-implement-skills.md index 70baaec..7e63066 100644 --- a/docs/issues/0021-implement-skills.md +++ b/docs/issues/0021-implement-skills.md @@ -1,6 +1,6 @@ # 0021 — Implement skills: implement-feature, tdd, refactor, diagnose -**Type:** HITL +**Type:** HITL **Parent PRD:** `docs/prd/chunk-3-skills-library.md` ## What to build diff --git a/docs/issues/0022-test-skills.md b/docs/issues/0022-test-skills.md index fbc4191..27a3500 100644 --- a/docs/issues/0022-test-skills.md +++ b/docs/issues/0022-test-skills.md @@ -1,6 +1,6 @@ # 0022 — Test skills: write-tests, generate-test-data, review-test-coverage -**Type:** HITL +**Type:** HITL **Parent PRD:** `docs/prd/chunk-3-skills-library.md` ## What to build diff --git a/docs/issues/0023-review-skills.md b/docs/issues/0023-review-skills.md index ce84a41..9b32e86 100644 --- a/docs/issues/0023-review-skills.md +++ b/docs/issues/0023-review-skills.md @@ -1,6 +1,6 @@ # 0023 — Review skills + cliff.toml: code-review, security-review, pr-description, changelog-entry -**Type:** HITL +**Type:** HITL **Parent PRD:** `docs/prd/chunk-3-skills-library.md` ## What to build diff --git a/docs/issues/0024-deploy-skills.md b/docs/issues/0024-deploy-skills.md index f4b707b..fdbd8d5 100644 --- a/docs/issues/0024-deploy-skills.md +++ b/docs/issues/0024-deploy-skills.md @@ -1,6 +1,6 @@ # 0024 — Deploy skills: write-ci-pipeline, write-deployment-config, write-ai-review-workflow, deployment-checklist -**Type:** HITL +**Type:** HITL **Parent PRD:** `docs/prd/chunk-3-skills-library.md` ## What to build diff --git a/docs/issues/0025-operate-skills.md b/docs/issues/0025-operate-skills.md index 0b12f94..68a263a 100644 --- a/docs/issues/0025-operate-skills.md +++ b/docs/issues/0025-operate-skills.md @@ -1,6 +1,6 @@ # 0025 — Operate skills: write-runbook, incident-diagnosis, post-mortem, inspect-deployment -**Type:** HITL +**Type:** HITL **Parent PRD:** `docs/prd/chunk-3-skills-library.md` ## What to build diff --git a/docs/issues/0026-iac-skills.md b/docs/issues/0026-iac-skills.md index 294a545..f282173 100644 --- a/docs/issues/0026-iac-skills.md +++ b/docs/issues/0026-iac-skills.md @@ -1,6 +1,6 @@ # 0026 — IaC skills: write-docker-compose, iac-security-review -**Type:** HITL +**Type:** HITL **Parent PRD:** `docs/prd/chunk-3-skills-library.md` ## What to build diff --git a/docs/issues/0027-cross-cutting-skills.md b/docs/issues/0027-cross-cutting-skills.md index 717a898..21e0a0a 100644 --- a/docs/issues/0027-cross-cutting-skills.md +++ b/docs/issues/0027-cross-cutting-skills.md @@ -1,6 +1,6 @@ # 0027 — Cross-cutting skills: session-handoff, governance-check, git-commit-message, improve-codebase-architecture, triage, zoom-out, caveman -**Type:** HITL +**Type:** HITL **Parent PRD:** `docs/prd/chunk-3-skills-library.md` ## What to build diff --git a/docs/issues/0028-chunk-3-closure.md b/docs/issues/0028-chunk-3-closure.md index 3092937..dfd4c5d 100644 --- a/docs/issues/0028-chunk-3-closure.md +++ b/docs/issues/0028-chunk-3-closure.md @@ -1,6 +1,6 @@ # 0028 — Chunk 3 closure: update skills-index, update spec, behavioral tests -**Type:** HITL +**Type:** HITL **Parent PRD:** `docs/prd/chunk-3-skills-library.md` ## What to build diff --git a/docs/notes/factory-research-gaps-conflicts.md b/docs/notes/factory-research-gaps-conflicts.md index a5c8883..9a61fb5 100644 --- a/docs/notes/factory-research-gaps-conflicts.md +++ b/docs/notes/factory-research-gaps-conflicts.md @@ -20,21 +20,21 @@ This changes almost every downstream decision. Until it's resolved, individual g ### 2.1 Where coding conventions live -**Factory research:** Preferred/Avoid code blocks belong in `CONTEXT.md`. Convention lives in a single shared-vocabulary file the agent always loads. +**Factory research:** Preferred/Avoid code blocks belong in `CONTEXT.md`. Convention lives in a single shared-vocabulary file the agent always loads. **Chunk 2 plan:** Coding conventions go in a separate `core/instructions/coding.md` file, loaded on-demand. One of these wins. If conventions go in `CONTEXT.md`, `coding.md` becomes much thinner or unnecessary. If they stay in `coding.md`, the factory's "CONTEXT.md is the primary context artefact" principle weakens. ### 2.2 Skill path structure: flat vs. nested -**Factory research:** 34 skills in 9 nested categories — `design/grill-me/SKILL.md`, `implement/tdd/SKILL.md`, `cross-cutting/session-handoff/SKILL.md`, etc. (phase × domain matrix) +**Factory research:** 34 skills in 9 nested categories — `design/grill-me/SKILL.md`, `implement/tdd/SKILL.md`, `cross-cutting/session-handoff/SKILL.md`, etc. (phase × domain matrix) **Current state:** 12 skills in a flat structure — `grill-me/SKILL.md`, `tdd/SKILL.md`, etc. Changing to nested paths breaks any tool that discovers skills by path. The nested structure also implies a different deployment model from `install.sh`. This is a structural decision for Chunk 3 — if we're adopting the nested taxonomy, it needs to be decided before writing any more skill files. ### 2.3 Governance file naming -**Factory research:** `AGENTS.md` at repo root as the single governance file for agents. +**Factory research:** `AGENTS.md` at repo root as the single governance file for agents. **Current repo:** `core/instructions/governance.md` loaded via `@import` in `providers/claude-code/CLAUDE.md`. These serve the same purpose. The factory's naming is cleaner (one file, obvious name), but the current structure fits the provider-agnostic model (governance isn't provider-specific). Not a blocking conflict, but naming inconsistency will cause confusion in grill sessions if not resolved. diff --git a/docs/notes/skill-implementation-workflow.md b/docs/notes/skill-implementation-workflow.md index 48b522b..4fc93d9 100644 --- a/docs/notes/skill-implementation-workflow.md +++ b/docs/notes/skill-implementation-workflow.md @@ -1,6 +1,6 @@ # Skill Implementation Workflow -**Produced by:** issue 0016 grill session, 2026-05-17 +**Produced by:** issue 0016 grill session, 2026-05-17 **Applies to:** all Chunk 3 skill issues (0017–0028) --- @@ -84,7 +84,7 @@ This is not a full grill-with-docs session — it is focused and bounded. If the Work through the following in order, iterating with the human. Sub-agents handle writing tasks where context accumulation is a risk. -**a. Trigger description** +**a. Trigger description** Write the `description:` frontmatter field first. Test it against three cases before writing the body: 1. Explicit invocation — user says the trigger phrase directly 2. Implicit invocation — user describes the task without the trigger phrase @@ -92,7 +92,7 @@ Write the `description:` frontmatter field first. Test it against three cases be For each case, output an explicit **PASS** or **FAIL** result. Do not proceed to step b until all three show PASS. Including the description inside the section walk-through (step b) does not satisfy this gate — it must be a standalone test-then-proceed step with per-case verdicts. If any case fails, revise the description and re-test before continuing. -**b. Per-section options walk-through** +**b. Per-section options walk-through** Before writing anything, walk through each body section with the human. For each section: - State what content is proposed and which upstream source it comes from - Present alternatives where upstream sources offered different approaches @@ -100,24 +100,24 @@ Before writing anything, walk through each body section with the human. For each Do not write the SKILL.md until the human has confirmed every section. The synthesis grill decisions cover the eval schema and gating questions; this step covers how upstream content maps to each SKILL.md section. These are separate conversations — do not collapse them. -**c. SKILL.md** (sub-agent) +**c. SKILL.md** (sub-agent) Once all sections are confirmed, spawn a write agent to produce the SKILL.md using `write-skill` (or hand-write for bootstrap skills). The agent receives: trigger description, per-section decisions from step b, upstream content to incorporate, authoring standard (see below). -**c. META.md — `source:` and `references:` fields** +**c. META.md — `source:` and `references:` fields** Populate `META.md` after upstream review. Two distinct fields: - `source:` — upstream provenance tracking (repo slug, commit SHA, files adopted with inline comments, updated date). Present only if content was adopted. Absence = self-authored. - `references:` — general citations (research papers, documentation, standard specifications). Present only if the skill cites external research. Both fields live in `META.md` alongside the SKILL.md — not in frontmatter. See `META-TEMPLATE.md` in `.agents/skills/write-skill/` for the full schema. -**d. eval.yaml** (sub-agent) +**d. eval.yaml** (sub-agent) Invoke `write-eval` in two steps to preserve its confirmation gate: 1. Sub-agent proposes test cases and returns the plan to the main conversation. 2. Human confirms the plan; then sub-agent writes the file. Do not pass pre-designed test cases directly to a write agent — that collapses the plan-then-confirm gate into a single step, bypassing write-eval's own constraint. Co-located at `.agents/evals///eval.yaml`. Must contain all five required test types (see Eval schema below). -**e. HITL behavioral test** +**e. HITL behavioral test** Human opens a fresh Claude session, invokes the skill with its trigger phrase, and verifies output. Do not batch more than 2–3 skills before running behavioral tests — output volume must stay within genuine human review capacity. An approval that cannot be meaningfully evaluated is not an approval. ### Step 6 — Session handoff @@ -127,7 +127,7 @@ After the behavioral test passes, close the skill session by appending a `## Han ```markdown ## Handoff -**Status:** complete +**Status:** complete **Files produced:** - `.agents/skills//SKILL.md` - `.agents/evals///eval.yaml` @@ -193,7 +193,7 @@ When refactoring an existing Pocock placeholder skill: ## Eval schema -**Location:** `.agents/evals///eval.yaml` — committed to the repo. +**Location:** `.agents/evals///eval.yaml` — committed to the repo. **Enforcement:** CI gates are Chunk 6. The files document expected behaviour before then. Every eval must contain all five required test types: diff --git a/docs/prd/chunk-3-skills-library.md b/docs/prd/chunk-3-skills-library.md index 060b441..c70db03 100644 --- a/docs/prd/chunk-3-skills-library.md +++ b/docs/prd/chunk-3-skills-library.md @@ -1,7 +1,7 @@ # PRD: Chunk 3 — Skills Library Rebuild -**Status:** In progress — 0015 ✅, 0016 ✅ -**Produced by:** grill-with-docs session, 2026-05-17 +**Status:** In progress — 0015 ✅, 0016 ✅ +**Produced by:** grill-with-docs session, 2026-05-17 **Prerequisite:** AGENTS.md refactor issue must be completed before skill implementation begins --- diff --git a/docs/prd/governance-instruction-layer.md b/docs/prd/governance-instruction-layer.md index 11f7fe7..25eb5d5 100644 --- a/docs/prd/governance-instruction-layer.md +++ b/docs/prd/governance-instruction-layer.md @@ -1,8 +1,8 @@ # PRD: Governance Instruction Layer (Phase 1) -**Workstream:** Governance (parallel, not a numbered chunk) -**Phase:** 1 of 2 — instruction and documentation layer -**Must complete before:** Chunk 3 +**Workstream:** Governance (parallel, not a numbered chunk) +**Phase:** 1 of 2 — instruction and documentation layer +**Must complete before:** Chunk 3 **Phase 2 spec:** `docs/research/governance_principles/CONTROLS.md` — deferred to Chunk 6 --- diff --git a/docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md b/docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md index 0089be3..9064a25 100644 --- a/docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md +++ b/docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md @@ -1,9 +1,9 @@ # AI Coding Factory — Implementation Guidance -**Version:** 1.2 -**Date:** May 2026 -**Status:** Guidance — not yet adapted to repo vision, roadmap, or ADRs -**Audience:** Human implementing the factory; Claude Code executing against it +**Version:** 1.2 +**Date:** May 2026 +**Status:** Guidance — not yet adapted to repo vision, roadmap, or ADRs +**Audience:** Human implementing the factory; Claude Code executing against it **Prerequisite reading:** `ai-coding-factory-principles.md`, `ai-coding-factory-research.md`, `ai-coding-factory-skills-index.md` > **Important:** This document is research-derived implementation guidance, not a finalised plan. It must be reconciled with the repo's actual vision and roadmap (to be established via grill-me sessions in Claude Code) before implementation begins. Where this guidance conflicts with those outputs, the grill-me session outputs win. ADRs produced in Claude Code are the authoritative implementation decisions; this document provides the evidence base and recommendations that inform them. @@ -698,15 +698,14 @@ The intended final state: every concrete recommendation in this document either ``` /grill-me -Context: I'm building an AI coding factory — a governed, AI-assisted development environment -implemented as committed files in a repo. I have completed research and implementation +Context: I'm building an AI coding factory — a governed, AI-assisted development environment +implemented as committed files in a repo. I have completed research and implementation guidance (loaded in context). I need to establish [session topic] before building. -Grill me until every decision is explicit. Do not let me proceed with vague answers. +Grill me until every decision is explicit. Do not let me proceed with vague answers. Output: a structured decision record suitable for converting to an ADR. ``` --- *This is a living guidance document. Update it as grill-me sessions produce decisions. When an ADR supersedes a recommendation, mark the section with `> Superseded by ADR-NNN` and link the ADR. Version in git alongside the rest of the factory.* - diff --git a/docs/research/governance_principles/CONTROLS.md b/docs/research/governance_principles/CONTROLS.md index 02e04c8..a5c14ec 100644 --- a/docs/research/governance_principles/CONTROLS.md +++ b/docs/research/governance_principles/CONTROLS.md @@ -1,8 +1,8 @@ # Deterministic Controls -Applies to: any environment, repository, or pipeline where AI tools are used. -Full governance context: `docs/ai-constitution.md` — principles these controls enforce. -Human practitioner rules: `docs/HUMANS.md` | Agent instructions: `core/instructions/governance.md` +Applies to: any environment, repository, or pipeline where AI tools are used. +Full governance context: `docs/ai-constitution.md` — principles these controls enforce. +Human practitioner rules: `docs/HUMANS.md` | Agent instructions: `core/instructions/governance.md` This file specifies the enforcement layer: controls that run mechanically, regardless of human or agent intention. **Why this file exists:** Agent instructions and human practitioner rules are probabilistic — they depend on attention and intent. This layer removes that dependency. A control that runs automatically in CI enforces a principle more reliably than any instruction in any file. Where a principle can be enforced deterministically, it must be. @@ -15,16 +15,16 @@ Controls configured once per development environment. Any machine or environment --- -**Secret scanning in pre-commit** -A pre-commit hook that detects secrets, credentials, API keys, and high-entropy strings must be active in every development environment. It must run before any commit reaches version control — not as a best-effort scan, but as a blocking gate. +**Secret scanning in pre-commit** +A pre-commit hook that detects secrets, credentials, API keys, and high-entropy strings must be active in every development environment. It must run before any commit reaches version control — not as a best-effort scan, but as a blocking gate. *Enforces: Constitution §2 — secrets never enter AI context or version control.* -**AI tool data tier verification** -AI tools used for Internal, Confidential, or Restricted data must be configured to use enterprise-tier endpoints. Verify contractual data-not-trained commitments are in place before connecting any non-Public data source to an AI tool. This is a one-time verification per tool, repeated when tools or plans change. +**AI tool data tier verification** +AI tools used for Internal, Confidential, or Restricted data must be configured to use enterprise-tier endpoints. Verify contractual data-not-trained commitments are in place before connecting any non-Public data source to an AI tool. This is a one-time verification per tool, repeated when tools or plans change. *Enforces: Constitution §3 — consumer and free-tier products handle Public data only.* -**Governance instruction file present and adapter files configured** -Every repository or project context in active use must have an agent governance instruction file present and accessible (in this repo: `core/instructions/governance.md`, deployed globally via `@import`), with tool-specific adapter files (CLAUDE.md, copilot-instructions.md, etc.) referencing it. Verify this is in place before starting AI-assisted work in any new repo. +**Governance instruction file present and adapter files configured** +Every repository or project context in active use must have an agent governance instruction file present and accessible (in this repo: `core/instructions/governance.md`, deployed globally via `@import`), with tool-specific adapter files (CLAUDE.md, copilot-instructions.md, etc.) referencing it. Verify this is in place before starting AI-assisted work in any new repo. *Enforces: Constitution §1 — governance rules must reach the agents operating in context.* --- @@ -35,32 +35,32 @@ Controls configured for each repository. Apply these when creating a new repo or --- -**Secret scanning in CI** -Every repository CI pipeline must include a secret scanning step that fails the build on detected credentials, tokens, or high-entropy strings. Pre-commit hooks can be bypassed; CI cannot. Both layers are required. +**Secret scanning in CI** +Every repository CI pipeline must include a secret scanning step that fails the build on detected credentials, tokens, or high-entropy strings. Pre-commit hooks can be bypassed; CI cannot. Both layers are required. *Enforces: Constitution §2 — architectural constraint, not a reminder.* -**Dependency and security scanning** -Every repository CI pipeline must include dependency vulnerability scanning covering known CVEs and supply chain risks. For repositories using AI-generated code, the scan must be configured to cover AI-assisted contributions — not just declared dependencies. +**Dependency and security scanning** +Every repository CI pipeline must include dependency vulnerability scanning covering known CVEs and supply chain risks. For repositories using AI-generated code, the scan must be configured to cover AI-assisted contributions — not just declared dependencies. *Enforces: Constitution §2 — AI-generated code is untrusted by default; OWASP LLM supply chain risks.* -**Licence scanning** -Every repository CI pipeline must include a licence scanning step that detects copyleft-licensed fragments (GPL, AGPL, LGPL) in committed code. Manifest-based scanners alone are insufficient for AI-assisted contributions — the scan must cover code content, not just declared dependencies. +**Licence scanning** +Every repository CI pipeline must include a licence scanning step that detects copyleft-licensed fragments (GPL, AGPL, LGPL) in committed code. Manifest-based scanners alone are insufficient for AI-assisted contributions — the scan must cover code content, not just declared dependencies. *Enforces: Constitution §8 — copyleft fragments can appear in AI output without headers.* -**AI agent permission scoping** -Any AI agent granted access to this repository must be configured with the minimum permissions required for its specific task. Broad-scope tokens granting read/write access to the full repository or infrastructure are prohibited for AI agents. Token scope must be documented and reviewed when the agent's task scope changes. +**AI agent permission scoping** +Any AI agent granted access to this repository must be configured with the minimum permissions required for its specific task. Broad-scope tokens granting read/write access to the full repository or infrastructure are prohibited for AI agents. Token scope must be documented and reviewed when the agent's task scope changes. *Enforces: Constitution §2 — least-privilege for all AI agents.* -**Prompt version control** -Any prompt used in an automated or recurring AI pipeline — not ad-hoc sessions — must be committed to version control with a change history. Prompts not under version control are not auditable. A prompt that runs in production without version control is uncontrolled code. +**Prompt version control** +Any prompt used in an automated or recurring AI pipeline — not ad-hoc sessions — must be committed to version control with a change history. Prompts not under version control are not auditable. A prompt that runs in production without version control is uncontrolled code. *Enforces: Constitution §7 — prompts are code; unversioned prompts are unauditable.* -**Audit logging for agentic workflows** -Any agentic workflow that modifies state — files, infrastructure, configuration, deployments — must produce a log capturing: prompt input (or reference to versioned prompt), model version, action taken, outcome, timestamp. The log must be tamper-evident and human-readable. Isolated timestamps without action context are not sufficient. +**Audit logging for agentic workflows** +Any agentic workflow that modifies state — files, infrastructure, configuration, deployments — must produce a log capturing: prompt input (or reference to versioned prompt), model version, action taken, outcome, timestamp. The log must be tamper-evident and human-readable. Isolated timestamps without action context are not sufficient. *Enforces: Constitution §7 — every agent action producing an effect must generate a trace.* -**Human approval gate for production changes** -Any CI/CD pipeline that applies changes to production systems, security configuration, or infrastructure must include an explicit human approval step before the change is applied. Automated merge-and-deploy pipelines for AI-generated changes are prohibited without this gate. The gate must be implemented in the pipeline, not left to individual judgment. +**Human approval gate for production changes** +Any CI/CD pipeline that applies changes to production systems, security configuration, or infrastructure must include an explicit human approval step before the change is applied. Automated merge-and-deploy pipelines for AI-generated changes are prohibited without this gate. The gate must be implemented in the pipeline, not left to individual judgment. *Enforces: Constitution §5 — production requires a human checkpoint; this is a hard rule.* --- @@ -71,25 +71,25 @@ Controls that must be verified periodically. These cannot be configured once and --- -**Pre-commit hook integrity** *(per developer, monthly)* +**Pre-commit hook integrity** *(per developer, monthly)* Verify pre-commit hooks are installed, active, and current in every active development environment. Hooks can be bypassed, uninstalled by tooling updates, or silently disabled. A hook that is not tested is not a control. -**CI scan results review** *(per repository, per release or sprint)* +**CI scan results review** *(per repository, per release or sprint)* Review secret, licence, and dependency scan outputs — not just pass/fail status. A scan that passes because exceptions have accumulated is not a clean scan. Review exception lists and remove expired or unjustified exceptions. -**AI agent permission audit** *(per repository, quarterly)* +**AI agent permission audit** *(per repository, quarterly)* Verify that AI agent tokens and permissions remain scoped to current task requirements. Agent permissions granted for a specific task tend to persist after the task ends. Revoke and re-scope on a defined cadence. -**Audit log review** *(per agentic workflow, per sprint or monthly)* +**Audit log review** *(per agentic workflow, per sprint or monthly)* Review AI agent action logs for unexpected scope, anomalous patterns, or actions that should have triggered a human approval gate but did not. Logging without review is record-keeping, not oversight. -**AI deployment value review** *(per deployment, time-bounded)* +**AI deployment value review** *(per deployment, time-bounded)* Every AI integration must be reviewed against the success criteria defined before deployment. Integrations that have not delivered measurable value within the defined review period must be redesigned or discontinued. Schedule this review at deployment time, not retrospectively. -**Provider terms and data handling review** *(annually, or when providers update terms)* +**Provider terms and data handling review** *(annually, or when providers update terms)* Verify that AI provider terms of service, data handling commitments, and IP provisions remain consistent with what was agreed at onboarding. Provider terms change. An enterprise commitment made in 2024 may not have the same scope in 2026. Re-verify; do not assume continuity. -**Constitution and controls alignment review** *(annually, or after any significant AI incident)* +**Constitution and controls alignment review** *(annually, or after any significant AI incident)* Verify that the controls specified here remain aligned with the current version of the AI Constitution. When the constitution is updated, this file must be reviewed and updated to match. A control specification that drifts from the constitution it enforces is not a control. --- @@ -102,5 +102,5 @@ Human judgment decisions — which AI model to use, whether a specific output is --- -*Derived from AI Constitution v1.1 — May 2026.* +*Derived from AI Constitution v1.1 — May 2026.* *Counterpart to: `docs/HUMANS.md` | `core/instructions/governance.md` | Full context: `docs/ai-constitution.md`* diff --git a/docs/research/governance_principles/ai-governance-research-session.md b/docs/research/governance_principles/ai-governance-research-session.md index a2174ca..7db299d 100644 --- a/docs/research/governance_principles/ai-governance-research-session.md +++ b/docs/research/governance_principles/ai-governance-research-session.md @@ -2,8 +2,8 @@ **Purpose:** Auditability of the artifact creation process. Documents what was done, how, why, and what decisions were made or deferred. Not a task list — a process record. -**Project:** AI governance research and artifact creation for a software development, deployment, and infrastructure management context. -**Sessions:** Three sessions, May 2026. +**Project:** AI governance research and artifact creation for a software development, deployment, and infrastructure management context. +**Sessions:** Three sessions, May 2026. **Artifacts produced:** See artifact registry below. --- @@ -28,8 +28,8 @@ The work was deliberately sequenced: research first, then distil into operative Each topic in the research document follows: question being researched → findings → counterarguments and challenges → bias flag → provisional principles. ### Distillation logic -Research document = full sourced reasoning (human reference, never in agent context). -Constitution = concise principles derived from research (agent-readable, repo artifact). +Research document = full sourced reasoning (human reference, never in agent context). +Constitution = concise principles derived from research (agent-readable, repo artifact). AGENTS.md = agent-actionable subset of the constitution, optimised for context window efficiency. ### Standing integrity caveat diff --git a/docs/research/governance_principles/ai-governance-research.md b/docs/research/governance_principles/ai-governance-research.md index 006b6e2..c93e678 100644 --- a/docs/research/governance_principles/ai-governance-research.md +++ b/docs/research/governance_principles/ai-governance-research.md @@ -4,7 +4,7 @@ **How to use this document:** This is the research layer, not the operative layer. If you want to know *what to do*, read `ai-constitution.md`. If you want to know *why a principle exists*, challenge a finding, or update the evidence base, read the relevant topic here. Each topic ends with provisional principles that map directly to a constitution section — cross-references are noted. -**Session:** May 2026 +**Session:** May 2026 **Methodology:** Topic-by-topic web research from reliable sources. All conclusions are provisional and challengeable. Research must remain unbiased — findings drive principles, not the other way around. --- diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..df9193a --- /dev/null +++ b/package-lock.json @@ -0,0 +1,853 @@ +{ + "name": "ai-development", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "devDependencies": { + "markdownlint": "^0.41.0" + } + }, + "node_modules/@types/debug": { + "version": "4.1.13", + "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.13.tgz", + "integrity": "sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/ms": "*" + } + }, + "node_modules/@types/katex": { + "version": "0.16.8", + "resolved": "https://registry.npmjs.org/@types/katex/-/katex-0.16.8.tgz", + "integrity": "sha512-trgaNyfU+Xh2Tc+ABIb44a5AYUpicB3uwirOioeOkNPPbmgRNtcWyDeeFRzjPZENO9Vq8gvVqfhaaXWLlevVwg==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/ms": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/@types/ms/-/ms-2.1.0.tgz", + "integrity": "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/unist": { + "version": "2.0.11", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz", + "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==", + "dev": true, + "license": "MIT" + }, + "node_modules/ansi-regex": { + "version": "6.2.2", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.2.tgz", + "integrity": "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-regex?sponsor=1" + } + }, + "node_modules/character-entities": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/character-entities/-/character-entities-2.0.2.tgz", + "integrity": "sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-entities-legacy": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/character-entities-legacy/-/character-entities-legacy-3.0.0.tgz", + "integrity": "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-reference-invalid": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/character-reference-invalid/-/character-reference-invalid-2.0.1.tgz", + "integrity": "sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/commander": { + "version": "8.3.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-8.3.0.tgz", + "integrity": "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 12" + } + }, + "node_modules/debug": { + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", + "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", + "dev": true, + "license": "MIT", + "dependencies": { + "ms": "^2.1.3" + }, + "engines": { + "node": ">=6.0" + }, + "peerDependenciesMeta": { + "supports-color": { + "optional": true + } + } + }, + "node_modules/decode-named-character-reference": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/decode-named-character-reference/-/decode-named-character-reference-1.3.0.tgz", + "integrity": "sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "character-entities": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/dequal": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz", + "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/devlop": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/devlop/-/devlop-1.1.0.tgz", + "integrity": "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==", + "dev": true, + "license": "MIT", + "dependencies": { + "dequal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/get-east-asian-width": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.6.0.tgz", + "integrity": "sha512-QRbvDIbx6YklUe6RxeTeleMR0yv3cYH6PsPZHcnVn7xv7zO1BHN8r0XETu8n6Ye3Q+ahtSarc3WgtNWmehIBfA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/is-alphabetical": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-alphabetical/-/is-alphabetical-2.0.1.tgz", + "integrity": "sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-alphanumerical": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-alphanumerical/-/is-alphanumerical-2.0.1.tgz", + "integrity": "sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-alphabetical": "^2.0.0", + "is-decimal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-decimal": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-decimal/-/is-decimal-2.0.1.tgz", + "integrity": "sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-hexadecimal": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-hexadecimal/-/is-hexadecimal-2.0.1.tgz", + "integrity": "sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/katex": { + "version": "0.16.47", + "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.47.tgz", + "integrity": "sha512-Eeo8Ys1doU1z+x8AZsPpQu+p/QcZBI5PeOo7QGQdy2x2m0MU/hYagBbGOmXwr5KVbEfVuWv9LpnQWeehogurjg==", + "dev": true, + "funding": [ + "https://opencollective.com/katex", + "https://github.com/sponsors/katex" + ], + "license": "MIT", + "dependencies": { + "commander": "^8.3.0" + }, + "bin": { + "katex": "cli.js" + } + }, + "node_modules/markdownlint": { + "version": "0.41.0", + "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.41.0.tgz", + "integrity": "sha512-xMUI3ChBuRuxuLF4ENvCZyS8z/+Jly1coUcZwErKLIB3sDj7ojpaTBa1e9YVPhSN4jGEIjYGQCldbTJS/hqS+A==", + "dev": true, + "license": "MIT", + "dependencies": { + "micromark": "4.0.2", + "micromark-core-commonmark": "2.0.3", + "micromark-extension-directive": "4.0.0", + "micromark-extension-gfm-autolink-literal": "2.1.0", + "micromark-extension-gfm-footnote": "2.1.0", + "micromark-extension-gfm-table": "2.1.1", + "micromark-extension-math": "3.1.0", + "micromark-util-types": "2.0.2", + "string-width": "8.2.1" + }, + "engines": { + "node": ">=22" + }, + "funding": { + "url": "https://github.com/sponsors/DavidAnson" + } + }, + "node_modules/micromark": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/micromark/-/micromark-4.0.2.tgz", + "integrity": "sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/debug": "^4.0.0", + "debug": "^4.0.0", + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "micromark-core-commonmark": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-combine-extensions": "^2.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-encode": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "micromark-util-subtokenize": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-core-commonmark": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/micromark-core-commonmark/-/micromark-core-commonmark-2.0.3.tgz", + "integrity": "sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "micromark-factory-destination": "^2.0.0", + "micromark-factory-label": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-factory-title": "^2.0.0", + "micromark-factory-whitespace": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-classify-character": "^2.0.0", + "micromark-util-html-tag-name": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-subtokenize": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-extension-directive": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-directive/-/micromark-extension-directive-4.0.0.tgz", + "integrity": "sha512-/C2nqVmXXmiseSSuCdItCMho7ybwwop6RrrRPk0KbOHW21JKoCldC+8rFOaundDoRBUWBnJJcxeA/Kvi34WQXg==", + "dev": true, + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-factory-whitespace": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "parse-entities": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-autolink-literal": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-autolink-literal/-/micromark-extension-gfm-autolink-literal-2.1.0.tgz", + "integrity": "sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==", + "dev": true, + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-footnote": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-footnote/-/micromark-extension-gfm-footnote-2.1.0.tgz", + "integrity": "sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==", + "dev": true, + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-core-commonmark": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-table": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-table/-/micromark-extension-gfm-table-2.1.1.tgz", + "integrity": "sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==", + "dev": true, + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-math": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-math/-/micromark-extension-math-3.1.0.tgz", + "integrity": "sha512-lvEqd+fHjATVs+2v/8kg9i5Q0AP2k85H0WUOwpIVvUML8BapsMvh1XAogmQjOCsLpoKRCVQqEkQBB3NhVBcsOg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/katex": "^0.16.0", + "devlop": "^1.0.0", + "katex": "^0.16.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-factory-destination": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-destination/-/micromark-factory-destination-2.0.1.tgz", + "integrity": "sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-label": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-label/-/micromark-factory-label-2.0.1.tgz", + "integrity": "sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-space": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-space/-/micromark-factory-space-2.0.1.tgz", + "integrity": "sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-title": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-title/-/micromark-factory-title-2.0.1.tgz", + "integrity": "sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-whitespace": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-whitespace/-/micromark-factory-whitespace-2.0.1.tgz", + "integrity": "sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-character": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/micromark-util-character/-/micromark-util-character-2.1.1.tgz", + "integrity": "sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-chunked": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-chunked/-/micromark-util-chunked-2.0.1.tgz", + "integrity": "sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-classify-character": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-classify-character/-/micromark-util-classify-character-2.0.1.tgz", + "integrity": "sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-combine-extensions": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-combine-extensions/-/micromark-util-combine-extensions-2.0.1.tgz", + "integrity": "sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-chunked": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-decode-numeric-character-reference": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/micromark-util-decode-numeric-character-reference/-/micromark-util-decode-numeric-character-reference-2.0.2.tgz", + "integrity": "sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-encode": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-encode/-/micromark-util-encode-2.0.1.tgz", + "integrity": "sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-html-tag-name": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-html-tag-name/-/micromark-util-html-tag-name-2.0.1.tgz", + "integrity": "sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-normalize-identifier": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-normalize-identifier/-/micromark-util-normalize-identifier-2.0.1.tgz", + "integrity": "sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-resolve-all": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-resolve-all/-/micromark-util-resolve-all-2.0.1.tgz", + "integrity": "sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-sanitize-uri": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-sanitize-uri/-/micromark-util-sanitize-uri-2.0.1.tgz", + "integrity": "sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-encode": "^2.0.0", + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-subtokenize": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-subtokenize/-/micromark-util-subtokenize-2.1.0.tgz", + "integrity": "sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-symbol": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-symbol/-/micromark-util-symbol-2.0.1.tgz", + "integrity": "sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-types": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/micromark-util-types/-/micromark-util-types-2.0.2.tgz", + "integrity": "sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "dev": true, + "license": "MIT" + }, + "node_modules/parse-entities": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/parse-entities/-/parse-entities-4.0.2.tgz", + "integrity": "sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0", + "character-entities-legacy": "^3.0.0", + "character-reference-invalid": "^2.0.0", + "decode-named-character-reference": "^1.0.0", + "is-alphanumerical": "^2.0.0", + "is-decimal": "^2.0.0", + "is-hexadecimal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/string-width": { + "version": "8.2.1", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-8.2.1.tgz", + "integrity": "sha512-IIaP0g3iy9Cyy18w3M9YcaDudujEAVHKt3a3QJg1+sr/oX96TbaGUubG0hJyCjCBThFH+tFpcIyoUHUn1ogaLA==", + "dev": true, + "license": "MIT", + "dependencies": { + "get-east-asian-width": "^1.5.0", + "strip-ansi": "^7.1.2" + }, + "engines": { + "node": ">=20" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/strip-ansi": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.2.0.tgz", + "integrity": "sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-regex": "^6.2.2" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/strip-ansi?sponsor=1" + } + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..294d3b1 --- /dev/null +++ b/package.json @@ -0,0 +1,5 @@ +{ + "devDependencies": { + "markdownlint": "^0.41.0" + } +} diff --git a/plugins/kyberforge/docs/research/examples/skill-write/skill-creator/LICENSE.txt b/plugins/kyberforge/docs/research/examples/skill-write/skill-creator/LICENSE.txt index 4f881c5..aba33d7 100644 --- a/plugins/kyberforge/docs/research/examples/skill-write/skill-creator/LICENSE.txt +++ b/plugins/kyberforge/docs/research/examples/skill-write/skill-creator/LICENSE.txt @@ -199,4 +199,4 @@ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and - limitations under the License. \ No newline at end of file + limitations under the License. diff --git a/plugins/kyberforge/docs/research/examples/skill-write/skill-creator/scripts/improve_description.py b/plugins/kyberforge/docs/research/examples/skill-write/skill-creator/scripts/improve_description.py index 06bcec7..9a3ad7e 100644 --- a/plugins/kyberforge/docs/research/examples/skill-write/skill-creator/scripts/improve_description.py +++ b/plugins/kyberforge/docs/research/examples/skill-write/skill-creator/scripts/improve_description.py @@ -137,7 +137,7 @@ Here are some tips that we've found to work well in writing these descriptions: - The description competes with other skills for Claude's attention — make it distinctive and immediately recognizable. - If you're getting lots of failures after repeated attempts, change things up. Try different sentence structures or wordings. -I'd encourage you to be creative and mix up the style in different iterations since you'll have multiple opportunities to try different approaches and we'll just grab the highest-scoring one at the end. +I'd encourage you to be creative and mix up the style in different iterations since you'll have multiple opportunities to try different approaches and we'll just grab the highest-scoring one at the end. Please respond with only the new description text in tags, nothing else.""" diff --git a/plugins/kyberforge/docs/research/examples/skill-write/skill-creator/scripts/quick_validate.py b/plugins/kyberforge/docs/research/examples/skill-write/skill-creator/scripts/quick_validate.py index ed8e1dd..54f682c 100644 --- a/plugins/kyberforge/docs/research/examples/skill-write/skill-creator/scripts/quick_validate.py +++ b/plugins/kyberforge/docs/research/examples/skill-write/skill-creator/scripts/quick_validate.py @@ -97,7 +97,7 @@ if __name__ == "__main__": if len(sys.argv) != 2: print("Usage: python quick_validate.py ") sys.exit(1) - + valid, message = validate_skill(sys.argv[1]) print(message) - sys.exit(0 if valid else 1) \ No newline at end of file + sys.exit(0 if valid else 1) diff --git a/plugins/kyberforge/docs/research/examples/skill-write/write-skill/sources.md b/plugins/kyberforge/docs/research/examples/skill-write/write-skill/sources.md index cacb546..9d00328 100644 --- a/plugins/kyberforge/docs/research/examples/skill-write/write-skill/sources.md +++ b/plugins/kyberforge/docs/research/examples/skill-write/write-skill/sources.md @@ -1 +1 @@ -I created this myself :) \ No newline at end of file +I created this myself :) diff --git a/plugins/kyberforge/docs/research/examples/skill-write/writing-great-skills/GLOSSARY.md b/plugins/kyberforge/docs/research/examples/skill-write/writing-great-skills/GLOSSARY.md index 96e7ff2..665cf07 100644 --- a/plugins/kyberforge/docs/research/examples/skill-write/writing-great-skills/GLOSSARY.md +++ b/plugins/kyberforge/docs/research/examples/skill-write/writing-great-skills/GLOSSARY.md @@ -178,4 +178,4 @@ An instruction that changes nothing because the model already does it by default A leading word is a *technique*; No-Op is a *verdict* on a line — and they cross. A leading word too weak to beat the default is a no-op (_be thorough_ when the agent is already thorough-ish), and the fix is a stronger word that passes the verdict (_relentless_), not a different technique. So the No-Op test — does it change behaviour versus the default? — is also how you grade whether a leading word is earning its repetitions. This is model-relative, not reader-relative: two people disagreeing over whether a line is a no-op disagree about the default, and settle it by running the skill, not by debate. -_Avoid_: redundant instruction, restating the obvious, belaboring \ No newline at end of file +_Avoid_: redundant instruction, restating the obvious, belaboring diff --git a/plugins/kyberforge/docs/research/examples/skill-write/writing-great-skills/SKILL.md b/plugins/kyberforge/docs/research/examples/skill-write/writing-great-skills/SKILL.md index 7c3311f..61abad4 100644 --- a/plugins/kyberforge/docs/research/examples/skill-write/writing-great-skills/SKILL.md +++ b/plugins/kyberforge/docs/research/examples/skill-write/writing-great-skills/SKILL.md @@ -79,4 +79,4 @@ Use these to diagnose issues the user may be having with the skill. - **Duplication** — the same meaning in more than one place. Costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank. - **Sediment** — stale layers that settle because adding feels safe and removing feels risky. The default fate of any skill without a pruning discipline. - **Sprawl** — a skill simply too long, even when every line is live and unique. Hurts readability and maintainability and wastes tokens. The cure is the ladder: disclose **reference** behind pointers, and split by **branch** or sequence so each path carries only what it needs. -- **No-op** — a line the model already obeys by default, so you pay load to say nothing. The test: does it change behaviour versus the default? A weak leading word (_be thorough_ when the agent is already thorough-ish) is a no-op; the fix is a stronger word (_relentless_), not a different technique. \ No newline at end of file +- **No-op** — a line the model already obeys by default, so you pay load to say nothing. The test: does it change behaviour versus the default? A weak leading word (_be thorough_ when the agent is already thorough-ish) is a no-op; the fix is a stronger word (_relentless_), not a different technique. diff --git a/plugins/kyberforge/docs/research/examples/skill-write/writing-skills/graphviz-conventions.dot b/plugins/kyberforge/docs/research/examples/skill-write/writing-skills/graphviz-conventions.dot index 3509e2f..f02d8d9 100644 --- a/plugins/kyberforge/docs/research/examples/skill-write/writing-skills/graphviz-conventions.dot +++ b/plugins/kyberforge/docs/research/examples/skill-write/writing-skills/graphviz-conventions.dot @@ -169,4 +169,4 @@ digraph STYLE_GUIDE { bad_2 -> bad_3; bad_3 -> bad_4; } -} \ No newline at end of file +} diff --git a/scripts/secure-context-config.sh b/scripts/secure-context-config.sh deleted file mode 100755 index 8803482..0000000 --- a/scripts/secure-context-config.sh +++ /dev/null @@ -1,16 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -# Sets secure file permissions on ~/.context/config.json. -# Run after every `context auth add` to protect stored credentials. -# Safe to run when the file does not exist yet. - -CONFIG="${HOME}/.context/config.json" - -if [ ! -f "$CONFIG" ]; then - echo "Skipped: ${CONFIG} does not exist — no permissions to set." - exit 0 -fi - -chmod 600 "$CONFIG" -echo "Secured: ${CONFIG} set to 600 (owner read/write only)." diff --git a/scripts/setup-neuledge-context.sh b/scripts/setup-neuledge-context.sh deleted file mode 100755 index 8ddc6e4..0000000 --- a/scripts/setup-neuledge-context.sh +++ /dev/null @@ -1,36 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -# Installs @neuledge/context globally at a pinned version. -# Usage: setup-neuledge-context.sh [VERSION] -# VERSION — npm version string (default: 1.2.0) -# Idempotent: skips install if already at the target version. - -TARGET_VERSION="${1:-1.2.0}" - -current_version() { - context --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1 || echo "" -} - -CURRENT="$(current_version)" - -if [ "$CURRENT" = "$TARGET_VERSION" ]; then - echo "Already at @neuledge/context@${TARGET_VERSION} — nothing to do." - exit 0 -fi - -if [ -n "$CURRENT" ]; then - echo "Upgrading @neuledge/context from ${CURRENT} to ${TARGET_VERSION}..." -else - echo "Installing @neuledge/context@${TARGET_VERSION}..." -fi - -npm install -g "@neuledge/context@${TARGET_VERSION}" - -INSTALLED="$(current_version)" -if [ "$INSTALLED" = "$TARGET_VERSION" ]; then - echo "Done: @neuledge/context@${TARGET_VERSION} installed." -else - echo "Error: expected version ${TARGET_VERSION} but got '${INSTALLED}'" >&2 - exit 1 -fi