geloforge 0.0.0-stage → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +72 -2
  3. package/THIRD_PARTY_NOTICES.md +33 -0
  4. package/VERSION +1 -0
  5. package/adapters/n8n/staging-audit-error-workflow.json +132 -0
  6. package/core/adopt-project.mjs +458 -0
  7. package/core/audit-learning.mjs +68 -0
  8. package/core/audit-provider.mjs +88 -0
  9. package/core/autonomous-audit.mjs +214 -0
  10. package/core/checkpoint.mjs +448 -0
  11. package/core/codebase-map.mjs +886 -0
  12. package/core/compatibility.json +16 -0
  13. package/core/compatibility.mjs +123 -0
  14. package/core/context-cache.mjs +113 -0
  15. package/core/context-compiler.mjs +1315 -0
  16. package/core/evidence-capture.mjs +347 -0
  17. package/core/git-utils.mjs +167 -0
  18. package/core/handoff.mjs +815 -0
  19. package/core/json-schema-lite.mjs +119 -0
  20. package/core/mcp-init.mjs +251 -0
  21. package/core/mcp-server.mjs +915 -0
  22. package/core/operation-approval.mjs +102 -0
  23. package/core/path-safety.mjs +508 -0
  24. package/core/project-locator.mjs +231 -0
  25. package/core/project-lock.mjs +438 -0
  26. package/core/project-status.mjs +635 -0
  27. package/core/project-validator.mjs +544 -0
  28. package/core/promotion.mjs +90 -0
  29. package/core/runtime-files.mjs +40 -0
  30. package/core/skills-history.mjs +572 -0
  31. package/core/skills-lifecycle.mjs +2225 -0
  32. package/core/skills-lint.mjs +365 -0
  33. package/core/skills.mjs +1449 -0
  34. package/core/staging-audit.mjs +454 -0
  35. package/core/staging-evidence.mjs +127 -0
  36. package/core/task-manager.mjs +1044 -0
  37. package/core/template-utils.mjs +190 -0
  38. package/core/text-utils.mjs +48 -0
  39. package/core/verify-task.mjs +48 -0
  40. package/core/worktrees.mjs +64 -0
  41. package/core/yaml-subset.mjs +572 -0
  42. package/package.json +50 -4
  43. package/policies/approval-boundaries.md +42 -0
  44. package/policies/memory-policy.md +53 -0
  45. package/policies/token-efficiency.md +30 -0
  46. package/schemas/README.md +43 -0
  47. package/schemas/adr.schema.json +64 -0
  48. package/schemas/agent-handoff.schema.json +139 -0
  49. package/schemas/approval-record.schema.json +110 -0
  50. package/schemas/conflict-record.schema.json +60 -0
  51. package/schemas/context-pack-manifest.schema.json +194 -0
  52. package/schemas/evidence-manifest.schema.json +83 -0
  53. package/schemas/incident-record.schema.json +53 -0
  54. package/schemas/project-manifest.schema.json +90 -0
  55. package/schemas/project-state.schema.json +64 -0
  56. package/schemas/recovery-checkpoint.schema.json +49 -0
  57. package/schemas/research-record.schema.json +76 -0
  58. package/schemas/task-contract.schema.json +95 -0
  59. package/scripts/bootstrap-project.mjs +357 -0
  60. package/scripts/geloforge.mjs +2512 -0
  61. package/templates/profiles/README.md +19 -0
  62. package/templates/profiles/ai-system/brain/profile.md +21 -0
  63. package/templates/profiles/ai-system/gitignore.append +5 -0
  64. package/templates/profiles/ai-system/profile.json +6 -0
  65. package/templates/profiles/automation/brain/profile.md +19 -0
  66. package/templates/profiles/automation/gitignore.append +5 -0
  67. package/templates/profiles/automation/profile.json +6 -0
  68. package/templates/profiles/desktop/brain/profile.md +21 -0
  69. package/templates/profiles/desktop/gitignore.append +7 -0
  70. package/templates/profiles/desktop/profile.json +6 -0
  71. package/templates/profiles/mobile/brain/profile.md +20 -0
  72. package/templates/profiles/mobile/gitignore.append +8 -0
  73. package/templates/profiles/mobile/profile.json +6 -0
  74. package/templates/profiles/web/brain/profile.md +21 -0
  75. package/templates/profiles/web/gitignore.append +6 -0
  76. package/templates/profiles/web/profile.json +6 -0
  77. package/templates/project-starter/AGENTS.md +27 -0
  78. package/templates/project-starter/GEMINI.md +16 -0
  79. package/templates/project-starter/README.md +26 -0
  80. package/templates/project-starter/brain/INDEX.md +40 -0
  81. package/templates/project-starter/brain/architecture/overview.md +30 -0
  82. package/templates/project-starter/brain/decisions/.gitkeep +0 -0
  83. package/templates/project-starter/brain/manifest.yaml +36 -0
  84. package/templates/project-starter/brain/requirements/constraints.md +29 -0
  85. package/templates/project-starter/brain/requirements/prd.md +37 -0
  86. package/templates/project-starter/brain/state/current.yaml +19 -0
  87. package/templates/project-starter/gitignore.template +25 -0
  88. package/templates/project-starter/src/.gitkeep +0 -0
  89. package/templates/project-starter/tasks/.gitkeep +0 -0
  90. package/templates/project-starter/tests/.gitkeep +0 -0
