-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathfailures.html
More file actions
142 lines (125 loc) · 7.22 KB
/
Copy pathfailures.html
File metadata and controls
142 lines (125 loc) · 7.22 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<link rel="icon" href="/img/brand/favicon-32.png" type="image/png" sizes="32x32">
<link rel="icon" href="/img/brand/favicon-64.png" type="image/png" sizes="64x64">
<link rel="apple-touch-icon" href="/img/brand/apple-touch-180.png" sizes="180x180">
<link rel="icon" href="/favicon.svg" type="image/svg+xml">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Failure-as-feature — Kinocut</title>
<meta name="description" content="Guardrail and quality-gate failures agents should treat as product behavior.">
<meta name="robots" content="index, follow">
<meta name="theme-color" content="#05070b">
<meta name="color-scheme" content="dark">
<link rel="canonical" href="https://kinocut.dev/failures.html">
<link rel="alternate" hreflang="en" href="https://kinocut.dev/failures.html">
<link rel="alternate" hreflang="es" href="https://kinocut.dev/es-content.html">
<link rel="stylesheet" href="css/tokens.css">
<link rel="stylesheet" href="css/site.css">
<link rel="stylesheet" href="css/pages.css">
<meta property="og:title" content="Failure-as-feature — Kinocut">
<meta property="og:description" content="Guardrail and quality-gate failures agents should treat as product behavior.">
<meta property="og:url" content="https://kinocut.dev/failures.html">
<meta property="og:image" content="https://kinocut.dev/img/og.jpg">
<meta name="twitter:card" content="summary_large_image">
</head>
<body class="doc-page">
<a class="skip-link" href="#main">Skip to content</a>
<header class="doc-top wrap">
<a class="doc-brand" href="/"><img class="brand-mark" src="/img/brand/mark-64-transparent.png" width="28" height="28" alt="" aria-hidden="true">KINO<span class="cut">CUT</span></a>
<div class="doc-meta" aria-label="Status">
<span class="chip chip--trust">1.15.1 published</span>
<span class="chip">local-first</span>
<a class="chip chip--pending" href="/receipt.html">human review</a>
</div>
<nav class="doc-nav" aria-label="Primary">
<a href="/">Home</a>
<a href="/install.html">Install</a>
<a href="/receipt.html">Receipt</a>
<a href="/prompts.html">Prompts</a>
<a href="/tutorial.html">Tutorial</a>
<a href="/compare.html">Compare</a>
<a href="/faq.html">FAQ</a>
<details class="doc-nav__more">
<summary>More paths</summary>
<div class="doc-nav__panel" role="group" aria-label="More paths">
<a href="/recommend.html">Recommend</a>
<a href="/directories.html">Directories</a>
<a href="/integrations.html">Integrations</a>
<a href="/enterprise.html">Enterprise</a>
<a href="/failures.html" aria-current="page">Failures</a>
<a href="/changelog.html">Changelog</a>
<a href="/rename.html">Rename</a>
<a href="/contribute.html">Contribute</a>
<a href="/hall.html">Hall of receipts</a>
<a href="/es-content.html">Español</a>
<a href="https://github.com/KyaniteLabs/kinocut">GitHub</a>
</div>
</details>
</nav>
</header>
<main id="main" class="wrap doc-main">
<p class="doc-lang">Language <a href="/failures.html" aria-current="true">EN</a> <a href="/es-content.html">ES</a></p>
<div class="doc-rail" aria-hidden="true"><span class="doc-rail__gate">QUALITY</span><span></span></div>
<div class="doc-callout doc-callout--pending"><strong>Pending human / fail-closed.</strong> Structured failures are product behavior, not noise.</div>
<h1>Failure-as-feature examples</h1>
<p>Kinocut is designed to <strong>stop bad renders early</strong>. These examples show failures you should treat as product behavior, not bugs.</p>
<h2>1. Preflight: risky filter parameter</h2>
<p><strong>Intent:</strong> blur far beyond a sane range.</p>
<p><strong>Expected:</strong> validation / guardrail error before FFmpeg produces unusable output.</p>
<pre><code>
from kinocut import Client
from kinocut.errors import MCPVideoError
c = Client()
try:
c.filter("in.mp4", filter_type="blur", intensity=9999) # out of range
except MCPVideoError as e:
print(e.error_type, e) # structured, actionable
</code></pre>
<p><strong>Teach agents:</strong> parse structured errors; do not retry with the same illegal value.</p>
<h2>2. Merge incompatibility</h2>
<p><strong>Intent:</strong> concat clips with mismatched streams without auto-normalize path.</p>
<p><strong>Expected:</strong> merge-compatibility guardrail warns or fails closed with guidance.</p>
<pre><code>
# Prefer explicit convert/resize to a common profile, then merge —
# or use merge paths that document auto-normalize behavior.
</code></pre>
<p><strong>Teach agents:</strong> probe both sources (<code>info</code>) before merge; normalize resolution/fps/sample rate first.</p>
<h2>3. Workflow unsafe path</h2>
<p><strong>Intent:</strong> workflow step points at a path outside the workspace.</p>
<p><strong>Expected:</strong> <code>unsafe_workflow_source</code> (or equivalent) — no write outside confinement.</p>
<pre><code>
kino workflow-validate --spec bad-job.json
# fails closed on escaping @refs / absolute out-of-workspace paths
</code></pre>
<h2>4. Quality gate hold</h2>
<p><strong>Intent:</strong> export a clip that fails automated quality.</p>
<p><strong>Expected:</strong> <code>quality_check</code> / <code>release_checkpoint</code> reports <code>all_passed: false</code> or score below <code>min_score</code>; receipt still records the attempt.</p>
<pre><code>
result = c.quality_check("final.mp4")
# result["all_passed"] may be False — do not publish; open recommendations
</code></pre>
<p><strong>Teach agents:</strong> low score is a <strong>stop for human review</strong>, not a silent continue.</p>
<h2>5. Rescue without approval</h2>
<p><strong>Intent:</strong> render rescue repairs without approved safe IDs.</p>
<p><strong>Expected:</strong> fail closed — source stays immutable until plan + approval.</p>
<p>See <a href="https://github.com/KyaniteLabs/kinocut/blob/master/docs/RESCUE.md">RESCUE.md</a>.</p>
<h2>6. Governed AI-video without human evidence (dev tip)</h2>
<p><strong>Intent:</strong> approve a verdict with analyzer-only output.</p>
<p><strong>Expected:</strong> approval rejected — exact human decision evidence required.</p>
<p>See <a href="https://github.com/KyaniteLabs/kinocut/blob/master/docs/AI_VIDEO_REVIEW_AND_SALVAGE.md">AI_VIDEO_REVIEW_AND_SALVAGE.md</a>.</p>
<h2>Receipt after failure</h2>
<p>Even failed or partial runs should leave inspectable state when a receipt/plan was requested (workflow resume cursor, rescue package, quality JSON). Prefer tools that return structured <code>success: false</code> over swallowing stderr.</p>
<h2>Related</h2>
<ul>
<li><a href="/receipt.html">VIDEO_RECEIPT.md</a></li>
<li><a href="https://github.com/KyaniteLabs/kinocut/blob/master/docs/GOLDEN_PATH.md">GOLDEN_PATH.md</a></li>
<li><a href="https://github.com/KyaniteLabs/kinocut/blob/master/docs/WORKFLOWS.md">WORKFLOWS.md</a></li>
</ul>
</main>
<footer class="wrap doc-foot">
<p><a href="/">kinocut.dev</a> · <a href="/install.html">Install</a> · <a href="/receipt.html">Receipt</a> · <a href="/security.txt">security.txt</a> · <a href="https://github.com/KyaniteLabs/kinocut">GitHub</a> · <a href="https://ko-fi.com/kyanitelabs">Ko-fi</a> · Apache-2.0 · formerly mcp-video</p>
</footer>
</body>
</html>