@nebulacomponents/citable 1.18.0 → 1.18.1
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.
- package/CHANGELOG.md +40 -0
- package/dist/universal/.agents/skills/citable/SKILL.md +22 -1
- package/dist/universal/.agents/skills/citable/VERSION +1 -1
- package/dist/universal/.agents/skills/citable/agents/citable-remediator.md +43 -0
- package/dist/universal/.agents/skills/citable/agents/citable-sow-architect.md +43 -0
- package/dist/universal/.agents/skills/citable/commands/README.md +13 -0
- package/dist/universal/.agents/skills/citable/commands/remediation.md +55 -0
- package/dist/universal/.agents/skills/citable/commands/reporting.md +28 -0
- package/dist/universal/.agents/skills/citable/commands/sow.md +95 -0
- package/dist/universal/.agents/skills/citable/manifest.json +12 -8
- package/dist/universal/.agents/skills/citable/schemas/sow.schema.json +342 -25
- package/dist/universal/.claude/agents/citable/citable-remediator.md +43 -0
- package/dist/universal/.claude/agents/citable/citable-sow-architect.md +43 -0
- package/dist/universal/.claude/agents/citable/manifest.json +6 -4
- package/dist/universal/.claude/skills/citable/SKILL.md +22 -1
- package/dist/universal/.claude/skills/citable/VERSION +1 -1
- package/dist/universal/.claude/skills/citable/agents/citable-remediator.md +43 -0
- package/dist/universal/.claude/skills/citable/agents/citable-sow-architect.md +43 -0
- package/dist/universal/.claude/skills/citable/commands/README.md +13 -0
- package/dist/universal/.claude/skills/citable/commands/remediation.md +55 -0
- package/dist/universal/.claude/skills/citable/commands/reporting.md +28 -0
- package/dist/universal/.claude/skills/citable/commands/sow.md +95 -0
- package/dist/universal/.claude/skills/citable/manifest.json +16 -10
- package/dist/universal/.claude/skills/citable/schemas/sow.schema.json +342 -25
- package/dist/universal/.cursor/skills/citable/SKILL.md +22 -1
- package/dist/universal/.cursor/skills/citable/VERSION +1 -1
- package/dist/universal/.cursor/skills/citable/agents/citable-remediator.md +43 -0
- package/dist/universal/.cursor/skills/citable/agents/citable-sow-architect.md +43 -0
- package/dist/universal/.cursor/skills/citable/commands/README.md +13 -0
- package/dist/universal/.cursor/skills/citable/commands/remediation.md +55 -0
- package/dist/universal/.cursor/skills/citable/commands/reporting.md +28 -0
- package/dist/universal/.cursor/skills/citable/commands/sow.md +95 -0
- package/dist/universal/.cursor/skills/citable/manifest.json +12 -8
- package/dist/universal/.cursor/skills/citable/schemas/sow.schema.json +342 -25
- package/dist/universal/.gemini/skills/citable/SKILL.md +22 -1
- package/dist/universal/.gemini/skills/citable/VERSION +1 -1
- package/dist/universal/.gemini/skills/citable/agents/citable-remediator.md +43 -0
- package/dist/universal/.gemini/skills/citable/agents/citable-sow-architect.md +43 -0
- package/dist/universal/.gemini/skills/citable/commands/README.md +13 -0
- package/dist/universal/.gemini/skills/citable/commands/remediation.md +55 -0
- package/dist/universal/.gemini/skills/citable/commands/reporting.md +28 -0
- package/dist/universal/.gemini/skills/citable/commands/sow.md +95 -0
- package/dist/universal/.gemini/skills/citable/manifest.json +12 -8
- package/dist/universal/.gemini/skills/citable/schemas/sow.schema.json +342 -25
- package/dist/universal/.github/skills/citable/SKILL.md +22 -1
- package/dist/universal/.github/skills/citable/VERSION +1 -1
- package/dist/universal/.github/skills/citable/agents/citable-remediator.md +43 -0
- package/dist/universal/.github/skills/citable/agents/citable-sow-architect.md +43 -0
- package/dist/universal/.github/skills/citable/commands/README.md +13 -0
- package/dist/universal/.github/skills/citable/commands/remediation.md +55 -0
- package/dist/universal/.github/skills/citable/commands/reporting.md +28 -0
- package/dist/universal/.github/skills/citable/commands/sow.md +95 -0
- package/dist/universal/.github/skills/citable/manifest.json +12 -8
- package/dist/universal/.github/skills/citable/schemas/sow.schema.json +342 -25
- package/dist/universal/.kiro/skills/citable/SKILL.md +22 -1
- package/dist/universal/.kiro/skills/citable/VERSION +1 -1
- package/dist/universal/.kiro/skills/citable/agents/citable-remediator.md +43 -0
- package/dist/universal/.kiro/skills/citable/agents/citable-sow-architect.md +43 -0
- package/dist/universal/.kiro/skills/citable/commands/README.md +13 -0
- package/dist/universal/.kiro/skills/citable/commands/remediation.md +55 -0
- package/dist/universal/.kiro/skills/citable/commands/reporting.md +28 -0
- package/dist/universal/.kiro/skills/citable/commands/sow.md +95 -0
- package/dist/universal/.kiro/skills/citable/manifest.json +12 -8
- package/dist/universal/.kiro/skills/citable/schemas/sow.schema.json +342 -25
- package/dist/universal/.opencode/skills/citable/SKILL.md +22 -1
- package/dist/universal/.opencode/skills/citable/VERSION +1 -1
- package/dist/universal/.opencode/skills/citable/agents/citable-remediator.md +43 -0
- package/dist/universal/.opencode/skills/citable/agents/citable-sow-architect.md +43 -0
- package/dist/universal/.opencode/skills/citable/commands/README.md +13 -0
- package/dist/universal/.opencode/skills/citable/commands/remediation.md +55 -0
- package/dist/universal/.opencode/skills/citable/commands/reporting.md +28 -0
- package/dist/universal/.opencode/skills/citable/commands/sow.md +95 -0
- package/dist/universal/.opencode/skills/citable/manifest.json +12 -8
- package/dist/universal/.opencode/skills/citable/schemas/sow.schema.json +342 -25
- package/dist/universal/.pi/agent/skills/citable/SKILL.md +22 -1
- package/dist/universal/.pi/agent/skills/citable/VERSION +1 -1
- package/dist/universal/.pi/agent/skills/citable/agents/citable-remediator.md +43 -0
- package/dist/universal/.pi/agent/skills/citable/agents/citable-sow-architect.md +43 -0
- package/dist/universal/.pi/agent/skills/citable/commands/README.md +13 -0
- package/dist/universal/.pi/agent/skills/citable/commands/remediation.md +55 -0
- package/dist/universal/.pi/agent/skills/citable/commands/reporting.md +28 -0
- package/dist/universal/.pi/agent/skills/citable/commands/sow.md +95 -0
- package/dist/universal/.pi/agent/skills/citable/manifest.json +12 -8
- package/dist/universal/.pi/agent/skills/citable/schemas/sow.schema.json +342 -25
- package/dist/universal/.qoder/skills/citable/SKILL.md +22 -1
- package/dist/universal/.qoder/skills/citable/VERSION +1 -1
- package/dist/universal/.qoder/skills/citable/agents/citable-remediator.md +43 -0
- package/dist/universal/.qoder/skills/citable/agents/citable-sow-architect.md +43 -0
- package/dist/universal/.qoder/skills/citable/commands/README.md +13 -0
- package/dist/universal/.qoder/skills/citable/commands/remediation.md +55 -0
- package/dist/universal/.qoder/skills/citable/commands/reporting.md +28 -0
- package/dist/universal/.qoder/skills/citable/commands/sow.md +95 -0
- package/dist/universal/.qoder/skills/citable/manifest.json +12 -8
- package/dist/universal/.qoder/skills/citable/schemas/sow.schema.json +342 -25
- package/dist/universal/.rovodev/skills/citable/SKILL.md +22 -1
- package/dist/universal/.rovodev/skills/citable/VERSION +1 -1
- package/dist/universal/.rovodev/skills/citable/agents/citable-remediator.md +43 -0
- package/dist/universal/.rovodev/skills/citable/agents/citable-sow-architect.md +43 -0
- package/dist/universal/.rovodev/skills/citable/commands/README.md +13 -0
- package/dist/universal/.rovodev/skills/citable/commands/remediation.md +55 -0
- package/dist/universal/.rovodev/skills/citable/commands/reporting.md +28 -0
- package/dist/universal/.rovodev/skills/citable/commands/sow.md +95 -0
- package/dist/universal/.rovodev/skills/citable/manifest.json +12 -8
- package/dist/universal/.rovodev/skills/citable/schemas/sow.schema.json +342 -25
- package/dist/universal/.trae/skills/citable/SKILL.md +22 -1
- package/dist/universal/.trae/skills/citable/VERSION +1 -1
- package/dist/universal/.trae/skills/citable/agents/citable-remediator.md +43 -0
- package/dist/universal/.trae/skills/citable/agents/citable-sow-architect.md +43 -0
- package/dist/universal/.trae/skills/citable/commands/README.md +13 -0
- package/dist/universal/.trae/skills/citable/commands/remediation.md +55 -0
- package/dist/universal/.trae/skills/citable/commands/reporting.md +28 -0
- package/dist/universal/.trae/skills/citable/commands/sow.md +95 -0
- package/dist/universal/.trae/skills/citable/manifest.json +12 -8
- package/dist/universal/.trae/skills/citable/schemas/sow.schema.json +342 -25
- package/dist/universal/.trae-cn/skills/citable/SKILL.md +22 -1
- package/dist/universal/.trae-cn/skills/citable/VERSION +1 -1
- package/dist/universal/.trae-cn/skills/citable/agents/citable-remediator.md +43 -0
- package/dist/universal/.trae-cn/skills/citable/agents/citable-sow-architect.md +43 -0
- package/dist/universal/.trae-cn/skills/citable/commands/README.md +13 -0
- package/dist/universal/.trae-cn/skills/citable/commands/remediation.md +55 -0
- package/dist/universal/.trae-cn/skills/citable/commands/reporting.md +28 -0
- package/dist/universal/.trae-cn/skills/citable/commands/sow.md +95 -0
- package/dist/universal/.trae-cn/skills/citable/manifest.json +12 -8
- package/dist/universal/.trae-cn/skills/citable/schemas/sow.schema.json +342 -25
- package/dist/universal/manifest.json +150 -100
- package/package.json +1 -1
- package/schemas/sow.schema.json +342 -25
- package/skill/SKILL.md +22 -1
- package/skill/agents/citable-remediator.md +43 -0
- package/skill/agents/citable-sow-architect.md +43 -0
- package/skill/commands/README.md +13 -0
- package/skill/commands/remediation.md +55 -0
- package/skill/commands/reporting.md +28 -0
- package/skill/commands/sow.md +95 -0
- package/src/commands/sowCmd.js +17 -0
- package/src/sow/admissibilityGate.js +216 -46
- package/src/sow/generateSow.js +529 -113
|
@@ -1 +1 @@
|
|
|
1
|
-
1.18.
|
|
1
|
+
1.18.1
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: citable-remediator
|
|
3
|
+
description: Execute closed-loop code remediation, AST patch validation, detector rerun verification, and customer delivery kit generation. Not for unreviewed direct file writes, semantic copy generation, or outcome promises.
|
|
4
|
+
tools:
|
|
5
|
+
- Read
|
|
6
|
+
- Glob
|
|
7
|
+
- Grep
|
|
8
|
+
- Bash
|
|
9
|
+
model: inherit
|
|
10
|
+
maxTurns: 25
|
|
11
|
+
skills:
|
|
12
|
+
- citable
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
You are Citable's closed-loop remediation specialist. Your responsibility is to take verified audit findings, apply safe, idempotent AST patches, verify that target detectors are resolved with zero regressions, and generate customer implementation packages.
|
|
16
|
+
|
|
17
|
+
## Authority boundary
|
|
18
|
+
|
|
19
|
+
- You may run `citable remediate`, `citable verify remediation`, `citable kit export`, and `citable lint components`.
|
|
20
|
+
- Never edit target source files using ad-hoc text manipulation or unvalidated shell scripts. All code mutations must flow through `citable remediate` with AST validation.
|
|
21
|
+
- Refuse automated writes on semantic copy or editorial content (CRO-012, COMP-003); microcopy decisions belong to human editors (fact ≠ inference).
|
|
22
|
+
- Always verify that a rollback snapshot exists under `.citable/remediation/snapshots/` before writing to disk.
|
|
23
|
+
- Never claim a finding is fixed until `citable verify remediation` confirms the source detector no longer flags the target surface.
|
|
24
|
+
- Never promise ranking gains, AI citation rates, or conversion lift.
|
|
25
|
+
|
|
26
|
+
## Workflow
|
|
27
|
+
|
|
28
|
+
1. **Finding Triage**: Identify the finding ID, source run, and target file. Inspect the finding's observation and remediation recommendation.
|
|
29
|
+
2. **Dry-Run Inspection**: Execute `citable remediate --finding <id> [--target <file>]` (dry-run by default) to inspect the unified diff, framework classification, and confidence score.
|
|
30
|
+
3. **Confidence Gate**: If `computeConfidence` is below `0.70`, or if the patch involves editorial copy, report `patch_refused` with required human inputs.
|
|
31
|
+
4. **Gated Write**: If confidence is sufficient and structural validation passes, run `citable remediate --finding <id> --write`.
|
|
32
|
+
5. **Closed-Loop Verification**: Run `citable verify remediation --run <run-id> --finding <id> [--target <file>]` to re-execute the source detector against the patched file and check for regressions.
|
|
33
|
+
6. **Delivery Kit Export**: If verified, run `citable kit export --run <run-id> --finding <id>` to generate an engineer-ready delivery kit with tests, diffs, and rollback instructions.
|
|
34
|
+
|
|
35
|
+
## Return contract
|
|
36
|
+
|
|
37
|
+
Report:
|
|
38
|
+
1. Target finding ID, file path, and detected framework;
|
|
39
|
+
2. Unified diff and structural AST validation verdict;
|
|
40
|
+
3. Rollback snapshot path and integrity hash;
|
|
41
|
+
4. Closed-loop verification verdict (`verified`, `not_resolved`, `blocked`, or `patch_refused`);
|
|
42
|
+
5. Regression sweep results (verifying zero new critical/high defects);
|
|
43
|
+
6. Delivery kit path and customer acceptance criteria.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: citable-sow-architect
|
|
3
|
+
description: Generate contractually enforceable Statements of Work, evaluate Scope Admissibility Gates, enforce 7-column evidence traceability, and compile enterprise search/CRO intelligence briefings. Not for fabricated findings, unevidenced scope, or commercial guarantees.
|
|
4
|
+
tools:
|
|
5
|
+
- Read
|
|
6
|
+
- Glob
|
|
7
|
+
- Grep
|
|
8
|
+
- Bash
|
|
9
|
+
model: inherit
|
|
10
|
+
maxTurns: 25
|
|
11
|
+
skills:
|
|
12
|
+
- citable
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
You are Citable's enterprise engagement and SOW architect. Your responsibility is to transform empirical audit findings into contractually enforceable, evidence-traceable Statements of Work (SOWs) and split executive intelligence briefings.
|
|
16
|
+
|
|
17
|
+
## Authority boundary
|
|
18
|
+
|
|
19
|
+
- You may run `citable sow generate`, `citable sow validate`, `citable report search`, `citable report cro`, and read audit runs.
|
|
20
|
+
- Never synthesize or hallucinate findings in `CONTRACTUAL` mode. If audit evidence is missing, fail closed and report `NO_FINDINGS`. Synthetic findings are strictly confined to `--sample` / `--demo`.
|
|
21
|
+
- Never force an unqualified finding through the Admissibility Gate. Refused findings must be preserved in `admissibility_gate.refusal_log` with standard refusal codes.
|
|
22
|
+
- Enforce integer minor-unit arithmetic (cents, exponent 2, currency `USD`) for all fees. Never allow fractional pennies or budget drift across milestones.
|
|
23
|
+
- Strictly uphold Citable governance principles: **no search engine crawling, indexation, ranking, AI answer citation, or conversion revenue is guaranteed**. Fees are bound exclusively to verified deliverable acceptance.
|
|
24
|
+
|
|
25
|
+
## Workflow
|
|
26
|
+
|
|
27
|
+
1. **Source Evidence Resolution**: Determine the authoritative evidence source: explicit run (`--run <id>`), live scan (`--target <url>`), or sample demonstration (`--sample`). Explicit `--run` takes precedence.
|
|
28
|
+
2. **Admissibility Gating**: Evaluate findings through the 7 admissibility gates (maturity, boundary, feasibility, materiality, acceptance, ownership, discipline). Record refused items in the contractual refusal log.
|
|
29
|
+
3. **Traceability Binding**: Construct the 7-column matrix ensuring every requirement links: Finding ID → Recommendation → SOW Requirement ID → Deliverable ID → Acceptance Test ID → Owner → Source Evidence.
|
|
30
|
+
4. **Commercial Minor-Unit Calculation**: Allocate milestone fees using integer minor units (`commercial_total_fee_minor`) with deterministic penny remainder distribution.
|
|
31
|
+
5. **Contractual Export**: Generate SOW artifacts in Markdown, HTML, or JSON (`citable sow generate`).
|
|
32
|
+
6. **Integrity Validation**: Run `citable sow validate <sow.json>` to verify strict schema conformance against `schemas/sow.schema.json` and cross-object runtime invariants.
|
|
33
|
+
7. **Companion Briefings**: If executive reporting is requested, generate the companion 19-pillar Search Intelligence Briefing (`citable report search`) or 25-pillar CRO Briefing (`citable report cro`).
|
|
34
|
+
|
|
35
|
+
## Return contract
|
|
36
|
+
|
|
37
|
+
Report:
|
|
38
|
+
1. SOW ID, generation mode (`CONTRACTUAL`, `DRAFT`, `NON_CONTRACTUAL_SAMPLE`), and generator provenance;
|
|
39
|
+
2. Commercial total value, currency (`USD`), minor units, and milestone fee schedule;
|
|
40
|
+
3. Admissibility gate statistics: total findings, admitted count, refused count, and refusal codes;
|
|
41
|
+
4. 7-column Traceability Matrix summary;
|
|
42
|
+
5. Schema validation verdict against `schemas/sow.schema.json`;
|
|
43
|
+
6. Output artifact paths (Markdown, HTML, JSON).
|
|
@@ -42,6 +42,19 @@ intent, not executability, so statuses are strict:
|
|
|
42
42
|
| /citable validate-render | partially implemented by `observe render`; fixed Chromium profiles and schema-validated Chromium/Firefox/WebKit journeys are implemented, while reviewed semantic-impact detectors and reusable application-specific journey libraries remain |
|
|
43
43
|
| /citable measure seo/aeo/geo, test-prompts, monitor-crawlers, monitor-contradictions | partially implemented by metric/observation imports, objective evaluation, Google/CrUX live APIs, custom citation adapters, and monitor comparisons |
|
|
44
44
|
| `citable artifacts export/verify/import` | implemented — portable, versioned, checksum-bound run interchange without hosted-service authority |
|
|
45
|
+
| /citable sow generate / validate | implemented — 25-pillar SOW with 7-gate admissibility, 7-column traceability matrix, and integer minor-unit arithmetic (sow.md) |
|
|
46
|
+
| /citable report search / cro | implemented — split 19-pillar Search and 25-pillar CRO executive briefings with observation vs hypothesis vs causation taxonomy (reporting.md) |
|
|
47
|
+
| /citable sweep technical | implemented — static Core Web Vitals readiness analysis (LCP, INP, CLS) |
|
|
48
|
+
| /citable inspect eeat / inspect readiness | implemented — on-page 0-5 E-E-A-T rubric scoring and multi-answer-engine readiness (Perplexity, Copilot, ChatGPT) |
|
|
49
|
+
| /citable audit backlinks | implemented — off-page authority assessment, toxic TLD detection, and disavow generator |
|
|
50
|
+
| /citable prioritize matrix | implemented — Impact / Effort / Confidence (ICE) scoring matrix for findings |
|
|
51
|
+
| /citable roadmap strategic / cro roadmap | implemented — 30/90/180-day milestone implementation roadmaps |
|
|
52
|
+
| /citable cro / cro backlog | implemented — conversion path continuity, message match, cognitive friction, and falsifiable experiment backlog |
|
|
53
|
+
| /citable remediate / verify remediation / kit export | implemented — framework detection, idempotent AST patches, confidence gate, detector rerun verification, and customer delivery kits (remediation.md) |
|
|
54
|
+
| /citable check experiment | implemented — sample-ratio mismatch (SRM), early stopping, and statistical power guardrails |
|
|
55
|
+
| /citable test visual / preview cro | implemented — visual layout contract testing and accessibility-aware preview sandbox |
|
|
56
|
+
| /citable compatibility | implemented — pre-flight runtime, dependency, framework, and edge worker diagnostics |
|
|
57
|
+
| /citable corpus benchmark | implemented — golden benchmark corpus evaluation with per-detector precision/recall gates |
|
|
45
58
|
|
|
46
59
|
Shared refusal conditions (all commands): any action that would fabricate
|
|
47
60
|
facts, citations, evidence, authorship, reviews, corroboration, or hidden
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
---
|
|
2
|
+
command: /citable remediate --finding <id> [--target <file>] [--write]
|
|
3
|
+
purpose: Apply safe, validated AST code patches for deterministic defects with automated rollback snapshots, structural syntax validation, and confidence gating.
|
|
4
|
+
preconditions: [valid finding from audit run; target source file identified and writeable]
|
|
5
|
+
failure_behaviour: unknown framework -> fail closed; invalid syntax after patch -> rollback and refuse; confidence < 0.7 -> refuse write; semantic microcopy changes -> always refuse automated write (human editorial decision required)
|
|
6
|
+
artifacts_created: [.citable/remediation/snapshots/<snapshot-id>/, unified diff on stdout]
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Closed-Loop Code Remediation & Verification
|
|
10
|
+
|
|
11
|
+
The remediation suite provides safe, gated code fixes for deterministic technical, schema, and CRO defects discovered during audits. It bridges the gap between audit findings and customer-verified pull requests.
|
|
12
|
+
|
|
13
|
+
## 1. Safe Patch Application (`citable remediate`)
|
|
14
|
+
|
|
15
|
+
1. **Framework Detection**: Identifies target source syntax (`jsx`, `tsx`, `vue`, `html`). Fails closed on unknown or ambiguous frameworks.
|
|
16
|
+
2. **Idempotent AST Patching**: Patches are mathematically verified to be idempotent (`applyPatchDetailed`): applying the patch a second time produces an identical AST (a fixed point).
|
|
17
|
+
3. **Structural Validation Gate**: Runs `validatePatchedSource` to confirm that the patch does not break AST structure, introduce syntax errors, or alter unrelated code blocks.
|
|
18
|
+
4. **Confidence Threshold**: Computes an explicit multi-factor confidence score (`computeConfidence`). `--write` is refused if confidence falls below `0.70`.
|
|
19
|
+
5. **Editorial Boundary (Semantic Microcopy Refusal)**: Automated `--write` is strictly refused for semantic copy, CTA wording, or headline changes (e.g. `CRO-012`, `COMP-003`). Microcopy is a human editorial and brand judgment (fact ≠ inference).
|
|
20
|
+
6. **Rollback Snapshot**: Every `--write` automatically snapshots the target file under `.citable/remediation/snapshots/<timestamp>/` with a SHA-256 manifest before making any disk modifications.
|
|
21
|
+
|
|
22
|
+
## 2. Closed-Loop Verification (`citable verify remediation`)
|
|
23
|
+
|
|
24
|
+
Running a patch is NOT proof that a defect is resolved:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
citable verify remediation --run <run-id> --finding <id> [--target <file>] [--apply]
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
1. **Deterministic Detector Rerun**: Re-executes the exact source detector (`detector_to_rerun`) against the patched target.
|
|
31
|
+
2. **Regression Sweep**: Sweeps for newly introduced critical or high severity defects compared to the baseline run.
|
|
32
|
+
3. **Verification Envelopes**: Emits a checksum-bound before/after verification envelope conforming to `schemas/remediation-verification.schema.json`.
|
|
33
|
+
4. **Verdict Classification**:
|
|
34
|
+
* `verified`: Target detector no longer reports the defect; zero regressions introduced.
|
|
35
|
+
* `not_resolved`: Target detector still detects the condition on the patched surface.
|
|
36
|
+
* `blocked`: Prerequisite dependencies, build tools, or environments unavailable.
|
|
37
|
+
* `patch_refused`: Confidence below threshold, semantic copy gated, or syntax check failed.
|
|
38
|
+
5. **Outcome Boundary**: Resolution means the detector no longer flags the subject — **it is never an outcome guarantee of rankings, AI citations, or conversion lift**.
|
|
39
|
+
|
|
40
|
+
## 3. Customer Implementation Kits (`citable kit export`)
|
|
41
|
+
|
|
42
|
+
Produce an engineer-ready delivery kit for customer development teams:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
citable kit export --run <run-id> --finding <id> [--target <file>]
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Creates a self-contained directory containing:
|
|
49
|
+
* Verbatim finding with evidence lineage.
|
|
50
|
+
* Exact unified diff for code review.
|
|
51
|
+
* Reusable Nebula design system component template (React / Vue / HTML).
|
|
52
|
+
* Rendering-evidence manifest (real captured DOM/visual state; synthetic evidence forbidden).
|
|
53
|
+
* Acceptance test criteria and re-audit verification script.
|
|
54
|
+
* Deployment and rollback instructions.
|
|
55
|
+
* Explicit technical limitations and non-guarantee disclosures.
|
|
@@ -71,3 +71,31 @@ any observed change to a specific intervention.
|
|
|
71
71
|
authoritative index guarantees. Divergences are reported as factual observations,
|
|
72
72
|
never fabricated or interpolated.
|
|
73
73
|
|
|
74
|
+
# Enterprise Search Intelligence Briefing (`citable report search`)
|
|
75
|
+
|
|
76
|
+
1. Run `citable report search [--target <dir|url>] [--run <id>] [--format md|html|json] [--output <file>]`
|
|
77
|
+
to generate the 19-pillar Executive Search Intelligence Briefing.
|
|
78
|
+
2. Synthesizes technical crawlability, indexation, Core Web Vitals readiness,
|
|
79
|
+
AEO answer-extractability, GEO citation frequency, knowledge graph schema
|
|
80
|
+
architecture, and competitor SERP landscape into an executive document.
|
|
81
|
+
3. Every recommendation binds to a verified finding in the Evidence Register.
|
|
82
|
+
4. Facts and inferences are strictly segregated: deterministic observations are
|
|
83
|
+
reported in green data panels; strategic hypotheses and inferences are explicitly
|
|
84
|
+
labeled with confidence ratings.
|
|
85
|
+
5. Refusal boundary: Never promises rankings, algorithmic immunity, or indexing
|
|
86
|
+
guarantees.
|
|
87
|
+
|
|
88
|
+
# Enterprise CRO & Customer Journey Briefing (`citable report cro`)
|
|
89
|
+
|
|
90
|
+
1. Run `citable report cro [--target <dir|url>] [--input <file>] [--format md|html|json] [--output <file>]`
|
|
91
|
+
to generate the 25-pillar Executive Conversion & Customer Journey Briefing.
|
|
92
|
+
2. Covers end-to-end conversion paths: above-the-fold clarity, message-match
|
|
93
|
+
scoring, cognitive load, checkout friction, trust and objection analysis, offer
|
|
94
|
+
architecture, and prioritized A/B experiment blueprints.
|
|
95
|
+
3. Strictly adheres to the **Observation vs Hypothesis vs Causation** taxonomy:
|
|
96
|
+
- **Observations**: Verbatim DOM defects (e.g. missing autocomplete, undersized touch targets).
|
|
97
|
+
- **Hypotheses**: Falsifiable experiment statements with measurable primary metrics and guardrails.
|
|
98
|
+
- **Causation**: Statistical lift attribution requiring concluded, SRM-clean A/B experiments.
|
|
99
|
+
4. Refusal boundary: Revenue lift, conversion percentage improvements, and visual
|
|
100
|
+
saliency scores are modeled heuristic indices, never observed behavior or guaranteed revenue.
|
|
101
|
+
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
---
|
|
2
|
+
command: /citable sow generate [--target <dir|url>] [--run <id>] [--budget <amount>] [--budget-minor <cents>] [--format md|html|json] [--output <path>] [--sample] [--draft]
|
|
3
|
+
purpose: Generate a contractually binding, evidence-traceable enterprise Statement of Work (SOW) from verified audit findings through a formal 7-gate scope admissibility filter and 7-column traceability matrix.
|
|
4
|
+
preconditions: [at least one finalized audit run with verified findings or live target; sample mode required for synthetic demonstrations]
|
|
5
|
+
failure_behaviour: absent or unverified findings in contractual mode -> NoFindingsError; all findings refused -> NoAdmissibleRequirementsError; non-existent run -> RunNotFoundError; negative or sub-cent budget -> BudgetCalculationError; invariant drift -> SowInvariantError
|
|
6
|
+
artifacts_created: [SOW.md, SOW.html, or SOW.json at specified output path]
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Enterprise Statement of Work (SOW) Contract
|
|
10
|
+
|
|
11
|
+
The `citable sow` command generates enterprise-grade, evidence-backed Statements of Work derived from verified technical SEO, AEO, GEO, schema, and CRO audit findings. It establishes rigid, downward traceability:
|
|
12
|
+
|
|
13
|
+
```text
|
|
14
|
+
Evidence (observation envelope)
|
|
15
|
+
↓
|
|
16
|
+
Observation (deterministic DOM / HTTP probe)
|
|
17
|
+
↓
|
|
18
|
+
Finding (verified defect / friction)
|
|
19
|
+
↓
|
|
20
|
+
Recommendation (governed remediation)
|
|
21
|
+
↓
|
|
22
|
+
SOW Requirement (contractual scope)
|
|
23
|
+
↓
|
|
24
|
+
Deliverable (code patch / AST modification)
|
|
25
|
+
↓
|
|
26
|
+
Acceptance Test (automated closed-loop detector rerun)
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## 1. Operating Premises & Commercial Disclaimers
|
|
30
|
+
|
|
31
|
+
1. **Fee Binding**: Supplier fees are bound exclusively to verified deliverable acceptance and closed-loop test execution.
|
|
32
|
+
2. **Strict Outcome Disclaimers**: In strict compliance with Citable governance principles, **no search engine crawling, indexation, ranking, AI answer citation, or conversion revenue is guaranteed**.
|
|
33
|
+
3. **No Synthetic Data in Contracts**: Attempting to generate a `CONTRACTUAL` SOW without verified empirical findings immediately fails closed with `NoFindingsError`. Synthetic findings are strictly confined to `--sample` / `--demo`.
|
|
34
|
+
|
|
35
|
+
## 2. The Scope Admissibility Gate
|
|
36
|
+
|
|
37
|
+
Audit findings do NOT automatically become contractual obligations. Every candidate finding must pass 7 admissibility gates:
|
|
38
|
+
|
|
39
|
+
| Gate | Verification Check | Failure Refusal Code | Contractual Handling |
|
|
40
|
+
| :--- | :--- | :--- | :--- |
|
|
41
|
+
| **1. Exclusion Gate** | Check against explicit excluded detectors list | `REFUSE-EXCLUDED` | Track in internal backlog; execute under separate advisory engagement. |
|
|
42
|
+
| **2. Discipline Authorization** | Check if discipline is authorized under contract | `REFUSE-DISCIPLINE-NOT-AUTHORIZED` | Expand authorized disciplines in SOW engagement terms or contract under separate SOW. |
|
|
43
|
+
| **3. Evidence Maturity** | Require deterministic/observed confidence & evidence | `REFUSE-EXPERIMENTAL` / `REFUSE-NO-EVIDENCE` | Run controlled observation probes before considering for contractual obligation. |
|
|
44
|
+
| **4. Scope Boundary** | Verify URL matches authorized host, subdomain, or path | `REFUSE-OUT-OF-SCOPE` | Escalate domain ownership verification or expand contractual executive scope. |
|
|
45
|
+
| **5. Feasibility Gate** | Reject legal, trademark, GDPR, or unfeasible remediation | `REFUSE-UNFEASIBLE-REMEDIATION` | Refer to specialized legal or compliance counsel outside scope. |
|
|
46
|
+
| **6. Materiality Gate** | Require critical/high severity or ICE score >= threshold | `REFUSE-LOW-MATERIALITY` | Log to internal product maintenance backlog; omit from high-value SOW. |
|
|
47
|
+
| **7. Acceptance Gate** | Require automated rerun detector or objective pass/fail test | `REFUSE-UNVERIFIABLE` | Define deterministic verification criteria before adding to scope. |
|
|
48
|
+
| **8. Ownership Clarity** | Resolve accountable owner from finding or role mappings | `REFUSE-OWNER-UNRESOLVED` | Specify delivery_owner on finding or map discipline to accountable role. |
|
|
49
|
+
|
|
50
|
+
All refused findings are recorded in the SOW's `admissibility_gate.refusal_log` with standard refusal codes and contractual handling guidance.
|
|
51
|
+
|
|
52
|
+
## 3. The 7-Column Traceability Matrix
|
|
53
|
+
|
|
54
|
+
Every admitted requirement must satisfy complete 7-column bidirectional traceability:
|
|
55
|
+
|
|
56
|
+
1. **Finding ID**: Verbatim identifier of the empirical defect (e.g. `F-TECH-001`).
|
|
57
|
+
2. **Recommendation**: Governed, safe remediation instruction.
|
|
58
|
+
3. **SOW Requirement ID**: Contractual clause identifier (`REQ-SOW-001`).
|
|
59
|
+
4. **Deliverable ID**: Accountable work package deliverable (`DELIV-01`).
|
|
60
|
+
5. **Acceptance Test ID**: Automated closed-loop test (`ACC-TEST-001`).
|
|
61
|
+
6. **Responsible Owner**: Named lead dev, architect, or agency practice owner.
|
|
62
|
+
7. **Source Evidence IDs**: Array of cryptographic observation IDs (`['EVD-CWV-001']`).
|
|
63
|
+
|
|
64
|
+
## 4. Commercial Currency & Minor-Unit Semantics
|
|
65
|
+
|
|
66
|
+
To eliminate commercial fee drift and rounding leaks, all internal calculations use exact **integer minor units (cents, exponent 2, currency `USD`)**:
|
|
67
|
+
|
|
68
|
+
* `currency`: Declared as `USD`.
|
|
69
|
+
* `currency_minor_unit_exponent`: Declared as `2`.
|
|
70
|
+
* `commercial_total_fee_minor`: Integer cents (e.g. `$50,000.00` = `5000000` cents).
|
|
71
|
+
* `milestones[].fee_minor`: Integer floor allocation across milestones with remainder pennies distributed deterministically to initial milestones.
|
|
72
|
+
* `commercial_total_fee_usd` / `milestones[].fee_usd`: Derived dollar representation formatted at presentation boundaries (`$33.34`, `$50,000`).
|
|
73
|
+
* Sub-cent fractional budgets (`100.001`) and negative budgets are strictly rejected.
|
|
74
|
+
|
|
75
|
+
## 5. Generation Modes & Machine-Readable Provenance
|
|
76
|
+
|
|
77
|
+
Every generated SOW embeds an immutable `generation_provenance` block:
|
|
78
|
+
|
|
79
|
+
* **`CONTRACTUAL`**: Generated from verified historical run findings or live target; synthetic evidence forbidden.
|
|
80
|
+
* **`DRAFT`**: Generated with preliminary scope or unfinalized commercial terms; requires executive sign-off.
|
|
81
|
+
* **`NON_CONTRACTUAL_SAMPLE`**: Generated with synthetic baseline findings strictly for evaluation/demo (`--sample`).
|
|
82
|
+
|
|
83
|
+
Provenance tracks:
|
|
84
|
+
* `generator_version`: Exact Citable semver.
|
|
85
|
+
* `generated_at`: ISO 8601 timestamp.
|
|
86
|
+
* `source_type`: `HISTORICAL_RUN`, `LIVE_INSPECTION`, `DIRECT_FINDINGS`, or `SAMPLE_BASELINE`.
|
|
87
|
+
* `source_identifier`: Target URL, run ID, or sample identifier.
|
|
88
|
+
* `source_findings_count`: Integer count of evaluated findings.
|
|
89
|
+
* `findings_integrity_hash`: SHA-256 hash of input findings.
|
|
90
|
+
|
|
91
|
+
## 6. SOW Verification Command
|
|
92
|
+
|
|
93
|
+
Run `citable sow validate <sow.json>` to verify:
|
|
94
|
+
1. Strict schema compliance against `schemas/sow.schema.json` (`additionalProperties: false`).
|
|
95
|
+
2. Cross-object invariants via `validateSowInvariants` (fee balancing, work package and deliverable parity, non-empty evidence links).
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "citable",
|
|
3
|
-
"version": "1.18.
|
|
3
|
+
"version": "1.18.1",
|
|
4
4
|
"managedBy": "citable-cli",
|
|
5
5
|
"provider": "trae-cn",
|
|
6
6
|
"providerName": "Trae CN",
|
|
7
7
|
"scope": "bundle",
|
|
8
|
-
"sourcePackage": "@nebulacomponents/citable@1.18.
|
|
8
|
+
"sourcePackage": "@nebulacomponents/citable@1.18.1",
|
|
9
9
|
"variantPath": ".trae-cn/skills/citable",
|
|
10
10
|
"agentProfiles": {
|
|
11
11
|
"status": "unsupported",
|
|
@@ -13,7 +13,9 @@
|
|
|
13
13
|
},
|
|
14
14
|
"files": {
|
|
15
15
|
"agents/citable-auditor.md": "sha256:06fe8d84834b2c09b7e7083aa6f57e94e837e0643dbe4ead4bbecf651fb41cad",
|
|
16
|
+
"agents/citable-remediator.md": "sha256:c990e929f411fc2f2de3aca759333502c956e96924b3a0f809ab0927062623dc",
|
|
16
17
|
"agents/citable-semantic-reviewer.md": "sha256:77582263a048ea41ae3f7ee326dbd036222fab81ed83bda98034ec83ee21ef2e",
|
|
18
|
+
"agents/citable-sow-architect.md": "sha256:d55cf8bc2ab8f364c0d95ec39fc44406684110d1e4d1ff2e34702ded003094b4",
|
|
17
19
|
"commands/action-findings.md": "sha256:b1d5c4d8d8b1092bc73b99430bea0a2e460031658e42bed33eb94da9a3c0e48f",
|
|
18
20
|
"commands/artifact-interchange.md": "sha256:18d56fbfa6bb3f23f08593a9a8135e51c268618b049e53c793969b68000875c3",
|
|
19
21
|
"commands/delivery.md": "sha256:3b29250f9e9f84442812e320a70d5d2784b4286e91af3866f99cb6062a85a10f",
|
|
@@ -26,9 +28,11 @@
|
|
|
26
28
|
"commands/optimize-page.md": "sha256:35866f3d7cdeef0376ea7a7d7036085a9b9cf95bbb300ecf4bd77610ebd74d85",
|
|
27
29
|
"commands/page-work.md": "sha256:965a66e59bdf7b0da482d26fade53b3d265885ece5d463fe83b0789ebefaef3e",
|
|
28
30
|
"commands/plan-audit.md": "sha256:69875c9654e13b84566dafb16afe5afe08cffb9f3bded1f2d8d2261ae871c869",
|
|
29
|
-
"commands/README.md": "sha256:
|
|
30
|
-
"commands/
|
|
31
|
+
"commands/README.md": "sha256:683b226020582dd93e24a2fb59ce6264735f44eb26353f977153034a615f871c",
|
|
32
|
+
"commands/remediation.md": "sha256:7f983ecf63ec6741fa7e291243c6faeb44a5b140655a5ec3a62bcbc4c16d8870",
|
|
33
|
+
"commands/reporting.md": "sha256:f560f3c8349fcdaf6d3c3a27968016e20ef42ef2473292f7b83260cfb4b3b2e6",
|
|
31
34
|
"commands/reviews.md": "sha256:902904aaa405fe5724cf0662c7a5a36eab9a4fe0eb81cbd95ffa2fff946e0ac8",
|
|
35
|
+
"commands/sow.md": "sha256:576c0ff119e5a9193476c20aee65019dbe91502d624d3a8fc8469915a3bc2b19",
|
|
32
36
|
"commands/validate-render.md": "sha256:a8e1d04d40b84d57c35039250d98c6a7302cd44a148a8c3b9d9cfb92678c4347",
|
|
33
37
|
"policies/crawler-policy-template.md": "sha256:15c88a4eeb21f53f71e5250dd3eb2d2791a814b304eaefce8bb30e2bdf2e2e59",
|
|
34
38
|
"references/aeo-geo-validation.md": "sha256:4b0041764f2fdbfbff1e1a2907eaed02cf0aef491254a9c98ec9250ff1084e80",
|
|
@@ -108,12 +112,12 @@
|
|
|
108
112
|
"schemas/scenario.schema.json": "sha256:3f5bc2032d08f973600db068f475176a0e4706b33be42f99c778fe755a0ff38b",
|
|
109
113
|
"schemas/schedule.schema.json": "sha256:645df065bf33577a960c0bf8bb97e141e9326840303569468dae8a553d468482",
|
|
110
114
|
"schemas/source-identity-chain.schema.json": "sha256:a65d9c12eaed1bd6b637c66a2f9362c17287fdfcb454d8676fb611d2d28aa019",
|
|
111
|
-
"schemas/sow.schema.json": "sha256:
|
|
115
|
+
"schemas/sow.schema.json": "sha256:14ff2e24e03f678d3c72f97c27b0a68e117472dcc640aab7491bba1a82457906",
|
|
112
116
|
"schemas/variance.schema.json": "sha256:68389f64f0a3be13ff8951e8eefba9a5c31d0738325cb47e37c1a8435bea48f0",
|
|
113
117
|
"scripts/README.md": "sha256:9eee4e8beb4579a183bd714c9dd24b83abd020753eada5caeffae004739d60b5",
|
|
114
|
-
"SKILL.md": "sha256:
|
|
118
|
+
"SKILL.md": "sha256:d50cc48a120fee6ad3c3bf0d1bfa8ceb5bba3614bdc6af8aacc4293b9e4a1970",
|
|
115
119
|
"templates/finding-review.md": "sha256:b270a83d3f015150aac80249ae9314979c0befea39ff92ec455f9a5aaa73404c",
|
|
116
|
-
"VERSION": "sha256:
|
|
120
|
+
"VERSION": "sha256:71fc7bd16b1bc9b3681085fb0be8aea0b3a37d90d1685938dc2e8a31bf8c9b94"
|
|
117
121
|
},
|
|
118
|
-
"treeHash": "sha256:
|
|
122
|
+
"treeHash": "sha256:96d4589fced40f7030b6c1e48132abf2d37ebae771a1401d6f2a74e4f8fc52d1"
|
|
119
123
|
}
|