@@ -0,0 +1,365 @@
1
+ /**
2
+ * Static security and quality linter for Agent Skills (SKILL.md) packages.
3
+ * Adapted from NousResearch hermes-agent skills_guard.py & skill_linter.py patterns
4
+ * into zero-dependency Node.js checks.
5
+ *
6
+ * IMPORTANT: Static pattern matching cannot prove a skill is harmless or stop
7
+ * semantic prompt injection. Treat all external/third-party skills as untrusted
8
+ * until reviewed by a human.
9
+ */
10
+
11
+ import { hasSecretContent, redactSecretContent } from "./path-safety.mjs";
12
+
13
+ export const STATIC_LINT_DISCLAIMER =
14
+ "Static checks detect known risky patterns only. A passing lint result does NOT prove a skill is harmless or guarantee protection against semantic prompt injection.";
15
+
16
+ const HIDDEN_UNICODE_REGEX = /[\u202A-\u202E\u2066-\u2069\u200B-\u200F\u2060\uFEFF]/;
17
+
18
+ const INJECTION_OVERRIDE_PATTERNS = [
19
+ /\b(?:ignore|disregard|forget|override)\s+(?:all\s+|any\s+)?(?:previous|prior|above|system|developer|harness|safety)\s+(?:instructions?|rules?|policies?|prompts?|constraints?)\b/i,
20
+ /\b(?:override|disable|bypass|ignore|skip)\s+(?:the\s+)?(?:a0|quarantine|approval(?:\s+gate|\s+boundaries)?|human\s+(?:approval|review|authorization)|security\s+policies?|guardrails?)\b/i,
21
+ /\b(?:do\s+not|never)\s+(?:tell|inform|show|mention\s+to)\s+(?:the\s+)?user\b/i,
22
+ /\bconceal\s+(?:this|these\s+actions?|output)\s+from\s+(?:the\s+)?user\b/i,
23
+ /\bsystem\s+prompt\s+override\b/i,
24
+ /<<<(?:END_)?GELOFORGE_DOC(?:>>>)?/,
25
+ ];
26
+
27
+ const REMOTE_EXEC_PATTERNS = [
28
+ /\b(?:curl|wget)\b[^\n|]*\|\s*(?:sudo\s+)?(?:sh|bash|zsh|dash|ksh|pwsh|powershell|python\d*|node)\b/i,
29
+ /\b(?:irm|iwr|invoke-webrequest|invoke-restmethod)\b[^\n|]*\|\s*(?:iex|invoke-expression)\b/i,
30
+ /\bbase64\s+(?:-d|--decode)\b[^\n|]*\|\s*(?:sh|bash|zsh|pwsh|powershell|python\d*|node)\b/i,
31
+ /\bpowershell(?:\.exe)?\b[^\n]*(?:-enc|-encodedcommand)\s+[A-Za-z0-9+/=]{16,}/i,
32
+ ];
33
+
34
+ const EXFILTRATION_PATTERNS = [
35
+ /(?:~\/\.ssh|~\/\.aws|\$\{?HOME\}?\/\.ssh|\$\{?HOME\}?\/\.aws|\/etc\/passwd|\/etc\/shadow|id_rsa|credentials\.json|\.env(?:\.[a-z]+)?)\b[^\n]*(?:curl|wget|nc\b|ncat|\/dev\/tcp\/|invoke-webrequest)/i,
36
+ /(?:curl|wget|nc\b|ncat|invoke-webrequest)[^\n]*(?:~\/\.ssh|~\/\.aws|\$\{?HOME\}?\/\.ssh|\$\{?HOME\}?\/\.aws|\/etc\/passwd|id_rsa|credentials\.json)/i,
37
+ ];
38
+
39
+ const AUTO_EXEC_CLAIM_PATTERNS = [
40
+ /\b(?:automatically\s+execute|silently\s+run|without\s+(?:asking|user\s+confirmation|human\s+(?:approval|review|authorization))|auto[- ]approve)\b/i,
41
+ ];
42
+
43
+ const OBFUSCATED_EXEC_PATTERNS = [
44
+ /\b(?:eval\s*\(\s*(?:atob|Buffer\.from)|new\s+Function\s*\(|powershell(?:\.exe)?[^\n]*-WindowStyle\s+Hidden)\b/i,
45
+ ];
46
+
47
+ const TRIGGER_GUIDANCE_REGEX =
48
+ /\b(?:when\s+to\s+use|use\s+(?:this\s+skill\s+)?when|trigger(?:s|ed)?\s+(?:when|for)|applicable\s+when)\b/i;
49
+
50
+ function makeFinding({ ruleId, severity, category, message, file, remediation }) {
51
+ return {
52
+ ruleId,
53
+ severity,
54
+ category,
55
+ message: redactSecretContent(message),
56
+ file,
57
+ remediation,
58
+ };
59
+ }
60
+
61
+ function scanTextForSecurity(findings, text, relFile) {
62
+ if (!text) return;
63
+
64
+ if (hasSecretContent(text)) {
65
+ findings.push(
66
+ makeFinding({
67
+ ruleId: "SEC-SECRET-CONTENT",
68
+ severity: "critical",
69
+ category: "security",
70
+ message: `Detected embedded credential or private-key literal in ${relFile}.`,
71
+ file: relFile,
72
+ remediation: "Remove credential literals and reference runtime environment variables securely.",
73
+ })
74
+ );
75
+ }
76
+ if (HIDDEN_UNICODE_REGEX.test(text)) {
77
+ findings.push(
78
+ makeFinding({
79
+ ruleId: "SEC-HIDDEN-UNICODE",
80
+ severity: "critical",
81
+ category: "security",
82
+ message: `Detected hidden Unicode directional override or zero-width control character in ${relFile}.`,
83
+ file: relFile,
84
+ remediation: "Remove bidi override (U+202A-U+202E, U+2066-U+2069) and zero-width characters.",
85
+ })
86
+ );
87
+ }
88
+ if (INJECTION_OVERRIDE_PATTERNS.some((pat) => pat.test(text))) {
89
+ findings.push(
90
+ makeFinding({
91
+ ruleId: "SEC-INJECTION-OVERRIDE",
92
+ severity: "critical",
93
+ category: "security",
94
+ message: `Detected instruction-override, A0 bypass, stealth, or delimiter-spoofing phrase in ${relFile}.`,
95
+ file: relFile,
96
+ remediation: "Remove instructions asking agents to ignore A0 policies, deceive users, or spoof packet fences.",
97
+ })
98
+ );
99
+ }
100
+ if (REMOTE_EXEC_PATTERNS.some((pat) => pat.test(text))) {
101
+ findings.push(
102
+ makeFinding({
103
+ ruleId: "SEC-REMOTE-EXEC",
104
+ severity: "critical",
105
+ category: "security",
106
+ message: `Detected remote download-and-execute pipeline or encoded shell payload in ${relFile}.`,
107
+ file: relFile,
108
+ remediation: "Replace piped remote installers or encoded commands with inspectable local instructions.",
109
+ })
110
+ );
111
+ }
112
+ if (EXFILTRATION_PATTERNS.some((pat) => pat.test(text))) {
113
+ findings.push(
114
+ makeFinding({
115
+ ruleId: "SEC-EXFILTRATION",
116
+ severity: "critical",
117
+ category: "security",
118
+ message: `Detected potential credential/system-file exfiltration command in ${relFile}.`,
119
+ file: relFile,
120
+ remediation: "Remove commands referencing SSH keys, .aws, .env, or system files alongside network tools.",
121
+ })
122
+ );
123
+ }
124
+ if (AUTO_EXEC_CLAIM_PATTERNS.some((pat) => pat.test(text))) {
125
+ findings.push(
126
+ makeFinding({
127
+ ruleId: "SEC-AUTO-EXEC-CLAIM",
128
+ severity: "high",
129
+ category: "security",
130
+ message: `Detected language claiming silent execution or bypassing confirmation in ${relFile}.`,
131
+ file: relFile,
132
+ remediation: "Require explicit developer confirmation and remember GeloForge never auto-executes scripts.",
133
+ })
134
+ );
135
+ }
136
+ if (OBFUSCATED_EXEC_PATTERNS.some((pat) => pat.test(text))) {
137
+ findings.push(
138
+ makeFinding({
139
+ ruleId: "SEC-OBFUSCATED-EXEC",
140
+ severity: "high",
141
+ category: "security",
142
+ message: `Detected dynamic/obfuscated execution pattern in ${relFile}.`,
143
+ file: relFile,
144
+ remediation: "Avoid encoded dynamic code execution snippets inside skills.",
145
+ })
146
+ );
147
+ }
148
+ }
149
+
150
+ /**
151
+ * Runs static security and quality lint checks on an inspected skill package.
152
+ */
153
+ export function lintSkill(skill) {
154
+ const findings = [];
155
+ const defaultFile = `${skill.displayPath}/SKILL.md`;
156
+
157
+ for (const err of skill.errors || []) {
158
+ if (err.code === "SEC-SECRET-CONTENT" || err.code === "SEC-SYMLINK-OR-TRAVERSAL") {
159
+ findings.push(
160
+ makeFinding({
161
+ ruleId: err.code,
162
+ severity: "critical",
163
+ category: "security",
164
+ message: err.message,
165
+ file: err.file || defaultFile,
166
+ remediation: err.remediation,
167
+ })
168
+ );
169
+ } else {
170
+ findings.push(
171
+ makeFinding({
172
+ ruleId: err.code || "VAL-INVALID",
173
+ severity: "error",
174
+ category: "validation",
175
+ message: err.message,
176
+ file: err.file || defaultFile,
177
+ remediation: err.remediation,
178
+ })
179
+ );
180
+ }
181
+ }
182
+
183
+ for (const warn of skill.warnings || []) {
184
+ findings.push(
185
+ makeFinding({
186
+ ruleId: warn.code || "QUAL-WARNING",
187
+ severity: "warning",
188
+ category: warn.category || "quality",
189
+ message: warn.message,
190
+ file: warn.file || defaultFile,
191
+ remediation: warn.remediation,
192
+ })
193
+ );
194
+ }
195
+
196
+ // Scan SKILL.md metadata + body
197
+ if (skill.rawSkillText) {
198
+ // Strip legitimate leading BOM already handled in parse; inspect normalized content.
199
+ const normalizedForScan = skill.rawSkillText.replace(/^\uFEFF/, "");
200
+ scanTextForSecurity(findings, normalizedForScan, defaultFile);
201
+ }
202
+
203
+ // Scan supporting text resources statically (never executing any scripts)
204
+ for (const resText of skill.inspectableTexts || []) {
205
+ scanTextForSecurity(findings, resText.text, `${skill.displayPath}/${resText.relPath}`);
206
+ }
207
+
208
+ // Quality & anti-rot checks (only meaningful once body exists)
209
+ if (typeof skill.body === "string" && skill.body.length > 0) {
210
+ if (skill.lineCount > 500 || skill.charCount > 24000) {
211
+ findings.push(
212
+ makeFinding({
213
+ ruleId: "QUAL-BODY-SIZE",
214
+ severity: "warning",
215
+ category: "quality",
216
+ message: `SKILL.md is large (${skill.lineCount} lines, ${skill.charCount} chars; recommended <= 500 lines / 24,000 chars).`,
217
+ file: defaultFile,
218
+ remediation: "Move bulky checklists or schemas into references/ and link them selectively.",
219
+ })
220
+ );
221
+ }
222
+
223
+ const desc = typeof skill.frontmatter?.description === "string" ? skill.frontmatter.description.trim() : "";
224
+ if (desc.length > 0 && desc.length < 20) {
225
+ findings.push(
226
+ makeFinding({
227
+ ruleId: "QUAL-SHORT-DESCRIPTION",
228
+ severity: "warning",
229
+ category: "quality",
230
+ message: `Skill description is very short (${desc.length} chars; recommended >= 20 chars).`,
231
+ file: defaultFile,
232
+ remediation: "Describe both what the skill does and specific tasks/triggers when it applies.",
233
+ })
234
+ );
235
+ }
236
+
237
+ const combinedGuidanceText = `${desc}\n${skill.body}`;
238
+ if (!TRIGGER_GUIDANCE_REGEX.test(combinedGuidanceText) && (skill.triggers || []).length === 0) {
239
+ findings.push(
240
+ makeFinding({
241
+ ruleId: "QUAL-NO-TRIGGER-GUIDANCE",
242
+ severity: "warning",
243
+ category: "quality",
244
+ message: "SKILL.md lacks explicit 'When to Use' / trigger guidance.",
245
+ file: defaultFile,
246
+ remediation: "Add a short '## When to Use' section or metadata.geloforge_triggers hint.",
247
+ })
248
+ );
249
+ }
250
+ }
251
+
252
+ const refsCount = (skill.resources?.references || []).length;
253
+ if (refsCount > 10) {
254
+ findings.push(
255
+ makeFinding({
256
+ ruleId: "QUAL-REFERENCE-SPRAWL",
257
+ severity: "warning",
258
+ category: "quality",
259
+ message: `Skill contains ${refsCount} files in references/ (recommended <= 10 for discoverability).`,
260
+ file: `${skill.displayPath}/references`,
261
+ remediation: "Consolidate related reference notes so agents do not have to guess among many files.",
262
+ })
263
+ );
264
+ }
265
+
266
+ for (const extra of skill.scaffoldingFiles || []) {
267
+ findings.push(
268
+ makeFinding({
269
+ ruleId: "QUAL-FORBIDDEN-SCAFFOLDING",
270
+ severity: "warning",
271
+ category: "quality",
272
+ message: `Extraneous scaffolding file "${extra}" inside skill directory.`,
273
+ file: `${skill.displayPath}/${extra}`,
274
+ remediation: "Remove README.md/CHANGELOG.md clutter and keep documentation inside SKILL.md or references/.",
275
+ })
276
+ );
277
+ }
278
+
279
+ const scripts = skill.resources?.scripts || [];
280
+ const posixOnlyScripts = scripts.filter((rel) => /\.(sh|bash)$/i.test(rel));
281
+ if (posixOnlyScripts.length > 0) {
282
+ const hasCrossPlatformMjs = scripts.some((rel) => /\.(mjs|js|ps1)$/i.test(rel));
283
+ const mentionsCrossPlatform = /\b(windows|powershell|cross-platform|wsl|git bash)\b/i.test(skill.body || "");
284
+ if (!hasCrossPlatformMjs && !mentionsCrossPlatform) {
285
+ findings.push(
286
+ makeFinding({
287
+ ruleId: "QUAL-POSIX-ONLY-SCRIPT",
288
+ severity: "warning",
289
+ category: "portability",
290
+ message: `Skill includes shell script(s) (${posixOnlyScripts.join(", ")}) without cross-platform/Windows notes or Node .mjs equivalent. Note: GeloForge never auto-executes skill scripts.`,
291
+ file: `${skill.displayPath}/${posixOnlyScripts[0]}`,
292
+ remediation: "Add a portable Node .mjs helper or document shell requirements clearly.",
293
+ })
294
+ );
295
+ }
296
+ }
297
+
298
+ // Deduplicate identical ruleId+file+message pairs
299
+ const deduped = [];
300
+ const seen = new Set();
301
+ for (const f of findings) {
302
+ const key = `${f.ruleId}|${f.file}|${f.message}`;
303
+ if (!seen.has(key)) {
304
+ seen.add(key);
305
+ deduped.push(f);
306
+ }
307
+ }
308
+
309
+ const counts = { critical: 0, high: 0, error: 0, warning: 0, info: 0 };
310
+ for (const f of deduped) {
311
+ counts[f.severity] = (counts[f.severity] || 0) + 1;
312
+ }
313
+
314
+ return {
315
+ name: skill.name,
316
+ displayPath: skill.displayPath,
317
+ source: skill.source,
318
+ trustTier: skill.trustTier,
319
+ findings: deduped,
320
+ counts,
321
+ hasCriticalOrError: counts.critical > 0 || counts.error > 0,
322
+ hasHighOrAbove: counts.critical > 0 || counts.error > 0 || counts.high > 0,
323
+ };
324
+ }
325
+
326
+ /**
327
+ * Aggregates lint reports across discovered skills and root-level safety diagnostics.
328
+ */
329
+ export function lintDiscoveredSkills(discovery, { strict = false, includeDrafts = false } = {}) {
330
+ const pool = [...discovery.allSkills];
331
+ if (includeDrafts) {
332
+ pool.push(...discovery.quarantinedSkills);
333
+ }
334
+ const results = pool.map((skill) => lintSkill(skill));
335
+ const counts = {
336
+ critical: discovery.rootErrors.length,
337
+ high: 0,
338
+ error: 0,
339
+ warning: discovery.rootWarnings.length,
340
+ info: 0,
341
+ };
342
+
343
+ for (const r of results) {
344
+ counts.critical += r.counts.critical;
345
+ counts.high += r.counts.high;
346
+ counts.error += r.counts.error;
347
+ counts.warning += r.counts.warning;
348
+ counts.info += r.counts.info;
349
+ }
350
+
351
+ const passed = strict
352
+ ? counts.critical === 0 && counts.error === 0 && counts.high === 0 && counts.warning === 0
353
+ : counts.critical === 0 && counts.error === 0;
354
+
355
+ return {
356
+ passed,
357
+ strict,
358
+ disclaimer: STATIC_LINT_DISCLAIMER,
359
+ counts,
360
+ rootErrors: discovery.rootErrors,
361
+ rootWarnings: discovery.rootWarnings,
362
+ conflicts: discovery.conflicts,
363
+ skills: results,
364
+ };
365
+ }